Storage contract

What a storage adapter implements, as @genoacms/contracts/storage declares it. How an adapter is shaped and registered is under adapters .

Concurrent writes

The only write an object store offers is replace the whole object. Two writers who both read an object and both write it back produce a lost update: the second silently erases the first, and nothing records that it happened. GenoaCMS stores mutable documents — page trees, component definitions, its own manifests — this way, so the contract addresses it directly.

Version tokens

getObject returns a version alongside the data, and uploadObject can require it:

const { data, version } = await getObject(reference)
// ...modify...
await uploadObject(reference, updated, { ifVersion: version })
ts

If the object changed after it was read, the write is refused rather than applied. ifAbsent: true is the other form — write only if the object does not exist, which lets any number of racing callers create something while exactly one succeeds.

A refused write raises PreconditionFailedError:

import { isPreconditionFailed } from '@genoacms/contracts/storage'

try {
  await uploadObject(reference, updated, { ifVersion: version })
} catch (error) {
  if (!isPreconditionFailed(error)) throw error
  // Someone else wrote first. Re-read and decide.
}
ts
Do not retry blindly

A rejected conditional write means someone else's change is now in the object. Replaying the write over it reintroduces the lost update the condition existed to prevent. Re-read, and where a person authored the change, tell them there is a conflict.

The token is opaque

ObjectVersion is a GCS generation on one adapter and an S3 etag on another. It is not a number, a timestamp or an ordering — it may only be handed back to uploadObject. Code that compares or sorts versions works against one provider and fails subtly against the next.

version may be absent when an adapter cannot supply one. That removes the ability to write conditionally against that object; it does not make the read invalid.

There are no transactions

Object storage provides no cross-object atomicity. Neither S3, GCS nor MinIO exposes an API that commits several objects together or rolls them back, and nothing above the adapter can supply the guarantee — a sequence of writes can always be interrupted part-way.

GenoaCMS therefore does not offer a transaction API. An interface named for a guarantee it cannot provide is worse than its absence, because callers rely on the name. Where several objects must change together, design so that each write is independently valid, and use ifVersion to detect that the world moved underneath you.

Types

type ObjectName = string

interface ObjectReference {
  bucket: string
  name: ObjectName
}

interface StorageObject {
  name: string
  size: number
  lastModified: Date
}

/**
 * Adapters accept a string or buffer as readily as a stream, and the CMS writes its own JSON
 * documents as strings. The declaration previously named only the stream, which every internal
 * write then contradicted.
 */
type ObjectPayload = string | Buffer | NodeJS.ReadableStream

/**
 * An opaque token identifying one version of an object — a GCS generation, an S3 or MinIO etag.
 *
 * **Opaque on purpose.** These are not comparable, orderable, or meaningful across providers;
 * treating a version as a number or a timestamp would produce code that works against one adapter
 * and fails subtly against another. It may only be passed back to `uploadObject`.
 */
type ObjectVersion = string

interface UploadOptions {
  /**
   * Write only if the object still has this version. A stale token is rejected rather than
   * overwriting, which is what prevents one writer silently erasing another's update.
   */
  ifVersion?: ObjectVersion
  /** Write only if the object does not exist. Exactly one of any number of racing callers wins. */
  ifAbsent?: boolean
}

interface ObjectData {
  data: NodeJS.ReadableStream
  /**
   * The version read, for passing to a later conditional write. Absent when the adapter cannot
   * supply one, in which case `ifVersion` cannot be used against that object.
   */
  version?: ObjectVersion
}

interface DirectoryListingParams {
  startAfter?: string
  limit?: number
  /** The `next` of the page before, to continue a listing. */
  pageToken?: string
}

interface DirectoryContents {
  files: StorageObject[]
  directories: ObjectReference[]
  /** Present while the store has more entries after this page; opaque, only passed back as `pageToken`. */
  next?: string
}

export type {
  ObjectName,
  ObjectReference,
  StorageObject,
  ObjectPayload,
  ObjectVersion,
  UploadOptions,
  ObjectData,
  DirectoryListingParams,
  DirectoryContents
}
ts
Expand code

Adapter

import type {
  ObjectName,
  ObjectReference,
  ObjectPayload,
  ObjectData,
  DirectoryListingParams,
  DirectoryContents
} from './types.d.ts'

type getObject = (reference: ObjectReference) => Promise<ObjectData>
type getSignedURL = (reference: ObjectReference, expires: Date) => Promise<string>
type getPublicURL = (reference: ObjectReference) => Promise<string>
type uploadObject = (reference: ObjectReference, data: ObjectPayload, options: UploadOptions) => Promise<void>
type moveObject = (reference: ObjectReference, destination: ObjectName) => Promise<void>
type deleteObject = (reference: ObjectReference) => Promise<void>
type listDirectory = (reference: ObjectReference, params?: DirectoryListingParams) => Promise<DirectoryContents>
type createDirectory = (reference: ObjectReference) => Promise<void>
type deleteDirectory = (reference: ObjectReference) => Promise<void>
type moveDirectory = (reference: ObjectReference, destination: ObjectName) => Promise<void>

interface Adapter {
  getObject: getObject
  getSignedURL: getSignedURL
  getPublicURL: getPublicURL
  uploadObject: uploadObject
  moveObject: moveObject
  deleteObject: deleteObject
  listDirectory: listDirectory
  createDirectory: createDirectory
  deleteDirectory: deleteDirectory
  moveDirectory: moveDirectory
}

export default Adapter
ts
Expand code

create receives the buckets bound to the provider as ctx.resources; a call naming any other bucket is refused.

Errors

import type Adapter from './adapter.d.ts'

/**
 * Raised when a conditional write (`ifVersion` / `ifAbsent`) was refused because the object was not
 * in the expected state. An ordinary outcome of losing a race, not a fault.
 */
declare class PreconditionFailedError extends Error {
  readonly reference: import('./types.d.ts').ObjectReference
  readonly reason: string
  constructor (reference: import('./types.d.ts').ObjectReference, reason: string)
}

declare function isPreconditionFailed (error: unknown): boolean

/** Raised when `getObject` or `deleteObject` is given an object that does not exist. */
declare class ObjectNotFoundError extends Error {
  readonly name: 'ObjectNotFoundError'
  readonly reference: import('./types.d.ts').ObjectReference
  constructor (reference: import('./types.d.ts').ObjectReference)
}

declare function isNotFound (error: unknown): boolean

/** Raised when a directory method is given a name that is neither `''` nor ends in `/`. */
declare class NotADirectoryError extends Error {
  readonly name: 'NotADirectoryError'
  readonly reference: import('./types.d.ts').ObjectReference
  constructor (reference: import('./types.d.ts').ObjectReference)
}

declare function isDirectoryName (name: string): boolean

export {
  PreconditionFailedError,
  isPreconditionFailed,
  ObjectNotFoundError,
  isNotFound,
  NotADirectoryError,
  isDirectoryName
}

export type {
  Adapter
}
export type {
  ObjectReference,
  StorageObject,
  ObjectPayload,
  UploadOptions,
  ObjectData,
  DirectoryListingParams,
  DirectoryContents
} from './types.d.ts'
ts
Expand code