brain-memory 0.3.0 → 0.4.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.
- package/CHANGELOG.md +54 -0
- package/SECURITY.md +44 -3
- package/bin/cloud-sync.js +49 -6
- package/commands/brain/sync.md +23 -0
- package/package.json +8 -4
- package/src/cloud-sync.js +121 -9
- package/store/CONTRACT.md +244 -0
- package/store/Dockerfile +24 -0
- package/store/README.md +43 -0
- package/store/SELF-HOSTING.md +200 -0
- package/store/bin/brain-store.js +189 -0
- package/store/conformance/conformance.test.js +341 -0
- package/store/conformance/helpers.js +145 -0
- package/store/deploy/Caddyfile +14 -0
- package/store/deploy/connector.Dockerfile +38 -0
- package/store/deploy/docker-compose.yml +83 -0
- package/store/deploy/env.example +19 -0
- package/store/lib/auth.js +174 -0
- package/store/lib/oidc.js +206 -0
- package/store/lib/storage.js +333 -0
- package/store/lib/tar.js +150 -0
- package/store/openapi.yaml +318 -0
- package/store/server.js +465 -0
- package/store/test/mock-issuer.js +104 -0
- package/store/test/oidc.test.js +217 -0
- package/store/test/store.test.js +445 -0
|
@@ -0,0 +1,318 @@
|
|
|
1
|
+
openapi: 3.1.0
|
|
2
|
+
info:
|
|
3
|
+
title: Brain store contract
|
|
4
|
+
version: "1.1"
|
|
5
|
+
summary: The HTTP interface between a Brain client and a remote store.
|
|
6
|
+
description: >
|
|
7
|
+
Machine-readable companion to CONTRACT.md. Where the two disagree,
|
|
8
|
+
CONTRACT.md is correct.
|
|
9
|
+
license:
|
|
10
|
+
name: MIT
|
|
11
|
+
identifier: MIT
|
|
12
|
+
|
|
13
|
+
servers:
|
|
14
|
+
- url: https://store.example
|
|
15
|
+
description: Your store
|
|
16
|
+
|
|
17
|
+
security:
|
|
18
|
+
- bearer: []
|
|
19
|
+
|
|
20
|
+
paths:
|
|
21
|
+
/health:
|
|
22
|
+
get:
|
|
23
|
+
summary: Liveness and contract discovery
|
|
24
|
+
security: []
|
|
25
|
+
responses:
|
|
26
|
+
"200":
|
|
27
|
+
description: The store is up.
|
|
28
|
+
content:
|
|
29
|
+
application/json:
|
|
30
|
+
schema: { $ref: "#/components/schemas/Health" }
|
|
31
|
+
|
|
32
|
+
/auth/me:
|
|
33
|
+
get:
|
|
34
|
+
summary: Describe the caller
|
|
35
|
+
responses:
|
|
36
|
+
"200":
|
|
37
|
+
description: The authenticated user.
|
|
38
|
+
content:
|
|
39
|
+
application/json:
|
|
40
|
+
schema:
|
|
41
|
+
type: object
|
|
42
|
+
required: [user]
|
|
43
|
+
properties:
|
|
44
|
+
user: { $ref: "#/components/schemas/User" }
|
|
45
|
+
storage_used: { type: integer, description: Bytes stored for this user. }
|
|
46
|
+
"401": { $ref: "#/components/responses/Unauthorized" }
|
|
47
|
+
|
|
48
|
+
/api/brains:
|
|
49
|
+
get:
|
|
50
|
+
summary: List the caller's brains, oldest first
|
|
51
|
+
responses:
|
|
52
|
+
"200":
|
|
53
|
+
description: Brain records.
|
|
54
|
+
content:
|
|
55
|
+
application/json:
|
|
56
|
+
schema:
|
|
57
|
+
type: array
|
|
58
|
+
items: { $ref: "#/components/schemas/Brain" }
|
|
59
|
+
"401": { $ref: "#/components/responses/Unauthorized" }
|
|
60
|
+
post:
|
|
61
|
+
summary: Create a brain
|
|
62
|
+
requestBody:
|
|
63
|
+
required: false
|
|
64
|
+
content:
|
|
65
|
+
application/json:
|
|
66
|
+
schema:
|
|
67
|
+
type: object
|
|
68
|
+
properties:
|
|
69
|
+
name: { type: string, default: default }
|
|
70
|
+
responses:
|
|
71
|
+
"201":
|
|
72
|
+
description: The new brain.
|
|
73
|
+
content:
|
|
74
|
+
application/json:
|
|
75
|
+
schema: { $ref: "#/components/schemas/Brain" }
|
|
76
|
+
"401": { $ref: "#/components/responses/Unauthorized" }
|
|
77
|
+
"403": { $ref: "#/components/responses/Error" }
|
|
78
|
+
|
|
79
|
+
/api/brains/{id}:
|
|
80
|
+
parameters:
|
|
81
|
+
- $ref: "#/components/parameters/BrainId"
|
|
82
|
+
get:
|
|
83
|
+
summary: Fetch one brain record
|
|
84
|
+
responses:
|
|
85
|
+
"200":
|
|
86
|
+
description: The brain.
|
|
87
|
+
content:
|
|
88
|
+
application/json:
|
|
89
|
+
schema: { $ref: "#/components/schemas/Brain" }
|
|
90
|
+
"400": { $ref: "#/components/responses/Error" }
|
|
91
|
+
"401": { $ref: "#/components/responses/Unauthorized" }
|
|
92
|
+
"404": { $ref: "#/components/responses/Error" }
|
|
93
|
+
delete:
|
|
94
|
+
summary: Delete a brain, its archive and its snapshots
|
|
95
|
+
responses:
|
|
96
|
+
"204": { description: Deleted. }
|
|
97
|
+
"401": { $ref: "#/components/responses/Unauthorized" }
|
|
98
|
+
"404": { $ref: "#/components/responses/Error" }
|
|
99
|
+
|
|
100
|
+
/api/brains/{id}/sync:
|
|
101
|
+
parameters:
|
|
102
|
+
- $ref: "#/components/parameters/BrainId"
|
|
103
|
+
get:
|
|
104
|
+
summary: Download the archive, or a snapshot
|
|
105
|
+
parameters:
|
|
106
|
+
- name: version
|
|
107
|
+
in: query
|
|
108
|
+
required: false
|
|
109
|
+
schema: { type: string }
|
|
110
|
+
description: A snapshot name from the versions listing.
|
|
111
|
+
- name: If-None-Match
|
|
112
|
+
in: header
|
|
113
|
+
required: false
|
|
114
|
+
schema: { type: string }
|
|
115
|
+
description: (1.1) Checksum the client already holds, as an entity tag.
|
|
116
|
+
responses:
|
|
117
|
+
"200":
|
|
118
|
+
description: The archive.
|
|
119
|
+
headers:
|
|
120
|
+
X-Checksum: { schema: { type: string }, description: SHA-256 of the archive. }
|
|
121
|
+
ETag: { schema: { type: string }, description: (1.1) The same checksum, quoted. }
|
|
122
|
+
content:
|
|
123
|
+
application/gzip:
|
|
124
|
+
schema: { type: string, format: binary }
|
|
125
|
+
"304": { description: (1.1) The client is current. }
|
|
126
|
+
"401": { $ref: "#/components/responses/Unauthorized" }
|
|
127
|
+
"404": { $ref: "#/components/responses/Error" }
|
|
128
|
+
put:
|
|
129
|
+
summary: Upload the archive
|
|
130
|
+
parameters:
|
|
131
|
+
- name: force
|
|
132
|
+
in: query
|
|
133
|
+
required: false
|
|
134
|
+
schema: { type: boolean }
|
|
135
|
+
description: Override the empty-push guard. Does not override If-Match.
|
|
136
|
+
- name: If-Match
|
|
137
|
+
in: header
|
|
138
|
+
required: false
|
|
139
|
+
schema: { type: string }
|
|
140
|
+
description: (1.1) Proceed only if the stored archive has this checksum.
|
|
141
|
+
- name: If-None-Match
|
|
142
|
+
in: header
|
|
143
|
+
required: false
|
|
144
|
+
schema: { type: string, enum: ["*"] }
|
|
145
|
+
description: (1.1) Proceed only if no archive is stored yet.
|
|
146
|
+
requestBody:
|
|
147
|
+
required: true
|
|
148
|
+
content:
|
|
149
|
+
multipart/form-data:
|
|
150
|
+
schema:
|
|
151
|
+
type: object
|
|
152
|
+
required: [brain]
|
|
153
|
+
properties:
|
|
154
|
+
brain:
|
|
155
|
+
type: string
|
|
156
|
+
format: binary
|
|
157
|
+
description: A gzip-compressed tar archive of the brain directory.
|
|
158
|
+
responses:
|
|
159
|
+
"200":
|
|
160
|
+
description: Stored.
|
|
161
|
+
headers:
|
|
162
|
+
ETag: { schema: { type: string }, description: (1.1) Checksum of the stored archive. }
|
|
163
|
+
content:
|
|
164
|
+
application/json:
|
|
165
|
+
schema: { $ref: "#/components/schemas/SyncResult" }
|
|
166
|
+
"400": { $ref: "#/components/responses/Error" }
|
|
167
|
+
"401": { $ref: "#/components/responses/Unauthorized" }
|
|
168
|
+
"404": { $ref: "#/components/responses/Error" }
|
|
169
|
+
"409":
|
|
170
|
+
description: The empty-push guard refused the upload.
|
|
171
|
+
content:
|
|
172
|
+
application/json:
|
|
173
|
+
schema: { $ref: "#/components/schemas/Error" }
|
|
174
|
+
"412": { $ref: "#/components/responses/PreconditionFailed" }
|
|
175
|
+
"413": { $ref: "#/components/responses/Error" }
|
|
176
|
+
"429": { $ref: "#/components/responses/RateLimited" }
|
|
177
|
+
|
|
178
|
+
/api/brains/{id}/versions:
|
|
179
|
+
parameters:
|
|
180
|
+
- $ref: "#/components/parameters/BrainId"
|
|
181
|
+
get:
|
|
182
|
+
summary: List snapshots, newest first
|
|
183
|
+
responses:
|
|
184
|
+
"200":
|
|
185
|
+
description: Snapshots.
|
|
186
|
+
content:
|
|
187
|
+
application/json:
|
|
188
|
+
schema:
|
|
189
|
+
type: object
|
|
190
|
+
required: [versions, total]
|
|
191
|
+
properties:
|
|
192
|
+
total: { type: integer }
|
|
193
|
+
versions:
|
|
194
|
+
type: array
|
|
195
|
+
items:
|
|
196
|
+
type: object
|
|
197
|
+
required: [version]
|
|
198
|
+
properties:
|
|
199
|
+
version: { type: string, description: Opaque snapshot name. }
|
|
200
|
+
date: { type: string, format: date-time }
|
|
201
|
+
"401": { $ref: "#/components/responses/Unauthorized" }
|
|
202
|
+
"404": { $ref: "#/components/responses/Error" }
|
|
203
|
+
|
|
204
|
+
/api/brains/{id}/versions/{version}/restore:
|
|
205
|
+
parameters:
|
|
206
|
+
- $ref: "#/components/parameters/BrainId"
|
|
207
|
+
- name: version
|
|
208
|
+
in: path
|
|
209
|
+
required: true
|
|
210
|
+
schema: { type: string }
|
|
211
|
+
post:
|
|
212
|
+
summary: Make a snapshot the live archive
|
|
213
|
+
parameters:
|
|
214
|
+
- name: If-Match
|
|
215
|
+
in: header
|
|
216
|
+
required: false
|
|
217
|
+
schema: { type: string }
|
|
218
|
+
description: (1.1) As for upload.
|
|
219
|
+
responses:
|
|
220
|
+
"200":
|
|
221
|
+
description: Restored. The previous live archive was kept as a snapshot.
|
|
222
|
+
content:
|
|
223
|
+
application/json:
|
|
224
|
+
schema:
|
|
225
|
+
type: object
|
|
226
|
+
required: [restored_version]
|
|
227
|
+
properties:
|
|
228
|
+
restored_version: { type: string }
|
|
229
|
+
checksum: { type: string }
|
|
230
|
+
"401": { $ref: "#/components/responses/Unauthorized" }
|
|
231
|
+
"404": { $ref: "#/components/responses/Error" }
|
|
232
|
+
"412": { $ref: "#/components/responses/PreconditionFailed" }
|
|
233
|
+
|
|
234
|
+
components:
|
|
235
|
+
securitySchemes:
|
|
236
|
+
bearer:
|
|
237
|
+
type: http
|
|
238
|
+
scheme: bearer
|
|
239
|
+
|
|
240
|
+
parameters:
|
|
241
|
+
BrainId:
|
|
242
|
+
name: id
|
|
243
|
+
in: path
|
|
244
|
+
required: true
|
|
245
|
+
schema: { type: string, format: uuid }
|
|
246
|
+
|
|
247
|
+
schemas:
|
|
248
|
+
Health:
|
|
249
|
+
type: object
|
|
250
|
+
required: [status]
|
|
251
|
+
properties:
|
|
252
|
+
status: { type: string, enum: [ok, degraded] }
|
|
253
|
+
contract: { type: string, description: Highest contract version implemented. Absent means "1". }
|
|
254
|
+
capabilities:
|
|
255
|
+
type: array
|
|
256
|
+
items: { type: string, examples: [static-token, device-code, conditional-sync] }
|
|
257
|
+
additionalProperties: true
|
|
258
|
+
User:
|
|
259
|
+
type: object
|
|
260
|
+
required: [id, email]
|
|
261
|
+
properties:
|
|
262
|
+
id: { type: string }
|
|
263
|
+
email: { type: string }
|
|
264
|
+
additionalProperties: true
|
|
265
|
+
Brain:
|
|
266
|
+
type: object
|
|
267
|
+
required: [id, name, size_bytes, file_count, checksum, last_synced_at, created_at]
|
|
268
|
+
properties:
|
|
269
|
+
id: { type: string, format: uuid }
|
|
270
|
+
name: { type: string }
|
|
271
|
+
size_bytes: { type: integer }
|
|
272
|
+
file_count: { type: integer, description: Regular-file entries in the archive. }
|
|
273
|
+
checksum: { type: [string, "null"], description: Lowercase hex SHA-256 of the archive. }
|
|
274
|
+
last_synced_at: { type: [string, "null"], format: date-time }
|
|
275
|
+
created_at: { type: string, format: date-time }
|
|
276
|
+
additionalProperties: true
|
|
277
|
+
SyncResult:
|
|
278
|
+
type: object
|
|
279
|
+
required: [size_bytes, file_count, checksum]
|
|
280
|
+
properties:
|
|
281
|
+
size_bytes: { type: integer }
|
|
282
|
+
file_count: { type: integer }
|
|
283
|
+
checksum: { type: string }
|
|
284
|
+
Error:
|
|
285
|
+
type: object
|
|
286
|
+
required: [error]
|
|
287
|
+
properties:
|
|
288
|
+
error: { type: string, description: Human-readable. Do not parse. }
|
|
289
|
+
additionalProperties: true
|
|
290
|
+
|
|
291
|
+
responses:
|
|
292
|
+
Error:
|
|
293
|
+
description: The request failed.
|
|
294
|
+
content:
|
|
295
|
+
application/json:
|
|
296
|
+
schema: { $ref: "#/components/schemas/Error" }
|
|
297
|
+
Unauthorized:
|
|
298
|
+
description: Missing, unknown or expired token.
|
|
299
|
+
content:
|
|
300
|
+
application/json:
|
|
301
|
+
schema: { $ref: "#/components/schemas/Error" }
|
|
302
|
+
RateLimited:
|
|
303
|
+
description: Too many requests.
|
|
304
|
+
headers:
|
|
305
|
+
Retry-After: { schema: { type: integer }, description: Seconds to wait. }
|
|
306
|
+
content:
|
|
307
|
+
application/json:
|
|
308
|
+
schema: { $ref: "#/components/schemas/Error" }
|
|
309
|
+
PreconditionFailed:
|
|
310
|
+
description: (1.1) The stored archive is not the one the client named. Nothing changed.
|
|
311
|
+
content:
|
|
312
|
+
application/json:
|
|
313
|
+
schema:
|
|
314
|
+
type: object
|
|
315
|
+
required: [error]
|
|
316
|
+
properties:
|
|
317
|
+
error: { type: string }
|
|
318
|
+
current_checksum: { type: [string, "null"] }
|