@springbrand/space 0.2.0-alpha.1 → 0.2.0-alpha.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@springbrand/space",
-  "version": "0.2.0-alpha.1",
+  "version": "0.2.0-alpha.10",
   "type": "module",
   "files": [
     "src",

package/src/index.ts

@@ -9,6 +9,7 @@ export type {
   AppTableQueryOpts,
   SpaceCommit,
   SpaceConditionalWriteResult,
+  SpaceStreamWriteOptions,
   SpaceAppPort,
   SpaceControlPort,
   SpaceFileInfo,

package/src/space/durable-object.ts

@@ -30,6 +30,7 @@ import {
   type SpaceCommit,
   type SpaceCommitManifest,
   type SpaceConditionalWriteResult,
+  type SpaceStreamWriteOptions,
   type SpaceAppPort,
   type SpaceControlPort,
   type SpaceFileInfo,
@@ -48,6 +49,7 @@ export type {
   SpaceCommit,
   SpaceCommitManifest,
   SpaceConditionalWriteResult,
+  SpaceStreamWriteOptions,
   SpaceControlPort,
   SpaceFileInfo,
   SpaceFileVersion,
@@ -257,6 +259,21 @@ export class SpaceDO extends DurableObject<Env>
     }
   }
 
+  private async streamedFileLimit(path: string): Promise<number> {
+    const quota = defaultSpaceQuota()
+    const existing = await this.statInfo(path)
+    const usage = await this.usageOf()
+    if (quota.maxFiles !== null && !existing && usage.fileCount >= quota.maxFiles) {
+      throw new Error("Space file count quota exceeded")
+    }
+    return Math.max(0, Math.min(
+      quota.maxFileBytes ?? Number.MAX_SAFE_INTEGER,
+      quota.maxTotalBytes === null
+        ? Number.MAX_SAFE_INTEGER
+        : quota.maxTotalBytes - usage.totalBytes + (existing?.size ?? 0),
+    ))
+  }
+
   private async usageOf(): Promise<SpaceUsage> {
     let fileCount = 0
     let directoryCount = 0
@@ -663,6 +680,44 @@ export class SpaceDO extends DurableObject<Env>
     await this.fs.writeFileBytes(target, bytes)
   }
 
+  async writeFileStream(
+    path: string,
+    content: ReadableStream<Uint8Array>,
+    options?: SpaceStreamWriteOptions,
+  ): Promise<{ path: string; bytes: number }> {
+    return this.lane(async () => {
+      await this.ensureInit()
+      const target = normalizeWritableSpacePath(path)
+      const expected = options?.contentLength
+      if (expected !== undefined && (!Number.isSafeInteger(expected) || expected < 0)) {
+        throw new Error("Stream contentLength must be a non-negative safe integer")
+      }
+      const limit = await this.streamedFileLimit(target)
+      if (expected !== undefined && expected > limit) {
+        throw new Error(`Space file exceeds the ${limit}-byte limit: ${target}`)
+      }
+      let bytes = 0
+      const counted = content.pipeThrough(new TransformStream<Uint8Array, Uint8Array>({
+        transform(chunk, controller) {
+          bytes += chunk.byteLength
+          if (bytes > limit) throw new Error(`Space file exceeds the ${limit}-byte limit: ${target}`)
+          controller.enqueue(chunk)
+        },
+        flush() {
+          if (expected !== undefined && bytes !== expected) {
+            throw new Error("Stream did not match declared contentLength")
+          }
+        },
+      }))
+      await this.backend.writeFileStream(
+        target,
+        counted,
+        options?.mediaType ?? "application/octet-stream",
+      )
+      return { path: target, bytes }
+    })
+  }
+
   async appendFile(path: string, content: string, mimeType?: string): Promise<void> {
     void mimeType
     await this.ensureInit()

package/src/space/fs-backend.ts

@@ -47,6 +47,7 @@ export interface SpaceFsBackend {
   ready(): Promise<void>
   hydrate(path: string): Promise<void>
   materializeAll(): Promise<void>
+  writeFileStream(path: string, content: ReadableStream<Uint8Array>, mediaType: string): Promise<void>
   flushCheckpoint(): Promise<void>
   push(branch: string): Promise<boolean>
   fetch(branch: string): Promise<void>
@@ -134,6 +135,10 @@ export class ArtifactsBackend implements SpaceFsBackend {
     await (this.fs as ArtifactsFileSystem).whenFullyMaterialized()
   }
 
+  async writeFileStream(): Promise<void> {
+    throw new Error("Streaming writes require the SQL Space backend")
+  }
+
   async flushCheckpoint(): Promise<void> {
     if (this.checkpointDirty.size === 0) return
     const paths = [...this.checkpointDirty]
@@ -199,6 +204,57 @@ export function spaceR2Prefix(spaceId: string): string {
   return `spaces/v1/${spaceId}`
 }
 
+const R2_MULTIPART_CHUNK_BYTES = 5 * 1024 * 1024
+
+async function putStream(
+  bucket: R2Bucket,
+  key: string,
+  content: ReadableStream<Uint8Array>,
+  mediaType: string,
+): Promise<R2Object> {
+  const upload = await bucket.createMultipartUpload(key, {
+    httpMetadata: { contentType: mediaType },
+  })
+  const uploaded: R2UploadedPart[] = []
+  const reader = content.getReader()
+  let buffer = new Uint8Array(R2_MULTIPART_CHUNK_BYTES)
+  let buffered = 0
+  let partNumber = 1
+  const flush = async () => {
+    if (buffered === 0) return
+    uploaded.push(await upload.uploadPart(partNumber++, buffer.slice(0, buffered)))
+    buffer = new Uint8Array(R2_MULTIPART_CHUNK_BYTES)
+    buffered = 0
+  }
+  try {
+    while (true) {
+      const next = await reader.read()
+      if (next.done) break
+      let offset = 0
+      while (offset < next.value.byteLength) {
+        const copied = Math.min(buffer.byteLength - buffered, next.value.byteLength - offset)
+        buffer.set(next.value.subarray(offset, offset + copied), buffered)
+        buffered += copied
+        offset += copied
+        if (buffered === buffer.byteLength) await flush()
+      }
+    }
+    await flush()
+    if (uploaded.length === 0) {
+      await upload.abort()
+      return (await bucket.put(key, new Uint8Array(), {
+        httpMetadata: { contentType: mediaType },
+      }))
+    }
+    return upload.complete(uploaded)
+  } catch (error) {
+    await upload.abort().catch(() => undefined)
+    throw error
+  } finally {
+    reader.releaseLock()
+  }
+}
+
 export class SqlBackend implements SpaceFsBackend {
   readonly overlay: FileSystem
   readonly fs: FileSystem
@@ -212,7 +268,11 @@ export class SqlBackend implements SpaceFsBackend {
    * row will hold — and a Space that fills its DO storage stops accepting
    * writes for every other file too.
    */
-  constructor(ctx: DurableObjectState, repoName: string, r2?: R2Bucket) {
+  constructor(
+    private readonly ctx: DurableObjectState,
+    private readonly repoName: string,
+    private readonly r2?: R2Bucket,
+  ) {
     const workspace = new Workspace({
       sql: ctx.storage.sql,
       name: () => repoName,
@@ -229,6 +289,63 @@ export class SqlBackend implements SpaceFsBackend {
   async ready(): Promise<void> {}
   async hydrate(_path: string): Promise<void> {}
   async materializeAll(): Promise<void> {}
+  async writeFileStream(
+    path: string,
+    content: ReadableStream<Uint8Array>,
+    mediaType: string,
+  ): Promise<void> {
+    if (!this.r2) throw new Error("Streaming writes require an R2 binding")
+    await this.workspace.exists("/")
+    const existing = await this.workspace.stat(path)
+    if (existing?.type === "directory") throw new Error(`EISDIR: ${path} is a directory`)
+    const parent = path.slice(0, path.lastIndexOf("/")) || "/"
+    await this.workspace.mkdir(parent, { recursive: true })
+
+    // @cloudflare/shell@0.4.3 owns this table. Its public writeFileStream buffers;
+    // this adapter keeps the same row contract while R2 consumes the body stream.
+    const table = "cf_workspace_default"
+    const previous = this.ctx.storage.sql.exec<{ r2Key: string | null }>(
+      `SELECT r2_key AS r2Key FROM ${table} WHERE path = ?`,
+      path,
+    ).toArray()[0]
+    const key = `${spaceR2Prefix(this.repoName)}/streams/${crypto.randomUUID()}`
+    try {
+      const object = await putStream(this.r2, key, content, mediaType)
+      const name = path.split("/").at(-1)!
+      const now = Math.floor(Date.now() / 1_000)
+      this.ctx.storage.sql.exec(
+        `INSERT INTO ${table}
+           (path, parent_path, name, type, mime_type, size, storage_backend,
+            r2_key, content_encoding, content, created_at, modified_at)
+         VALUES (?, ?, ?, 'file', ?, ?, 'r2', ?, 'base64', NULL, ?, ?)
+         ON CONFLICT(path) DO UPDATE SET
+           parent_path = excluded.parent_path,
+           name = excluded.name,
+           type = 'file',
+           mime_type = excluded.mime_type,
+           size = excluded.size,
+           storage_backend = 'r2',
+           r2_key = excluded.r2_key,
+           content_encoding = 'base64',
+           content = NULL,
+           modified_at = excluded.modified_at`,
+        path,
+        parent,
+        name,
+        mediaType,
+        object.size,
+        key,
+        now,
+        now,
+      )
+    } catch (error) {
+      await this.r2.delete(key).catch(() => undefined)
+      throw error
+    }
+    if (previous?.r2Key && previous.r2Key !== key) {
+      await this.r2.delete(previous.r2Key).catch(() => undefined)
+    }
+  }
   async flushCheckpoint(): Promise<void> {}
   async push(_branch: string): Promise<boolean> { return false }
   async fetch(_branch: string): Promise<void> {}

package/src/space/workspace-port.ts

@@ -182,6 +182,11 @@ export interface SpaceWorkspacePort {
     data: Uint8Array | ArrayBuffer,
     mimeType?: string,
   ): Promise<void>;
+  writeFileStream(
+    path: string,
+    content: ReadableStream<Uint8Array>,
+    options?: SpaceStreamWriteOptions,
+  ): Promise<{ path: string; bytes: number }>;
   appendFile(path: string, content: string, mimeType?: string): Promise<void>;
   exists(path: string): Promise<boolean>;
   stat(path: string): Promise<SpaceFileInfo | null>;
@@ -199,6 +204,11 @@ export interface SpaceWorkspacePort {
   glob(pattern: string): Promise<SpaceFileInfo[]>;
 }
 
+export interface SpaceStreamWriteOptions {
+  contentLength?: number;
+  mediaType?: string;
+}
+
 /**
  * Everything a Space does that is not a file operation.
  *