The best way to control Claude Code, Codex and more from any computer or phone

main
mdx 140 lines 3.9 KB
Raw
1 ---
2 title: Cloud Storage
3 description: Create Cloud Storage buckets, read and write objects from Cloud Run with Read, Write, and ReadWrite bindings, and hand out signed download URLs.
4 ---
5
6 Cloud Storage holds files. Declare a Bucket, bind it to your service,
7 and `get`, `put`, `list`, and `delete` objects.
8
9 ## Create a Bucket
10
11 ```typescript
12 // src/resources.ts
13 import * as GCP from "@alchemy.run/gcp";
14
15 export const Uploads = GCP.Storage.Bucket("Uploads", {});
16 ```
17
18 Alchemy generates a globally unique name.
19
20 ## Bind it to a service
21
22 Ask for the least access you need:
23
24 | Binding | Methods | Role on the bucket |
25 | --- | --- | --- |
26 | `ReadBucket` | `head`, `get`, `list` | `roles/storage.objectViewer` |
27 | `WriteBucket` | `put`, `delete` | `roles/storage.objectUser` |
28 | `ReadWriteBucket` | all of the above | `roles/storage.objectUser` |
29
30 ```typescript
31 // src/Api.ts
32 import * as GCP from "@alchemy.run/gcp";
33 import * as Effect from "effect/Effect";
34 import { HttpServerRequest } from "effect/http/HttpServerRequest";
35 import * as HttpServerResponse from "effect/http/HttpServerResponse";
36 import { Uploads } from "./resources.ts";
37
38 export default class Api extends GCP.Function<Api>()(
39 "Api",
40 { main: import.meta.url, invokerIamDisabled: true },
41 Effect.gen(function* () {
42 const files = yield* GCP.Storage.ReadWriteBucket(Uploads);
43
44 return {
45 fetch: Effect.gen(function* () {
46 const request = yield* HttpServerRequest;
47 const name = new URL(request.originalUrl, "http://localhost").pathname.slice(1);
48
49 if (request.method === "PUT") {
50 const body = new Uint8Array(yield* request.arrayBuffer);
51 yield* files.put(name, body, {
52 contentType: request.headers["content-type"],
53 });
54 return HttpServerResponse.empty({ status: 204 });
55 }
56
57 const object = yield* files.get(name);
58 if (object === undefined) {
59 return HttpServerResponse.text("Not found", { status: 404 });
60 }
61 return HttpServerResponse.uint8Array(object.body, {
62 contentType: object.contentType ?? "application/octet-stream",
63 });
64 }).pipe(Effect.orDie),
65 };
66 }).pipe(Effect.provide(GCP.Storage.ReadWriteBucketHttp)),
67 ) {}
68 ```
69
70 ## Read objects
71
72 `get` returns the bytes and content type, or `undefined` when the
73 object is missing:
74
75 ```typescript
76 const object = yield* files.get("reports/2026.json");
77 const text = object && new TextDecoder().decode(object.body);
78 ```
79
80 `head` returns only the metadata.
81
82 ## Write objects
83
84 ```typescript
85 yield* files.put("reports/2026.json", JSON.stringify(report), {
86 contentType: "application/json",
87 });
88 ```
89
90 `put` takes a string or bytes and overwrites any existing object.
91
92 ## List objects
93
94 ```typescript
95 const { objects, prefixes, nextPageToken } = yield* files.list({
96 prefix: "reports/",
97 delimiter: "/",
98 });
99 ```
100
101 ## Signed download URLs
102
103 `SignGetObjectUrl` gives a browser a link to a private object:
104
105 ```typescript
106 const sign = yield* GCP.Storage.SignGetObjectUrl(Uploads);
107 // …
108 const url = yield* sign({ object: "reports/2026.pdf", expiresIn: 3600 });
109 ```
110
111 The URL is signed with the service's own identity. There's no key
112 file. Provide `GCP.Storage.SignGetObjectUrlHttp`.
113
114 ## Destroying a Bucket with objects
115
116 Cloud Storage won't delete a Bucket that still has objects. Set
117 `forceDestroy` on Buckets whose contents you can lose:
118
119 ```typescript
120 export const Cache = GCP.Storage.Bucket("Cache", { forceDestroy: true });
121 ```
122
123 Leave it off for user data.
124
125 ## Upload files at deploy time
126
127 `Storage.Files` uploads a local directory, one object per file, and
128 only re-uploads what changed. See
129 [Static sites](/gcp/frontend/static-site#from-a-cloud-storage-bucket).
130
131 ## React to uploads
132
133 Run code when an object lands with
134 [Storage events](/gcp/messaging/storage-events).
135
136 ## Where next
137
138 - [Storage events](/gcp/messaging/storage-events) — index every upload.
139 - [Storage reference](/providers/gcp/storage#bucket) — every prop and
140 attribute.