@devries-cameron20 / t3code Mirror · read-only
Fork 0

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

main
ts 137 lines 5.18 KB
Raw
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 ) {}