cloudrop 0.0.0 → 0.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.
- package/CHANGELOG.md +56 -0
- package/LICENSE +21 -0
- package/README.md +98 -3
- package/dist/adapters/drizzle.d.ts +204 -0
- package/dist/adapters/drizzle.js +216 -0
- package/dist/adapters/drizzle.js.map +1 -0
- package/dist/adapters/prisma.d.ts +81 -0
- package/dist/adapters/prisma.js +32 -0
- package/dist/adapters/prisma.js.map +1 -0
- package/dist/adapters/sql.d.ts +98 -0
- package/dist/adapters/sql.js +70 -0
- package/dist/adapters/sql.js.map +1 -0
- package/dist/client-Dj6ON4MN.d.ts +214 -0
- package/dist/client-Y1zUEbCj.js +1561 -0
- package/dist/client-Y1zUEbCj.js.map +1 -0
- package/dist/client.d.ts +3 -0
- package/dist/client.js +3 -0
- package/dist/d1-BY2c5bcL.js +16 -0
- package/dist/d1-BY2c5bcL.js.map +1 -0
- package/dist/errors-CUxMmFAe.js +40 -0
- package/dist/errors-CUxMmFAe.js.map +1 -0
- package/dist/executor-CEA7WV2W.d.ts +27 -0
- package/dist/index.d.ts +421 -0
- package/dist/index.js +3007 -0
- package/dist/index.js.map +1 -0
- package/dist/input-DTC476_I.js +13 -0
- package/dist/input-DTC476_I.js.map +1 -0
- package/dist/next.d.ts +9 -0
- package/dist/next.js +14 -0
- package/dist/next.js.map +1 -0
- package/dist/node.d.ts +32 -0
- package/dist/node.js +100 -0
- package/dist/node.js.map +1 -0
- package/dist/part-size-CvMoobfC.js +9 -0
- package/dist/part-size-CvMoobfC.js.map +1 -0
- package/dist/react.d.ts +123 -0
- package/dist/react.js +355 -0
- package/dist/react.js.map +1 -0
- package/dist/route-CspI1Ypt.js +72 -0
- package/dist/route-CspI1Ypt.js.map +1 -0
- package/dist/store-BfCJejGh.d.ts +382 -0
- package/dist/tables-DZnw2sPK.d.ts +11 -0
- package/dist/transactional-DnvnGsVH.js +672 -0
- package/dist/transactional-DnvnGsVH.js.map +1 -0
- package/dist/types-BZUOaz_B.js +5 -0
- package/dist/types-BZUOaz_B.js.map +1 -0
- package/dist/types-BrAx3dA4.d.ts +185 -0
- package/package.json +108 -4
|
@@ -0,0 +1,382 @@
|
|
|
1
|
+
import { T as UploadedFile, d as Jsonified } from "./types-BrAx3dA4.js";
|
|
2
|
+
interface StandardSchema<Input = unknown, Output = Input> {
|
|
3
|
+
readonly "~standard": {
|
|
4
|
+
readonly version: 1;
|
|
5
|
+
readonly vendor: string;
|
|
6
|
+
readonly validate: (value: unknown) => StandardResult<Output> | Promise<StandardResult<Output>>;
|
|
7
|
+
readonly types?: {
|
|
8
|
+
readonly input: Input;
|
|
9
|
+
readonly output: Output;
|
|
10
|
+
} | undefined;
|
|
11
|
+
};
|
|
12
|
+
}
|
|
13
|
+
type StandardResult<Output> = {
|
|
14
|
+
readonly value: Output;
|
|
15
|
+
readonly issues?: undefined;
|
|
16
|
+
} | {
|
|
17
|
+
readonly issues: ReadonlyArray<StandardIssue>;
|
|
18
|
+
};
|
|
19
|
+
interface StandardIssue {
|
|
20
|
+
readonly message: string;
|
|
21
|
+
readonly path?: ReadonlyArray<PropertyKey | {
|
|
22
|
+
readonly key: PropertyKey;
|
|
23
|
+
}> | undefined;
|
|
24
|
+
}
|
|
25
|
+
type SchemaInput<TSchema> = TSchema extends StandardSchema<infer Input, unknown> ? Input : undefined;
|
|
26
|
+
type SchemaOutput<TSchema> = TSchema extends StandardSchema<unknown, infer Output> ? Output : undefined;
|
|
27
|
+
/** A size in bytes, or a number with a unit: "512KB", "5MB", "1.5GB". KB, MB, GB and TB are binary (1 KB = 1024 bytes). */
|
|
28
|
+
type Size = number | `${number}${"B" | "KB" | "MB" | "GB" | "TB" | "KiB" | "MiB" | "GiB" | "TiB"}`;
|
|
29
|
+
type Awaitable<T> = T | Promise<T>;
|
|
30
|
+
declare const DENIED: unique symbol;
|
|
31
|
+
declare const STORE: unique symbol;
|
|
32
|
+
/**
|
|
33
|
+
* Returned by `authorize` to refuse an upload: `unauthorized()` answers UNAUTHORIZED (401), `forbidden()` FORBIDDEN
|
|
34
|
+
* (403), with `message`.
|
|
35
|
+
*/
|
|
36
|
+
interface Refusal {
|
|
37
|
+
readonly [DENIED]: true;
|
|
38
|
+
/** Absent on a refusal from a copy of cloudrop that predates forbidden(): it means UNAUTHORIZED. */
|
|
39
|
+
readonly code?: "UNAUTHORIZED" | "FORBIDDEN";
|
|
40
|
+
readonly message: string;
|
|
41
|
+
}
|
|
42
|
+
/** For a caller who is not signed in. */
|
|
43
|
+
declare function unauthorized(message?: string): Refusal;
|
|
44
|
+
/** For a signed-in caller who may not upload this: a quota, a plan or a role. */
|
|
45
|
+
declare function forbidden(message?: string): Refusal;
|
|
46
|
+
/** `authorize: allowAnyone` makes a route public. It must be written out: public uploads are never a default. */
|
|
47
|
+
declare function allowAnyone(): object;
|
|
48
|
+
/** Names cloudrop puts into every route context; an authorize result's own fields with these names are replaced. */
|
|
49
|
+
type ReservedName = "request" | "metadata" | "file";
|
|
50
|
+
interface AuthorizeContext<TMetadata> {
|
|
51
|
+
request: Request;
|
|
52
|
+
metadata: TMetadata;
|
|
53
|
+
}
|
|
54
|
+
/** `owner` sees the live authorize result inside `/upload`, once for all of its files. */
|
|
55
|
+
type OwnerContext<TAuth, TMetadata> = Omit<TAuth, ReservedName> & {
|
|
56
|
+
request: Request;
|
|
57
|
+
metadata: TMetadata;
|
|
58
|
+
};
|
|
59
|
+
/** `prefix` and `key` see the live authorize result; this runs inside `/upload`, once per file. */
|
|
60
|
+
type KeyContext<TAuth, TMetadata> = OwnerContext<TAuth, TMetadata> & {
|
|
61
|
+
file: {
|
|
62
|
+
id: string;
|
|
63
|
+
name: string;
|
|
64
|
+
size: number;
|
|
65
|
+
type: string;
|
|
66
|
+
ext: string;
|
|
67
|
+
};
|
|
68
|
+
};
|
|
69
|
+
/** `onComplete` runs inside `/complete`, so it sees what the token carried: the JSON form of each value. */
|
|
70
|
+
type CompleteContext<TAuth, TMetadata> = Omit<Jsonified<TAuth>, ReservedName> & {
|
|
71
|
+
request: Request;
|
|
72
|
+
file: UploadedFile;
|
|
73
|
+
/** undefined on a route without a schema, and possibly undefined when the schema's output can be. */
|
|
74
|
+
metadata: Jsonified<TMetadata> | (undefined extends TMetadata ? undefined : never);
|
|
75
|
+
};
|
|
76
|
+
/** What `/complete` sends as `data`: the JSON form of the result, and null where `onComplete` gave undefined or nothing. */
|
|
77
|
+
type CompleteData<TResult> = Jsonified<TResult> | (undefined extends TResult ? null : never);
|
|
78
|
+
/** `afterComplete` sees what `onComplete` sees, plus the `data` the client was sent. */
|
|
79
|
+
type AfterCompleteContext<TAuth, TMetadata, TResult> = CompleteContext<TAuth, TMetadata> & {
|
|
80
|
+
data: CompleteData<Awaited<TResult>>;
|
|
81
|
+
};
|
|
82
|
+
/** A store's extra context (an adapter's `tx`) replaces an authorize field of the same name. */
|
|
83
|
+
type WithExtra<TContext, TExtra> = [keyof TExtra] extends [never] ? TContext : Omit<TContext, keyof TExtra> & TExtra;
|
|
84
|
+
type NoExtra = Record<never, never>;
|
|
85
|
+
/** route()'s first argument: every option that is not typed from authorize's result. */
|
|
86
|
+
interface RoutePolicy<TAuth extends object, TSchema extends StandardSchema | undefined> {
|
|
87
|
+
/** MIME types such as "image/png", "image/*" or "*\/*". The file name's extension must agree with the type. */
|
|
88
|
+
accept: string | readonly string[];
|
|
89
|
+
/** Bytes, or "5MB" style (binary units). */
|
|
90
|
+
maxSize: Size;
|
|
91
|
+
/** Files per `/upload` call, 1 to 100. Default 10. */
|
|
92
|
+
maxFiles?: number;
|
|
93
|
+
/** Any Standard Schema (zod, valibot, arktype). Its output, as JSON, must fit in 2 KiB. */
|
|
94
|
+
metadata?: TSchema;
|
|
95
|
+
/** "public" needs the storage's `publicUrl`. Default: "public" when the storage has one, otherwise "private". */
|
|
96
|
+
visibility?: "public" | "private";
|
|
97
|
+
/**
|
|
98
|
+
* Required. Return a plain object with the facts later steps need (they are signed into the upload token, which the
|
|
99
|
+
* browser can read: return ids, never secrets), or `unauthorized()` or `forbidden()`. `allowAnyone` makes the route
|
|
100
|
+
* public.
|
|
101
|
+
*
|
|
102
|
+
* It runs only in `/upload`. The token it signs is the authority for the next 24 hours, so a session revoked
|
|
103
|
+
* mid-upload can still finish that upload; check the session again in `onComplete` when that matters.
|
|
104
|
+
*/
|
|
105
|
+
authorize: (context: AuthorizeContext<SchemaOutput<TSchema>>) => Awaitable<TAuth | Refusal>;
|
|
106
|
+
}
|
|
107
|
+
/**
|
|
108
|
+
* route()'s second argument: the callbacks typed from authorize's result. A separate argument because TypeScript
|
|
109
|
+
* infers from callbacks left to right within one object, so one written before authorize would see `object`.
|
|
110
|
+
*/
|
|
111
|
+
interface RouteCallbacks<TAuth extends object, TMetadata, TResult, TExtra extends object = NoExtra> {
|
|
112
|
+
/** Folder for generated keys `<prefix>/<ulid><ext>`. Sanitized like every key. */
|
|
113
|
+
prefix?: (context: KeyContext<TAuth, TMetadata>) => string;
|
|
114
|
+
/**
|
|
115
|
+
* The whole key instead of `<prefix>/<ulid><ext>`. Sanitized like every key. It must be unique: a rejected or
|
|
116
|
+
* aborted upload's object is deleted by key once a HEAD, or a create-only completion, shows the object is this
|
|
117
|
+
* upload's. The delete is not conditional, so another file stored under the same key between the two requests
|
|
118
|
+
* would be deleted.
|
|
119
|
+
*/
|
|
120
|
+
key?: (context: KeyContext<TAuth, TMetadata>) => string;
|
|
121
|
+
/**
|
|
122
|
+
* Runs inside `/complete`, at least once per file; its JSON result reaches the client as `data`.
|
|
123
|
+
*
|
|
124
|
+
* `authorize` is not called again here: `request` carries the caller's cookies and headers, so re-check a session
|
|
125
|
+
* that may have been revoked since `/upload`. Until the token expires (24 hours after `/upload`), whoever holds it
|
|
126
|
+
* can also delete this file through `/abort`, even after `onComplete` has run. A database store closes that gap and
|
|
127
|
+
* runs `onComplete` once per file: inside the store's transaction with `tx` when its route comes from the store's own
|
|
128
|
+
* `route()`, otherwise again only after a crash between claiming the file and recording its completion.
|
|
129
|
+
*/
|
|
130
|
+
onComplete?: (context: WithExtra<CompleteContext<TAuth, TMetadata>, TExtra>) => Awaitable<TResult>;
|
|
131
|
+
/**
|
|
132
|
+
* With a store: who the file counts against for `quota` and `api.usage`, 1 to 255 characters, or null for no one.
|
|
133
|
+
* Runs once per `/upload`. Not the authorize result signed into the token; return an id, such as a user or team id.
|
|
134
|
+
*/
|
|
135
|
+
owner?: (context: OwnerContext<TAuth, TMetadata>) => Awaitable<string | null>;
|
|
136
|
+
/**
|
|
137
|
+
* With a store: runs after the completion is recorded, at most once per file and best effort. A crash right after the
|
|
138
|
+
* recording skips it, and a throw is logged while the client still gets its answer, which waits for it: keep it short.
|
|
139
|
+
* Call storage and other network services here, not in `onComplete`; for work that must happen, write an outbox row
|
|
140
|
+
* through `tx` in `onComplete`. Write it after `onComplete`: TypeScript infers `data`'s type from `onComplete` only
|
|
141
|
+
* when `onComplete` comes first.
|
|
142
|
+
*/
|
|
143
|
+
afterComplete?: (context: AfterCompleteContext<TAuth, TMetadata, TResult>) => Awaitable<void>;
|
|
144
|
+
}
|
|
145
|
+
/**
|
|
146
|
+
* A route with its types erased, as the server runs it. Method syntax makes the typed callbacks assignable: route()
|
|
147
|
+
* has already checked each one against its own context type.
|
|
148
|
+
*/
|
|
149
|
+
interface RouteDefinition {
|
|
150
|
+
accept: string | readonly string[];
|
|
151
|
+
maxSize: Size;
|
|
152
|
+
maxFiles?: number;
|
|
153
|
+
metadata?: StandardSchema;
|
|
154
|
+
visibility?: "public" | "private";
|
|
155
|
+
authorize(context: AuthorizeContext<unknown>): Awaitable<unknown>;
|
|
156
|
+
prefix?(context: KeyContext<object, unknown>): string;
|
|
157
|
+
key?(context: KeyContext<object, unknown>): string;
|
|
158
|
+
owner?(context: OwnerContext<object, unknown>): Awaitable<string | null>;
|
|
159
|
+
onComplete?(context: {
|
|
160
|
+
request: Request;
|
|
161
|
+
file: UploadedFile;
|
|
162
|
+
metadata: unknown;
|
|
163
|
+
}): unknown;
|
|
164
|
+
afterComplete?(context: {
|
|
165
|
+
request: Request;
|
|
166
|
+
file: UploadedFile;
|
|
167
|
+
metadata: unknown;
|
|
168
|
+
data: unknown;
|
|
169
|
+
}): unknown;
|
|
170
|
+
/** The store whose `route()` made this route, whose `tx` its `onComplete` expects. */
|
|
171
|
+
readonly [STORE]?: object;
|
|
172
|
+
}
|
|
173
|
+
interface Route<TMetadataInput = unknown, TResult = unknown> {
|
|
174
|
+
readonly definition: RouteDefinition;
|
|
175
|
+
/** Type-only: never set at runtime. */
|
|
176
|
+
readonly "~types"?: {
|
|
177
|
+
readonly metadata: TMetadataInput;
|
|
178
|
+
readonly result: TResult;
|
|
179
|
+
};
|
|
180
|
+
}
|
|
181
|
+
/**
|
|
182
|
+
* An upload route: `route({ accept, maxSize, authorize }, { prefix, onComplete })`. The second argument is optional
|
|
183
|
+
* and typed from what `authorize` returns.
|
|
184
|
+
*/
|
|
185
|
+
declare function route<TAuth extends object, TSchema extends StandardSchema | undefined = undefined, TResult = null>(policy: RoutePolicy<TAuth, TSchema>, callbacks?: RouteCallbacks<TAuth, SchemaOutput<TSchema>, TResult>): NoInfer<Route<SchemaInput<TSchema>, CompleteData<Awaited<TResult>>>>;
|
|
186
|
+
/** route(), typed with a store's extra `onComplete` context. */
|
|
187
|
+
type RouteFunction<TExtra extends object> = <TAuth extends object, TSchema extends StandardSchema | undefined = undefined, TResult = null>(policy: RoutePolicy<TAuth, TSchema>, callbacks?: RouteCallbacks<TAuth, SchemaOutput<TSchema>, TResult, TExtra>) => NoInfer<Route<SchemaInput<TSchema>, CompleteData<Awaited<TResult>>>>;
|
|
188
|
+
/** Where a file's row stands. `pending` until a `/complete` claims it; the five ended statuses never change again. */
|
|
189
|
+
type FileStatus = "pending" | "completing" | "completed" | "aborted" | "rejected" | "failed" | "expired" | "deleted";
|
|
190
|
+
/** The statuses `end` can move a row to. */
|
|
191
|
+
type EndedStatus = "aborted" | "rejected" | "failed" | "expired" | "deleted";
|
|
192
|
+
/** One accepted file of an `/upload`, written before anything is signed. */
|
|
193
|
+
interface NewFile {
|
|
194
|
+
/** The file id from the upload token and the object's `cloudrop-id`; the row's primary key. */
|
|
195
|
+
id: string;
|
|
196
|
+
route: string;
|
|
197
|
+
/** The object key. Not unique: a route may upload the same key again after a cancel. */
|
|
198
|
+
key: string;
|
|
199
|
+
name: string;
|
|
200
|
+
type: string;
|
|
201
|
+
/** Bytes, as signed. */
|
|
202
|
+
size: number;
|
|
203
|
+
/** The validated metadata as JSON, or null. */
|
|
204
|
+
metadata: string | null;
|
|
205
|
+
}
|
|
206
|
+
/** A file's row as the store holds it. Times are `Date`s whatever the database keeps. */
|
|
207
|
+
interface FileRecord extends NewFile {
|
|
208
|
+
/** The quota owner from the route's `owner` callback, or null. Not the token's `owner` (the `authorize` JSON). */
|
|
209
|
+
owner: string | null;
|
|
210
|
+
status: FileStatus;
|
|
211
|
+
/** The multipart upload id once `attach` stored it. */
|
|
212
|
+
uploadId: string | null;
|
|
213
|
+
/** `onComplete`'s result as JSON, once completed. */
|
|
214
|
+
result: string | null;
|
|
215
|
+
/** The upload token's deadline. */
|
|
216
|
+
expiresAt: Date;
|
|
217
|
+
createdAt: Date;
|
|
218
|
+
claimedAt: Date | null;
|
|
219
|
+
completedAt: Date | null;
|
|
220
|
+
/** When the row reached an ended status (`deleted` included). */
|
|
221
|
+
endedAt: Date | null;
|
|
222
|
+
/** When the sweep finished removing what the upload left in the bucket. */
|
|
223
|
+
cleanedAt: Date | null;
|
|
224
|
+
}
|
|
225
|
+
/** What `claim` found. Only `claimed` lets the caller run `onComplete`. */
|
|
226
|
+
type ClaimOutcome = {
|
|
227
|
+
kind: "claimed";
|
|
228
|
+
} | {
|
|
229
|
+
kind: "completed";
|
|
230
|
+
record: FileRecord;
|
|
231
|
+
} | {
|
|
232
|
+
kind: "busy";
|
|
233
|
+
} | {
|
|
234
|
+
kind: "ended";
|
|
235
|
+
record: FileRecord;
|
|
236
|
+
} | {
|
|
237
|
+
kind: "missing";
|
|
238
|
+
};
|
|
239
|
+
/** The answer of a guarded status change. */
|
|
240
|
+
type Transition = {
|
|
241
|
+
changed: true;
|
|
242
|
+
record: FileRecord;
|
|
243
|
+
} | {
|
|
244
|
+
changed: false;
|
|
245
|
+
record: FileRecord | null;
|
|
246
|
+
};
|
|
247
|
+
/** An owner's counters, kept for every row with an owner whether or not a quota is set. */
|
|
248
|
+
interface OwnerUsage {
|
|
249
|
+
/** Bytes of the owner's `pending` and `completing` rows. */
|
|
250
|
+
reservedBytes: number;
|
|
251
|
+
/** Bytes of the owner's `completed` rows. */
|
|
252
|
+
activeBytes: number;
|
|
253
|
+
/** The owner's `completed` rows (a `deleted` row no longer counts). */
|
|
254
|
+
files: number;
|
|
255
|
+
}
|
|
256
|
+
/**
|
|
257
|
+
* A database store. Each method is one atomic unit: either everything it describes is written, or it throws and nothing
|
|
258
|
+
* is. Methods throw only on a database failure; every expected outcome is in the return value, and the server answers
|
|
259
|
+
* any throw with a retryable `SERVER_ERROR` and logs it. Times come from the server as `now`; the store keeps them as
|
|
260
|
+
* given. Every write also sets the row's `updated_at` to `now`.
|
|
261
|
+
*
|
|
262
|
+
* Usage counters change only for rows with an owner, always in the same unit as the status change that moves the bytes.
|
|
263
|
+
* A change that moves no bytes (an owner-less row, or leaving an ended status) does not write the usage row at all.
|
|
264
|
+
* `TTx` is the transaction handle `onComplete` receives when the store has `transaction`.
|
|
265
|
+
*/
|
|
266
|
+
interface CloudropStore<TTx = never> {
|
|
267
|
+
/**
|
|
268
|
+
* Writes the accepted files of one `/upload` as `pending` rows of one owner, adding each reserved file's size to the
|
|
269
|
+
* owner's reserved bytes. With an owner and a `limit`, each file in order is reserved only when the owner's
|
|
270
|
+
* `reservedBytes + activeBytes + size <= limit` (counting the files reserved before it in this call); otherwise it is
|
|
271
|
+
* `"over-quota"` and nothing of it is written. The quota applies from the first file of an owner the store has never
|
|
272
|
+
* counted (no usage row yet counts as zeros). Without an owner the limit does not apply and no usage is written. The
|
|
273
|
+
* owner's usage row is created by its first reserved file, so a call that reserves nothing leaves none. A file whose
|
|
274
|
+
* id already has a row makes the call throw (a primary-key violation, never `ON CONFLICT DO NOTHING`), and then
|
|
275
|
+
* nothing of the call is written. Atomic for the whole call. Answers one outcome per file, in order.
|
|
276
|
+
*
|
|
277
|
+
* `requestKey` is the `/upload` request's idempotency key, stored on every row written. When it is not null, the call
|
|
278
|
+
* first ends as `aborted` (`ended_at = now`, `cleaned_at` left null for the sweep) every `pending` row with this key,
|
|
279
|
+
* the route of the call's files and the same owner (null matches null), releasing their reserved bytes, so the quota
|
|
280
|
+
* check of the new files counts without them: a retry supersedes an attempt whose answer was lost. Rows in any other
|
|
281
|
+
* status are left alone. The rows are superseded whatever the new files' outcomes, even when every one is over the
|
|
282
|
+
* quota, and not at all when the call throws. A call with no files writes nothing. The server passes a key only with
|
|
283
|
+
* an owner (M5-T105): owner-less rows hold no quota, so superseding them would free nothing. A store that ignores
|
|
284
|
+
* `requestKey` keeps the old cost: lost answers hold their bytes until the sweep.
|
|
285
|
+
*/
|
|
286
|
+
reserve(input: {
|
|
287
|
+
owner: string | null;
|
|
288
|
+
limit: number | null;
|
|
289
|
+
expiresAt: Date;
|
|
290
|
+
requestKey: string | null;
|
|
291
|
+
files: readonly NewFile[];
|
|
292
|
+
}, now: Date): Promise<readonly ("reserved" | "over-quota")[]>;
|
|
293
|
+
/** Stores the multipart upload id on a `pending` row whose `upload_id` is null or already this id: true, and
|
|
294
|
+
* `updated_at = now` (a repeat stamps it again). False for any other row, or none, which is left unchanged. */
|
|
295
|
+
attach(id: string, uploadId: string, now: Date): Promise<boolean>;
|
|
296
|
+
get(id: string): Promise<FileRecord | null>;
|
|
297
|
+
/**
|
|
298
|
+
* Takes the row for one `/complete`: a `pending` row, or a `completing` one claimed more than `leaseMs` before `now`,
|
|
299
|
+
* becomes `completing` with this claim and `claimed_at = now`. A claim is live through exactly `leaseMs`: at
|
|
300
|
+
* `claimed_at + leaseMs` the row is still `busy`, one millisecond later it can be taken. A `completing` row with a live
|
|
301
|
+
* claim is `busy` even for the token that holds it (the store does not know who holds a token). `expires_at` is not
|
|
302
|
+
* read: the server refuses a dead token before it claims. `completed` answers the record (a replay), an ended status
|
|
303
|
+
* `ended` with the record; neither changes the row.
|
|
304
|
+
*/
|
|
305
|
+
claim(id: string, claim: string, now: Date, leaseMs: number): Promise<ClaimOutcome>;
|
|
306
|
+
/** Hands a claimed row back after `onComplete` threw: `completing` with this claim → `pending`, its claim and
|
|
307
|
+
* `claimed_at` cleared, usage untouched. False when the row holds another claim or another status. */
|
|
308
|
+
release(id: string, claim: string, now: Date): Promise<boolean>;
|
|
309
|
+
/**
|
|
310
|
+
* `completing` with this claim → `completed` with `result` and `completed_at = now`; the owner's reserved bytes drop
|
|
311
|
+
* by the size, active bytes rise by it and files by one. Unchanged for any other row: a repeat answers the completed
|
|
312
|
+
* row, a lost claim the row another `/complete` holds. `claim` and `claimed_at` stay as they were, recording which
|
|
313
|
+
* claim completed the row.
|
|
314
|
+
*/
|
|
315
|
+
complete(id: string, claim: string, result: string | null, now: Date): Promise<Transition>;
|
|
316
|
+
/**
|
|
317
|
+
* Moves a row from exactly `from` to `to` and sets `ended_at = now`; `cleaned: true` also sets `cleaned_at = now`.
|
|
318
|
+
* Usage follows `from`: `pending` or `completing` releases the reserved bytes; `completed` releases the active bytes
|
|
319
|
+
* and one file; an ended status releases nothing. `claim` and `claimed_at` stay as they were. Unchanged when the
|
|
320
|
+
* row is in another status, or missing.
|
|
321
|
+
*/
|
|
322
|
+
end(id: string, from: FileStatus, to: EndedStatus, now: Date, options?: {
|
|
323
|
+
cleaned?: boolean;
|
|
324
|
+
}): Promise<Transition>;
|
|
325
|
+
/** Ends every `pending` row of one owner as `aborted`, releasing their reserved bytes. `completing` and later rows
|
|
326
|
+
* stay. Answers how many rows changed. */
|
|
327
|
+
revoke(owner: string, now: Date): Promise<number>;
|
|
328
|
+
/**
|
|
329
|
+
* One page of sweep work, ordered by its time column, then id. `"expire"`: `pending` rows with `expires_at < before`,
|
|
330
|
+
* and `completing` rows with `expires_at < before` and `claimed_at < claimedBefore`, by `expires_at`. `"cleanup"`:
|
|
331
|
+
* `aborted`, `rejected`, `failed`, `expired` and `deleted` rows with `cleaned_at` null and `ended_at < before`, by
|
|
332
|
+
* `ended_at`.
|
|
333
|
+
* At most `limit` records; `cursor` continues after the previous page (keyset, so rows that leave the set between
|
|
334
|
+
* pages skip nothing) and is null on the last page. A cursor is `<milliseconds>:<id>`, the last row's time and id
|
|
335
|
+
* (the sweep refuses any other before calling the store), and is valid only for its own kind.
|
|
336
|
+
*/
|
|
337
|
+
stale(input: {
|
|
338
|
+
kind: "expire" | "cleanup";
|
|
339
|
+
before: Date;
|
|
340
|
+
claimedBefore: Date;
|
|
341
|
+
limit: number;
|
|
342
|
+
cursor: string | null;
|
|
343
|
+
}): Promise<{
|
|
344
|
+
records: FileRecord[];
|
|
345
|
+
cursor: string | null;
|
|
346
|
+
}>;
|
|
347
|
+
/** Sets `cleaned_at = now` on a row that has none; a cleaned or missing row is left as it is. */
|
|
348
|
+
cleaned(id: string, now: Date): Promise<void>;
|
|
349
|
+
/** The owner's counters; zeros for an owner the store has never counted. */
|
|
350
|
+
usage(owner: string): Promise<OwnerUsage>;
|
|
351
|
+
/**
|
|
352
|
+
* Repairs an owner's counters: locks the owner's usage row, then recounts it from the owner's rows, so a concurrent
|
|
353
|
+
* `reserve` is never lost. When the owner has rows but no usage row, it creates the row (on Postgres: insert it
|
|
354
|
+
* with `ON CONFLICT DO NOTHING`, then lock, then recount, in one transaction). A missing row counts as zeros, so an
|
|
355
|
+
* owner whose recount is all zeros gets no row. True when a counter changed (or the row was created). Writes only
|
|
356
|
+
* then, and stamps `updated_at` with the database's clock, as no time is passed.
|
|
357
|
+
*/
|
|
358
|
+
reconcile(owner: string): Promise<boolean>;
|
|
359
|
+
/**
|
|
360
|
+
* One page of the owners that have counters, in the database's order of owner; `cursor` continues after the
|
|
361
|
+
* previous page (keyset) and is null on the last page.
|
|
362
|
+
*/
|
|
363
|
+
owners(cursor: string | null, limit: number): Promise<{
|
|
364
|
+
owners: string[];
|
|
365
|
+
cursor: string | null;
|
|
366
|
+
}>;
|
|
367
|
+
/**
|
|
368
|
+
* Runs `run` in one interactive database transaction and commits when it resolves; a throw rolls back every write
|
|
369
|
+
* made through `tx` or the given `store` and is rethrown. Only stores that can hold one (Postgres) have it.
|
|
370
|
+
*/
|
|
371
|
+
transaction?<T>(run: (tx: TTx, store: Omit<CloudropStore<TTx>, "transaction">) => Promise<T>): Promise<T>;
|
|
372
|
+
}
|
|
373
|
+
/**
|
|
374
|
+
* A store built with `transaction: true`: completions run in its transaction, and `route` makes the routes whose
|
|
375
|
+
* `onComplete` receives that transaction as `tx`. Its routes work only with this very store passed to `createCloudrop`.
|
|
376
|
+
*/
|
|
377
|
+
type TransactionalStore<TTx> = CloudropStore<TTx> & Required<Pick<CloudropStore<TTx>, "transaction">> & {
|
|
378
|
+
route: RouteFunction<{
|
|
379
|
+
tx: TTx;
|
|
380
|
+
}>;
|
|
381
|
+
};
|
|
382
|
+
export { forbidden as C, StandardSchema as D, Size as E, allowAnyone as S, unauthorized as T, Route as _, FileStatus as a, RouteFunction as b, TransactionalStore as c, AuthorizeContext as d, Awaitable as f, Refusal as g, OwnerContext as h, FileRecord as i, Transition as l, KeyContext as m, CloudropStore as n, NewFile as o, CompleteContext as p, EndedStatus as r, OwnerUsage as s, ClaimOutcome as t, AfterCompleteContext as u, RouteCallbacks as v, route as w, RoutePolicy as x, RouteDefinition as y };
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
/** The table names a store is built with (spec §3); columns are fixed. */
|
|
2
|
+
interface StoreTables {
|
|
3
|
+
files?: string;
|
|
4
|
+
usage?: string;
|
|
5
|
+
/**
|
|
6
|
+
* Postgres only: the schema both tables live in, such as `"app"`. Without it the statements name the tables alone,
|
|
7
|
+
* and the connection's search path finds them.
|
|
8
|
+
*/
|
|
9
|
+
schema?: string;
|
|
10
|
+
}
|
|
11
|
+
export { StoreTables as t };
|