The best way to control Claude Code, Codex and more from any computer or phone
Mirrored from https://github.com/Camo67/t3code.git
Synced Nov 21, 04:45 UTC
| 1 | /** |
| 2 | * `Git.BlobStore` — the swappable bulk-byte store (RFC "Git Building |
| 3 | * Blocks" §3.1). |
| 4 | * |
| 5 | * Immutable, content-addressed bulk bytes: compacted packs, clone |
| 6 | * bundles, oversize loose objects, and spilled push bodies. The contract |
| 7 | * is everything the pack plane needs and nothing more — ranged reads, |
| 8 | * whole-object writes with a known length, multipart writes of unknown |
| 9 | * length, delete, and prefix listing (GC only, never on a serving path). |
| 10 | * |
| 11 | * Implementations shipped: |
| 12 | * |
| 13 | * - `Git.BlobStoreR2` — Cloudflare R2 over the existing |
| 14 | * `ReadWriteBucket` capability (the default). |
| 15 | * - `Git.BlobStoreS3` — AWS S3 over the S3 object bindings. |
| 16 | * |
| 17 | * Multipart rules are the R2/S3 intersection: uniform part sizes |
| 18 | * (≥ 5 MiB) except the last part. |
| 19 | * |
| 20 | * ### Providing the store |
| 21 | * **Example:** R2 (the default) |
| 22 | * ```typescript |
| 23 | * const GitLive = Git.ApiLive.pipe( |
| 24 | * Layer.provide(Git.ApiHandlersLive), |
| 25 | * Layer.provide(Git.BlobStoreR2(MyBucket)), |
| 26 | * // ... |
| 27 | * ); |
| 28 | * |
| 29 | * // The Worker picks the ReadWriteBucket implementation. |
| 30 | * export default class GitHost extends Cloudflare.Worker<GitHost>()( |
| 31 | * "GitHost", |
| 32 | * { main: import.meta.url, ...Git.GIT_WORKER_OPTIONS }, |
| 33 | * Effect.gen(function* () { |
| 34 | * return { fetch: yield* HttpRouter.toHttpEffect(GitLive) }; |
| 35 | * }).pipe(Effect.provide(Cloudflare.R2.ReadWriteBucketBinding)), |
| 36 | * ) {} |
| 37 | * ``` |
| 38 | */ |
| 39 | import type { RuntimeContext } from "alchemy/RuntimeContext"; |
| 40 | import * as Context from "effect/Context"; |
| 41 | import * as Data from "effect/Data"; |
| 42 | import * as Effect from "effect/Effect"; |
| 43 | import * as Stream from "effect/Stream"; |
| 44 | |
| 45 | /** Failure of a {@link BlobStore} operation. */ |
| 46 | export class BlobStoreError extends Data.TaggedError("BlobStoreError")<{ |
| 47 | readonly reason: string; |
| 48 | }> {} |
| 49 | |
| 50 | /** A read blob: size plus the bytes as a one-shot buffer or a stream. */ |
| 51 | export interface BlobBody { |
| 52 | readonly size: number; |
| 53 | readonly bytes: Effect.Effect<Uint8Array, BlobStoreError>; |
| 54 | readonly stream: Stream.Stream<Uint8Array, BlobStoreError>; |
| 55 | /** |
| 56 | * The store's native body stream when it has one, for serving paths |
| 57 | * that pipe bytes to the client with no per-chunk Effect work (DESIGN |
| 58 | * §22). Consume either this or `stream`, never both. |
| 59 | */ |
| 60 | readonly readable?: ReadableStream<Uint8Array> | undefined; |
| 61 | } |
| 62 | |
| 63 | /** One uploaded part of a multipart write, as the store identifies it. */ |
| 64 | export interface UploadedPart { |
| 65 | readonly partNumber: number; |
| 66 | readonly etag: string; |
| 67 | } |
| 68 | |
| 69 | /** |
| 70 | * An in-flight multipart write. Parts must be uniform in size (≥ 5 MiB) |
| 71 | * except the last — the R2/S3 intersection. Parts may be uploaded from |
| 72 | * ANY isolate that knows the key and `uploadId` (`BlobStoreShape.uploadPart` |
| 73 | * — the push pipeline's hasher isolates do, DESIGN §22.10); the creator |
| 74 | * completes with the collected parts, in any order. |
| 75 | */ |
| 76 | export interface BlobMultipart { |
| 77 | readonly uploadId: string; |
| 78 | readonly uploadPart: ( |
| 79 | partNumber: number, |
| 80 | part: Uint8Array, |
| 81 | ) => Effect.Effect<UploadedPart, BlobStoreError>; |
| 82 | readonly complete: (parts: ReadonlyArray<UploadedPart>) => Effect.Effect<void, BlobStoreError>; |
| 83 | readonly abort: Effect.Effect<void, BlobStoreError>; |
| 84 | } |
| 85 | |
| 86 | /** Sorts parts by number: stores validate the uniform-part rule against the list as given. */ |
| 87 | export const orderedParts = (parts: ReadonlyArray<UploadedPart>): Array<UploadedPart> => |
| 88 | [...parts].sort((a, b) => a.partNumber - b.partNumber); |
| 89 | |
| 90 | /** One listed blob (GC/purge walks). */ |
| 91 | export interface BlobMeta { |
| 92 | readonly key: string; |
| 93 | readonly size: number; |
| 94 | } |
| 95 | |
| 96 | /** The service shape — see the module doc for semantics. */ |
| 97 | export interface BlobStoreShape { |
| 98 | /** Ranged read; omit `range` for the whole object. `null` = missing. */ |
| 99 | readonly get: ( |
| 100 | key: string, |
| 101 | range?: { readonly offset: number; readonly length: number }, |
| 102 | ) => Effect.Effect<BlobBody | null, BlobStoreError, RuntimeContext>; |
| 103 | /** Whole-object write. `contentLength` is required for streams. */ |
| 104 | readonly put: ( |
| 105 | key: string, |
| 106 | body: Uint8Array | Stream.Stream<Uint8Array, BlobStoreError>, |
| 107 | options?: { readonly contentLength?: number | undefined }, |
| 108 | ) => Effect.Effect<void, BlobStoreError, RuntimeContext>; |
| 109 | /** Existence/size check without reading the body. */ |
| 110 | readonly head: (key: string) => Effect.Effect<BlobMeta | null, BlobStoreError, RuntimeContext>; |
| 111 | /** Begin a multipart write (spilled push bodies of unknown length). */ |
| 112 | readonly multipart: (key: string) => Effect.Effect<BlobMultipart, BlobStoreError, RuntimeContext>; |
| 113 | /** |
| 114 | * Uploads one part of a multipart write created elsewhere (by key and |
| 115 | * `uploadId`) — the resume path the push pipeline's hasher isolates use. |
| 116 | */ |
| 117 | readonly uploadPart: ( |
| 118 | key: string, |
| 119 | uploadId: string, |
| 120 | partNumber: number, |
| 121 | part: Uint8Array, |
| 122 | ) => Effect.Effect<UploadedPart, BlobStoreError, RuntimeContext>; |
| 123 | readonly delete: ( |
| 124 | keys: string | ReadonlyArray<string>, |
| 125 | ) => Effect.Effect<void, BlobStoreError, RuntimeContext>; |
| 126 | /** Prefix listing — GC/purge only, never on a serving path. */ |
| 127 | readonly list: (prefix: string) => Stream.Stream<BlobMeta, BlobStoreError, RuntimeContext>; |
| 128 | } |
| 129 | |
| 130 | /** |
| 131 | * The swappable bulk-byte store of the git service. |
| 132 | * |
| 133 | * @binding |
| 134 | */ |
| 135 | export class BlobStore extends Context.Service<BlobStore, BlobStoreShape>()( |
| 136 | "alchemy/Git/BlobStore", |
| 137 | ) {} |