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 }) 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.
} 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.
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
} 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 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'