@fabrika/platform 0.3.2 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/platform",
-	"version": "0.3.2",
+	"version": "0.4.0",
 	"type": "module",
 	"repository": {
 		"type": "git",

package/src/index.ts

@@ -9,6 +9,18 @@
 // Runtime-specific implementations live with the workers that use them, or in @fabrika/platform-node.
 
 export { SqlDeployLocks, type SqlDeployLocksOptions } from './deploy-locks-sql'
-export type { AssetServer, BlobStore, DeployLocks, HttpService, JobQueue, WaitUntil } from './ports'
+export { ObjectExistsError, ObjectTooLargeError } from './ports'
+export type {
+	AssetServer,
+	BlobStore,
+	DeployLocks,
+	FileObjectStore,
+	HttpService,
+	JobQueue,
+	ObjectMetadata,
+	ObjectWriteOptions,
+	StoredObject,
+	WaitUntil,
+} from './ports'
 export type { SqlDatabase, SqlQueryResult, SqlRunResult, SqlStatement } from './sql'
 export { uuidv7 } from './uuid'

package/src/ports.ts

@@ -16,6 +16,65 @@ export interface BlobStore {
 	delete(key: string): Promise<void>
 }
 
+/** What the store recorded for an object. `contentType` is what the writer declared, or null. */
+export interface ObjectMetadata {
+	readonly size: number
+	readonly contentType: string | null
+}
+
+export interface StoredObject extends ObjectMetadata {
+	/** One stream, consumable once. */
+	readonly body: ReadableStream<Uint8Array>
+	/** These exact bytes' version, from the same answer as the body: an S3 ETag. It changes when the object is replaced. */
+	readonly version: string
+}
+
+export interface ObjectWriteOptions {
+	readonly contentType: string
+	/** The most bytes the object may have. The write stops reading `body` once more arrive. */
+	readonly maxBytes: number
+}
+
+/** A write named a key that already holds an object: a file's object is written once. Read by `name`. */
+export class ObjectExistsError extends Error {
+	override readonly name = 'ObjectExistsError'
+
+	constructor() {
+		super('an object is already stored under this key')
+	}
+}
+
+/** The body of a write was longer than its `maxBytes`. Read by `name`, never by a cross-package `instanceof`. */
+export class ObjectTooLargeError extends Error {
+	override readonly name = 'ObjectTooLargeError'
+	readonly maxBytes: number
+
+	constructor(maxBytes: number) {
+		super(`the object is larger than ${maxBytes} bytes`)
+		this.maxBytes = maxBytes
+	}
+}
+
+/**
+ * The objects of an application's file collections (S3/MinIO). Separate from `BlobStore` because its callers
+ * need a size bound enforced while the bytes stream and the metadata read back; an R2 adapter that ignored
+ * either would silently drop a limit.
+ */
+export interface FileObjectStore {
+	/**
+	 * Streams `body` to a new `key`. A key that already holds an object is refused with `ObjectExistsError`, and nothing
+	 * is written. Past `options.maxBytes` it stops reading, keeps nothing under `key` and rejects with
+	 * `ObjectTooLargeError`. Any other failure also leaves nothing stored.
+	 */
+	write(key: string, body: ReadableStream<Uint8Array>, options: ObjectWriteOptions): Promise<ObjectMetadata>
+	/** The object with its metadata and version, in one answer, or `null` for a missing key. `signal` stops it. */
+	read(key: string, signal?: AbortSignal): Promise<StoredObject | null>
+	/** The object only while it is still `version`, in one answer; `null` when it is missing or was replaced. */
+	readVersion(key: string, version: string, signal?: AbortSignal): Promise<StoredObject | null>
+	/** Idempotent: a missing key is not an error. */
+	delete(key: string): Promise<void>
+}
+
 /** Enqueue a deploy job. The CONSUMER side is platform-specific and deliberately not modelled here. */
 export interface JobQueue<T> {
 	send(message: T, options?: { delaySeconds?: number }): Promise<void>

package/src/testing.ts

@@ -1,4 +1,13 @@
-import type { BlobStore, JobQueue } from './ports'
+import {
+	type BlobStore,
+	type FileObjectStore,
+	type JobQueue,
+	ObjectExistsError,
+	type ObjectMetadata,
+	ObjectTooLargeError,
+	type ObjectWriteOptions,
+	type StoredObject,
+} from './ports'
 import type { SqlDatabase } from './sql'
 
 /** A blob store that keeps string values in memory. */
@@ -23,6 +32,65 @@ export class MemoryBlobs implements BlobStore {
 	}
 }
 
+/** A file object store in memory, with the port's size bound enforced while the body streams. */
+export class MemoryFileObjects implements FileObjectStore {
+	readonly objects = new Map<string, { readonly bytes: Uint8Array<ArrayBuffer>; readonly contentType: string; readonly version: string }>()
+	#writes = 0
+
+	async write(key: string, body: ReadableStream<Uint8Array>, options: ObjectWriteOptions): Promise<ObjectMetadata> {
+		const reader = body.getReader()
+		if (this.objects.has(key)) {
+			await reader.cancel()
+			throw new ObjectExistsError()
+		}
+		const chunks: Uint8Array[] = []
+		let size = 0
+		for (let next = await reader.read(); !next.done; next = await reader.read()) {
+			size += next.value.byteLength
+			if (size > options.maxBytes) {
+				await reader.cancel()
+				throw new ObjectTooLargeError(options.maxBytes)
+			}
+			chunks.push(next.value)
+		}
+		const bytes = new Uint8Array(size)
+		let offset = 0
+		for (const chunk of chunks) {
+			bytes.set(chunk, offset)
+			offset += chunk.byteLength
+		}
+		this.replace(key, bytes, options.contentType)
+		return { size, contentType: options.contentType }
+	}
+
+	/** Puts `bytes` under `key` whatever it held, under a new version: what a write outside the upload path does. */
+	replace(key: string, bytes: Uint8Array<ArrayBuffer>, contentType = 'application/octet-stream'): void {
+		this.#writes++
+		this.objects.set(key, { bytes, contentType, version: `"memory-${this.#writes}"` })
+	}
+
+	read(key: string): Promise<StoredObject | null> {
+		const object = this.objects.get(key)
+		if (object === undefined) return Promise.resolve(null)
+		return Promise.resolve({
+			size: object.bytes.byteLength,
+			contentType: object.contentType,
+			version: object.version,
+			body: new Blob([object.bytes]).stream(),
+		})
+	}
+
+	async readVersion(key: string, version: string): Promise<StoredObject | null> {
+		const object = await this.read(key)
+		return object?.version === version ? object : null
+	}
+
+	delete(key: string): Promise<void> {
+		this.objects.delete(key)
+		return Promise.resolve()
+	}
+}
+
 /** A queue that records every sent message. */
 export class MemoryQueue<T> implements JobQueue<T> {
 	readonly messages: T[] = []