@walkeros/server-store-gcs 4.1.0-next-1778668930820 → 4.1.0

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.
Files changed (4) hide show
  1. package/CHANGELOG.md +178 -0
  2. package/README.md +32 -145
  3. package/dist/walkerOS.json +2 -6
  4. package/package.json +4 -3
package/CHANGELOG.md ADDED
@@ -0,0 +1,178 @@
1
+ # @walkeros/server-store-gcs
2
+
3
+ ## 4.1.0
4
+
5
+ ### Patch Changes
6
+
7
+ - Updated dependencies [e155ff8]
8
+ - Updated dependencies [e800974]
9
+ - Updated dependencies [e155ff8]
10
+ - Updated dependencies [1a8f2d7]
11
+ - Updated dependencies [1a8f2d7]
12
+ - Updated dependencies [b276173]
13
+ - Updated dependencies [dd9f5ad]
14
+ - Updated dependencies [c60ef35]
15
+ - Updated dependencies [adeebea]
16
+ - Updated dependencies [13aaeaa]
17
+ - Updated dependencies [e800974]
18
+ - Updated dependencies [adeebea]
19
+ - Updated dependencies [e800974]
20
+ - Updated dependencies [e800974]
21
+ - Updated dependencies [058f7ed]
22
+ - Updated dependencies [28a8ac2]
23
+ - Updated dependencies [fd6076e]
24
+ - @walkeros/core@4.1.0
25
+
26
+ ## 4.0.2
27
+
28
+ ### Patch Changes
29
+
30
+ - Updated dependencies [a6a0ea7]
31
+ - @walkeros/core@4.0.2
32
+
33
+ ## 4.0.1
34
+
35
+ ### Patch Changes
36
+
37
+ - cc3bbd0: Add `setup()` lifecycle. Operators can now run
38
+ `walkeros setup store.<id>` to create the GCS bucket idempotently with
39
+ sensible defaults (location EU, STANDARD storage class, uniform bucket-level
40
+ access, public access prevention enforced). Detects drift on subsequent runs
41
+ without mutating the bucket. Adds a hard-fail with actionable message at
42
+ runtime when the bucket does not exist.
43
+ - Updated dependencies [381dfe7]
44
+ - Updated dependencies [1524275]
45
+ - Updated dependencies [03d7055]
46
+ - @walkeros/core@4.0.1
47
+
48
+ ## 4.0.0
49
+
50
+ ### Patch Changes
51
+
52
+ - Updated dependencies [93ea9c4]
53
+ - Updated dependencies [465775c]
54
+ - Updated dependencies [942a7fe]
55
+ - Updated dependencies [cfc7469]
56
+ - Updated dependencies [8e06b1f]
57
+ - Updated dependencies [3d50dd6]
58
+ - Updated dependencies [1ef33d9]
59
+ - @walkeros/core@4.0.0
60
+
61
+ ## 3.4.2
62
+
63
+ ### Patch Changes
64
+
65
+ - @walkeros/core@3.4.2
66
+
67
+ ## 3.4.1
68
+
69
+ ### Patch Changes
70
+
71
+ - Updated dependencies [12adf24]
72
+ - Updated dependencies [75aa26b]
73
+ - @walkeros/core@3.4.1
74
+
75
+ ## 3.4.0
76
+
77
+ ### Minor Changes
78
+
79
+ - 724f97e: Migrate every step example in every walkerOS package to the
80
+ standardized `[callable, ...args][]` shape introduced in `@walkeros/core`.
81
+ Every step example's `out` is now an array of effect tuples whose first
82
+ element is the callable's public SDK name (`'gtag'`, `'analytics.track'`,
83
+ `'fbq'`, `'dataLayer.push'`, `'sendServer'`, `'fetch'`, `'trackClient.track'`,
84
+ `'amplitude.track'`, `'fs.writeFile'`, `'producer.send'`, `'client.xadd'`,
85
+ `'client.send'`, `'dataset.table.insert'`, etc.). Source examples use `'elb'`
86
+ as the callable; transformer examples use the reserved `'return'` keyword;
87
+ store examples use store-operation callables (`'get'`, `'set'`). Tests capture
88
+ real calls on each component's spy and assert against `example.out` directly —
89
+ the hardcoded `PACKAGE_CALLS` registry in the app is no longer consulted
90
+ (emptied; plan #3 removes it structurally).
91
+
92
+ ### Patch Changes
93
+
94
+ - Updated dependencies [74940cc]
95
+ - Updated dependencies [525f5d9]
96
+ - @walkeros/core@3.4.0
97
+
98
+ ## 3.3.1
99
+
100
+ ### Patch Changes
101
+
102
+ - @walkeros/core@3.3.1
103
+
104
+ ## 3.3.0
105
+
106
+ ### Patch Changes
107
+
108
+ - Updated dependencies [2849acb]
109
+ - Updated dependencies [08c365a]
110
+ - Updated dependencies [08c365a]
111
+ - Updated dependencies [08c365a]
112
+ - Updated dependencies [08c365a]
113
+ - @walkeros/core@3.3.0
114
+
115
+ ## 3.2.0
116
+
117
+ ### Patch Changes
118
+
119
+ - Updated dependencies [eb865e1]
120
+ - Updated dependencies [c0a53f9]
121
+ - Updated dependencies [f007c9f]
122
+ - Updated dependencies [bf2dc5b]
123
+ - Updated dependencies [da0b640]
124
+ - @walkeros/core@3.2.0
125
+
126
+ ## 3.1.1
127
+
128
+ ### Patch Changes
129
+
130
+ - @walkeros/core@3.1.1
131
+
132
+ ## 3.1.0
133
+
134
+ ### Patch Changes
135
+
136
+ - Updated dependencies [dfc6738]
137
+ - Updated dependencies [966342b]
138
+ - Updated dependencies [bee8ba7]
139
+ - Updated dependencies [966342b]
140
+ - Updated dependencies [df990d4]
141
+ - @walkeros/core@3.1.0
142
+
143
+ ## 3.0.2
144
+
145
+ ### Patch Changes
146
+
147
+ - @walkeros/core@3.0.2
148
+
149
+ ## 3.0.1
150
+
151
+ ### Patch Changes
152
+
153
+ - @walkeros/core@3.0.1
154
+
155
+ ## 3.0.0
156
+
157
+ ### Minor Changes
158
+
159
+ - f5b925d: New package: Google Cloud Storage store with zero runtime
160
+ dependencies and built-in ADC + service account auth
161
+
162
+ ### Patch Changes
163
+
164
+ - Updated dependencies [2b259b6]
165
+ - Updated dependencies [2614014]
166
+ - Updated dependencies [6ae0ee3]
167
+ - Updated dependencies [37299a9]
168
+ - Updated dependencies [499e27a]
169
+ - Updated dependencies [0e5eede]
170
+ - Updated dependencies [d11f574]
171
+ - Updated dependencies [d11f574]
172
+ - Updated dependencies [1fe337a]
173
+ - Updated dependencies [5cb84c1]
174
+ - Updated dependencies [23f218a]
175
+ - Updated dependencies [499e27a]
176
+ - Updated dependencies [c83d909]
177
+ - Updated dependencies [b6c8fa8]
178
+ - @walkeros/core@3.0.0
package/README.md CHANGED
@@ -1,166 +1,53 @@
1
+ <p align="left">
2
+ <a href="https://www.walkeros.io">
3
+ <img alt="walkerOS" title="walkerOS" src="https://www.walkeros.io/img/walkerOS_logo.svg" width="256px"/>
4
+ </a>
5
+ </p>
6
+
1
7
  # @walkeros/server-store-gcs
2
8
 
3
- Google Cloud Storage for walkerOS server flows.
9
+ Google Cloud Storage store with zero runtime dependencies. Uses raw `fetch`
10
+ against the GCS JSON API with built-in auth via Application Default Credentials
11
+ or an explicit service account JWT.
12
+
13
+ [Documentation](https://www.walkeros.io/docs/stores/server/gcs) &bull;
14
+ [NPM Package](https://www.npmjs.com/package/@walkeros/server-store-gcs) &bull;
15
+ [Source Code](https://github.com/elbwalker/walkerOS/tree/main/packages/server/stores/gcs)
16
+
17
+ ## Installation
4
18
 
5
- Zero runtime dependencies — uses raw `fetch` against the GCS JSON API with
6
- built-in auth (ADC on Cloud Run / service account JWT elsewhere).
19
+ ```bash
20
+ npm install @walkeros/server-store-gcs
21
+ ```
7
22
 
8
- ## Quick Start (Bundled Mode)
23
+ ## Quick start
9
24
 
10
25
  ```json
11
26
  {
12
- "version": 3,
27
+ "version": 4,
13
28
  "flows": {
14
29
  "default": {
15
- "server": {},
30
+ "config": { "platform": "server" },
16
31
  "stores": {
17
- "assets": {
18
- "package": "@walkeros/server-store-gcs",
19
- "config": {
20
- "settings": {
21
- "bucket": "my-assets",
22
- "prefix": "public"
23
- }
24
- }
25
- }
26
- },
27
- "transformers": {
28
- "file": {
29
- "package": "@walkeros/server-transformer-file",
30
- "config": { "settings": { "prefix": "/static" } },
31
- "env": { "store": "$store.assets" }
32
- }
32
+ "assets": { "package": "@walkeros/server-store-gcs", "config": {} }
33
33
  }
34
34
  }
35
35
  }
36
36
  }
37
37
  ```
38
38
 
39
- ## Integrated Mode
40
-
41
- ```typescript
42
- import { storeGcsInit } from '@walkeros/server-store-gcs';
43
-
44
- const store = await storeGcsInit({
45
- collector,
46
- logger,
47
- id: 'assets',
48
- config: {
49
- settings: {
50
- bucket: 'my-assets',
51
- prefix: 'public',
52
- // Omit credentials for ADC on Cloud Run/GKE
53
- // Or pass SA JSON: credentials: process.env.GCS_SA_KEY
54
- },
55
- },
56
- env: {},
57
- });
58
-
59
- const file = await store.get('walker.js'); // Buffer | undefined
60
- await store.set('cache/data.json', Buffer.from('{}'));
61
- await store.delete('old-file.txt');
62
- ```
63
-
64
- ## Configuration
65
-
66
- | Setting | Type | Required | Default | Description |
67
- | ------------- | ------------------ | -------- | ------- | ------------------------------ |
68
- | `bucket` | `string` | Yes | (none) | GCS bucket name |
69
- | `prefix` | `string` | No | (none) | Key prefix for scoping |
70
- | `credentials` | `string \| object` | No | ADC | Service account JSON or string |
71
-
72
- ## Provisioning
73
-
74
- The package ships an idempotent `setup()` lifecycle that creates the GCS bucket
75
- described in flow config. It is invoked only by the explicit operator command:
76
-
77
- ```bash
78
- walkeros setup store.<id>
79
- ```
80
-
81
- It never runs automatically and never alters an existing bucket.
82
-
83
- ### `Setup` options
84
-
85
- | Option | Type | Default | Notes |
86
- | -------------- | ----------------------------------------------------- | ------------ | -------------------------------------------------------------- |
87
- | `projectId` | `string` | (resolved) | GCP project that owns the bucket. Resolution order below. |
88
- | `location` | `string` | `'EU'` | Multi-region or regional location. |
89
- | `storageClass` | `'STANDARD' \| 'NEARLINE' \| 'COLDLINE' \| 'ARCHIVE'` | `'STANDARD'` | Default object storage class. |
90
- | `versioning` | `boolean` | `false` | Object versioning. Off by default; opt in. |
91
- | `lifecycle` | `{ rule: unknown[] }` | (none) | Applied at create. Drift detection NOT included for lifecycle. |
92
- | `kmsKeyName` | `string` | (none) | Customer-managed encryption key (CMEK) at create time. |
93
- | `labels` | `Record<string, string>` | (none) | Cost-allocation labels. |
94
-
95
- `bucket` is taken from `settings.bucket` and is NOT duplicated under `setup`.
96
-
97
- ### `projectId` resolution
98
-
99
- The GCS create call requires a project. Resolution order:
100
-
101
- 1. Explicit `setup.projectId`.
102
- 2. `project_id` field inside the `settings.credentials` service-account JSON.
103
- 3. `process.env.GOOGLE_CLOUD_PROJECT` (Cloud Run / GKE convention).
104
- 4. Throws with an actionable error if none of the above is available.
105
-
106
- ### Behavior
107
-
108
- - **Idempotent**: HTTP 409 (bucket exists) is treated as success. The setup
109
- never patches or mutates an existing bucket.
110
- - **Drift detection**: when the bucket already exists, setup performs a
111
- `GET /b/<bucket>` and logs `WARN setup.drift { field, declared, actual }` for
112
- any of `location`, `storageClass`, `versioning`, `iamConfiguration` (uniform
113
- bucket-level access, public access prevention), and `labels` that do not
114
- match. Drift is logged, never auto-fixed.
115
- - **Defaults enforced at create**: uniform bucket-level access on, public access
116
- prevention enforced. These are baked in by the package.
117
-
118
- ### Runtime hard-fail
119
-
120
- At runtime, the first `get` / `set` / `delete` call issues a single
121
- `HEAD /b/<bucket>` per process per bucket. On 404, it throws with an actionable
122
- message:
123
-
124
- ```
125
- GCS bucket not found: <bucket> in project <projectId>. Run "walkeros setup store.<id>" to create it.
126
- ```
127
-
128
- Operators see the error pointing at the exact command to fix it. Subsequent
129
- operations in the same process skip the check via an in-memory cache.
130
-
131
- ## Authentication
39
+ ## Documentation
132
40
 
133
- ### Cloud Run / GKE (ADC)
41
+ Full configuration, mapping, and examples live in the docs:
42
+ **https://www.walkeros.io/docs/stores/server/gcs**
134
43
 
135
- When running on GCP infrastructure, omit `credentials`. The store fetches tokens
136
- from the metadata server automatically.
44
+ ## Contribute
137
45
 
138
- ### Non-GCP (Service Account)
46
+ Feel free to contribute by submitting an
47
+ [issue](https://github.com/elbwalker/walkerOS/issues), starting a
48
+ [discussion](https://github.com/elbwalker/walkerOS/discussions), or getting in
49
+ [contact](https://calendly.com/elb-alexander/30min).
139
50
 
140
- Pass a service account JSON as a string (from `$env.GCS_SA_KEY`) or as an object
141
- with `client_email` and `private_key` fields. The store signs JWTs locally and
142
- exchanges them for access tokens.
143
-
144
- ```json
145
- {
146
- "credentials": "$env.GCS_SA_KEY"
147
- }
148
- ```
149
-
150
- ## Security
151
-
152
- - **Key validation**: Path traversal attempts (`..`, absolute paths) are
153
- rejected
154
- - **Prefix scoping**: The `prefix` setting restricts all operations to a
155
- subdirectory
156
- - **Token caching**: Access tokens are cached and refreshed automatically
157
-
158
- ## API
159
-
160
- ```typescript
161
- const file = await store.get('walker.js'); // Buffer | undefined
162
- await store.set('data.json', Buffer.from('{}')); // void
163
- await store.delete('old-file.txt'); // void
164
- ```
51
+ ## License
165
52
 
166
- `get()` returns `Buffer` for compatibility with the file transformer.
53
+ MIT
package/dist/walkerOS.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$meta": {
3
3
  "package": "@walkeros/server-store-gcs",
4
- "version": "4.1.0-next-1778668930820",
4
+ "version": "4.1.0",
5
5
  "type": "store",
6
6
  "platform": [
7
7
  "server"
@@ -99,11 +99,7 @@
99
99
  "type": "string"
100
100
  }
101
101
  },
102
- "required": [
103
- "location",
104
- "storageClass",
105
- "versioning"
106
- ],
102
+ "required": [],
107
103
  "additionalProperties": false,
108
104
  "description": "Provisioning options for \"walkeros setup store.<id>\". Idempotent: never mutates an existing bucket."
109
105
  }
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@walkeros/server-store-gcs",
3
3
  "description": "Google Cloud Storage for walkerOS server flows",
4
- "version": "4.1.0-next-1778668930820",
4
+ "version": "4.1.0",
5
5
  "license": "MIT",
6
6
  "main": "./dist/index.js",
7
7
  "module": "./dist/index.mjs",
@@ -20,7 +20,8 @@
20
20
  "./walkerOS.json": "./dist/walkerOS.json"
21
21
  },
22
22
  "files": [
23
- "dist/**"
23
+ "dist/**",
24
+ "CHANGELOG.md"
24
25
  ],
25
26
  "scripts": {
26
27
  "build": "tsup --silent",
@@ -32,7 +33,7 @@
32
33
  "update": "npx npm-check-updates -u && npm update"
33
34
  },
34
35
  "dependencies": {
35
- "@walkeros/core": "4.1.0-next-1778668930820"
36
+ "@walkeros/core": "4.1.0"
36
37
  },
37
38
  "devDependencies": {},
38
39
  "repository": {