@cat-factory/provider-s3 0.2.85 → 0.2.86
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +74 -0
- package/package.json +2 -2
package/README.md
ADDED
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
# @cat-factory/provider-s3
|
|
2
|
+
|
|
3
|
+
Opt-in **AWS S3** (or S3-compatible) blob backend for cat-factory's binary artifacts —
|
|
4
|
+
implements the kernel `BinaryBlobBackend` port over an S3 bucket.
|
|
5
|
+
|
|
6
|
+
## Why this is its own package
|
|
7
|
+
|
|
8
|
+
The blob backend is pluggable: artifact **metadata** always lives in the runtime's database, but
|
|
9
|
+
the **bytes** can go anywhere (Cloudflare R2, the local filesystem, Postgres, or S3). S3 pulls in
|
|
10
|
+
the heavy `@aws-sdk/client-s3`, so it ships as its own opt-in package that only a deployment
|
|
11
|
+
choosing S3 depends on. Even then, the SDK is imported **lazily on first I/O**, not at module
|
|
12
|
+
load: a facade statically imports `S3BinaryBlobBackend` to wire its container, but a deployment
|
|
13
|
+
that ends up running the `db`/`fs`/no blob backend never pays the SDK's load cost — the SDK is
|
|
14
|
+
pulled in only when an S3 `put`/`get`/`delete` actually executes.
|
|
15
|
+
|
|
16
|
+
## Enabling it
|
|
17
|
+
|
|
18
|
+
The package exports one class:
|
|
19
|
+
|
|
20
|
+
- `S3BinaryBlobBackend` — a `BinaryBlobBackend` (`put` / `get` / `delete`) constructed from an
|
|
21
|
+
`S3BinaryBlobBackendConfig`.
|
|
22
|
+
|
|
23
|
+
### Node / local facade
|
|
24
|
+
|
|
25
|
+
The Node facade selects a blob backend by kind in its `BuildBlobBackend` switch (see
|
|
26
|
+
`backend/runtimes/node/src/container.ts`); the `s3` case builds this backend from the account's
|
|
27
|
+
content-storage config:
|
|
28
|
+
|
|
29
|
+
```ts
|
|
30
|
+
import { S3BinaryBlobBackend } from '@cat-factory/provider-s3'
|
|
31
|
+
|
|
32
|
+
case 's3':
|
|
33
|
+
if (!opts.s3) return null
|
|
34
|
+
return new S3BinaryBlobBackend({
|
|
35
|
+
...opts.s3, // region, bucket, prefix, endpoint, forcePathStyle
|
|
36
|
+
...(opts.s3Credentials ? { credentials: opts.s3Credentials } : {}),
|
|
37
|
+
})
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
An account picks the S3 backend (and supplies region / bucket + credentials) in the
|
|
41
|
+
**content-storage settings UI**; the facade builds the backend from that config. Omitting
|
|
42
|
+
`credentials` is intentional and falls back to the **ambient AWS credential chain** (instance
|
|
43
|
+
role, `AWS_*` env) — the right behaviour for a deployment running on AWS with an attached role.
|
|
44
|
+
(The UI requires explicit keys, so the keyless path is only reached by config written through
|
|
45
|
+
another channel.)
|
|
46
|
+
|
|
47
|
+
> **Runtime reach.** S3 is wired on the **Node / local** facades. The Cloudflare Worker uses
|
|
48
|
+
> **R2** as its native blob backend, so it does not pull in `@aws-sdk/client-s3`. Scaled
|
|
49
|
+
> (multi-replica) Node deployments should prefer `s3` over the `fs` backend, whose local-disk
|
|
50
|
+
> bytes are invisible to other replicas and lost on redeploy.
|
|
51
|
+
|
|
52
|
+
## S3-compatible stores
|
|
53
|
+
|
|
54
|
+
Point `endpoint` at a non-AWS S3 API (MinIO, Ceph, etc.) and set `forcePathStyle: true` (required
|
|
55
|
+
by most S3-compatible stores). An optional `prefix` (e.g. `artifacts/`) is joined to each
|
|
56
|
+
artifact's storage key.
|
|
57
|
+
|
|
58
|
+
## Config (`S3BinaryBlobBackendConfig`)
|
|
59
|
+
|
|
60
|
+
| Option | Purpose |
|
|
61
|
+
| ---------------- | -------------------------------------------------------------------------------- |
|
|
62
|
+
| `region` | AWS region (required). |
|
|
63
|
+
| `bucket` | Target bucket (required). |
|
|
64
|
+
| `prefix` | Optional key prefix, e.g. `artifacts/`, joined to the artifact's storage key. |
|
|
65
|
+
| `endpoint` | Optional custom endpoint for S3-compatible stores (MinIO, etc.). |
|
|
66
|
+
| `forcePathStyle` | Force path-style addressing (needed by most S3-compatible stores). |
|
|
67
|
+
| `credentials` | Explicit `{ accessKeyId, secretAccessKey, sessionToken? }`; omit to use the default AWS credential chain. |
|
|
68
|
+
|
|
69
|
+
## Related
|
|
70
|
+
|
|
71
|
+
Part of cat-factory's opt-in **AWS stack** alongside
|
|
72
|
+
[`@cat-factory/provider-bedrock`](../provider-bedrock) (LLM models) and
|
|
73
|
+
[`@cat-factory/eks`](../eks) (runner + environment backends). Each is independent and registers
|
|
74
|
+
into its own seam — mix in only what you use.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@cat-factory/provider-s3",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.86",
|
|
4
4
|
"description": "Opt-in AWS S3 blob backend for the Agent Architecture Board's binary-artifact storage abstraction. Implements the kernel BinaryBlobBackend port over an S3 bucket.",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
@@ -25,7 +25,7 @@
|
|
|
25
25
|
},
|
|
26
26
|
"dependencies": {
|
|
27
27
|
"@aws-sdk/client-s3": "^3.1075.0",
|
|
28
|
-
"@cat-factory/kernel": "0.
|
|
28
|
+
"@cat-factory/kernel": "0.89.0"
|
|
29
29
|
},
|
|
30
30
|
"devDependencies": {
|
|
31
31
|
"typescript": "7.0.1-rc"
|