@guren/core 1.12.0 → 1.13.1
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/dist/agent.d.ts +1 -0
- package/dist/agent.js +2 -0
- package/dist/index.d.ts +174 -429
- package/dist/index.js +165 -395
- package/dist/internal/deploy-build.d.ts +123 -196
- package/dist/internal/deploy-build.js +166 -279
- package/package.json +8 -4
package/dist/index.d.ts
CHANGED
|
@@ -2,43 +2,21 @@ import { ApiToken, ApiTokenStore, Command, Controller, Job, OAuthStatePayload, O
|
|
|
2
2
|
import { AccessorDefinitions, AccessorFn, AwsDataApiDatabase, AwsDataApiDatabaseOptions, AwsDataApiSeederContext, BelongsToManyRecord, BelongsToManyRelationResult, BelongsToRecord, BelongsToRelationResult, BelongsToRequiredRecord, CastType, D1DatabaseHandle, D1DatabaseOptions, DrizzleAdapter, EagerLoadConstraint, FindManyOptions, GroupCondition, HasManyRecord, HasManyRelationResult, HasManyThroughRecord, HasManyThroughRelationResult, HasOneRecord, HasOneRelationResult, HookCallback, HookName, InferModelInsert, InferModelRecord, MassAssignmentException, MigrationRunSummary, MigrationStatusEntry, Model, Model as Model$1, ModelHooks, ModelNotFoundException, ModelObserver, ModelObserverConstructor, ModelPaginationMeta, ModelQueryOptions, MorphManyRecord, MorphManyRelationResult, MorphToRecord, MorphToRelationResult, MutatorDefinitions, MutatorFn, MySqlDatabase, MySqlDatabaseOptions, MySqlSeederContext, ORMAdapter, ORMAdapterAdvanced, OrderByClause, OrderByInput, OrderDefinition, OrderDirection, PaginateOptions, PaginatedResult, PlainObject, PlainObject as PlainObject$1, PostgresDatabase, PostgresDatabaseOptions, PostgresSeederContext, QueryBuilder, QueryBuilderOptions, ScopeFunction, SeederContext, SeederHandler, SeederRunSummary, SimpleCondition, SoftDeletes, SoftDeletesStatic, SqliteDatabase, SqliteDatabaseOptions, SqliteSeederContext, TransactionHandle, TransactionModelScope, WhereClause, WhereCondition, WhereGroupCallback, WhereOperator, WithRelations, createAwsDataApiDatabase, createD1Database, createMySqlDatabase, createPostgresDatabase, createSqliteDatabase, defineModel, defineSeeder, runSeeders } from "@guren/orm";
|
|
3
3
|
export * from "@guren/server";
|
|
4
4
|
//#region src/api-token-store.d.ts
|
|
5
|
-
/**
|
|
6
|
-
* Options for DatabaseApiTokenStore.
|
|
7
|
-
*/
|
|
8
5
|
interface DatabaseApiTokenStoreOptions {
|
|
9
6
|
/**
|
|
10
|
-
* How the `abilities` column stores the ability list
|
|
11
|
-
*
|
|
12
|
-
*
|
|
13
|
-
*
|
|
14
|
-
* - `'text'` serializes to a JSON string for plain text columns.
|
|
15
|
-
*
|
|
16
|
-
* Reads always accept both representations.
|
|
7
|
+
* How the `abilities` column stores the ability list: `'json'` (default)
|
|
8
|
+
* passes the array through for a JSON-capable column (pg `jsonb`/`json`,
|
|
9
|
+
* sqlite `text(..., { mode: 'json' })`); `'text'` serializes to a JSON string.
|
|
10
|
+
* Reads accept both.
|
|
17
11
|
* @default 'json'
|
|
18
12
|
*/
|
|
19
13
|
abilitiesMode?: 'json' | 'text';
|
|
20
14
|
}
|
|
21
15
|
/**
|
|
22
|
-
* Database-backed API token store built on the Guren ORM.
|
|
23
|
-
*
|
|
24
|
-
*
|
|
25
|
-
*
|
|
26
|
-
* `hashedToken`, `userId`, `abilities`, `lastUsedAt`, `expiresAt`,
|
|
27
|
-
* `createdAt`). The ORM must be configured (the standard
|
|
28
|
-
* `DatabaseProvider` setup) before the store is used.
|
|
29
|
-
*
|
|
30
|
-
* @example
|
|
31
|
-
* ```ts
|
|
32
|
-
* import { DatabaseApiTokenStore, createApiToken } from '@guren/core'
|
|
33
|
-
* import { apiTokens } from '@/db/schema'
|
|
34
|
-
*
|
|
35
|
-
* const store = new DatabaseApiTokenStore(apiTokens)
|
|
36
|
-
*
|
|
37
|
-
* const { plainTextToken } = await createApiToken(store, {
|
|
38
|
-
* name: 'Mobile App Token',
|
|
39
|
-
* userId: user.id,
|
|
40
|
-
* })
|
|
41
|
-
* ```
|
|
16
|
+
* Database-backed API token store built on the Guren ORM. Pass the Drizzle
|
|
17
|
+
* table for your `api_tokens` schema; column property names must match the
|
|
18
|
+
* {@link ApiToken} fields. Configure the ORM before use.
|
|
19
|
+
* @example `new DatabaseApiTokenStore(apiTokens)`
|
|
42
20
|
*/
|
|
43
21
|
declare class DatabaseApiTokenStore implements ApiTokenStore {
|
|
44
22
|
private readonly model;
|
|
@@ -51,60 +29,30 @@ declare class DatabaseApiTokenStore implements ApiTokenStore {
|
|
|
51
29
|
deleteForUser(userId: string | number): Promise<void>;
|
|
52
30
|
updateLastUsed(id: string, timestamp: Date): Promise<void>;
|
|
53
31
|
/**
|
|
54
|
-
* Delete tokens whose expiration
|
|
55
|
-
*
|
|
56
|
-
* job to keep the table small.
|
|
32
|
+
* Delete tokens whose expiration has passed. `verifyApiToken` already rejects
|
|
33
|
+
* them; this only keeps the table small.
|
|
57
34
|
*/
|
|
58
35
|
deleteExpired(now?: Date): Promise<void>;
|
|
59
36
|
private deserialize;
|
|
60
37
|
}
|
|
61
38
|
//#endregion
|
|
62
39
|
//#region src/session-store.d.ts
|
|
63
|
-
/**
|
|
64
|
-
* Options for DatabaseSessionStore.
|
|
65
|
-
*/
|
|
66
40
|
interface DatabaseSessionStoreOptions {
|
|
67
41
|
/**
|
|
68
|
-
* How the `data` column stores the serialized session
|
|
69
|
-
*
|
|
70
|
-
*
|
|
71
|
-
*
|
|
72
|
-
* - `'text'` serializes to a JSON string for plain text columns.
|
|
73
|
-
*
|
|
74
|
-
* Reads always accept both representations.
|
|
42
|
+
* How the `data` column stores the serialized session: `'json'` (default)
|
|
43
|
+
* passes the object through for a JSON-capable column (pg `jsonb`/`json`,
|
|
44
|
+
* sqlite `text(..., { mode: 'json' })`); `'text'` serializes to a JSON string.
|
|
45
|
+
* Reads accept both.
|
|
75
46
|
* @default 'json'
|
|
76
47
|
*/
|
|
77
48
|
dataMode?: 'json' | 'text';
|
|
78
49
|
}
|
|
79
50
|
/**
|
|
80
|
-
* Database-backed session store built on the Guren ORM
|
|
81
|
-
*
|
|
82
|
-
*
|
|
83
|
-
*
|
|
84
|
-
*
|
|
85
|
-
* Pass the Drizzle table for your `sessions` schema. Column property names
|
|
86
|
-
* must match `id` (text primary key), `data`, and `expiresAt`:
|
|
87
|
-
*
|
|
88
|
-
* ```ts
|
|
89
|
-
* export const sessions = sqliteTable('sessions', {
|
|
90
|
-
* id: text('id').primaryKey(),
|
|
91
|
-
* data: text('data', { mode: 'json' }).$type<Record<string, unknown>>().notNull(),
|
|
92
|
-
* expiresAt: integer('expires_at', { mode: 'timestamp_ms' }).notNull(),
|
|
93
|
-
* })
|
|
94
|
-
* ```
|
|
95
|
-
*
|
|
96
|
-
* Session values must be JSON-serializable: Dates come back as ISO strings,
|
|
97
|
-
* `undefined` properties are dropped, and `bigint` values fail to serialize —
|
|
98
|
-
* unlike `MemorySessionStore`, which keeps live references. Store primitives
|
|
99
|
-
* and plain objects/arrays in sessions.
|
|
100
|
-
*
|
|
101
|
-
* @example
|
|
102
|
-
* ```ts
|
|
103
|
-
* import { DatabaseSessionStore } from '@guren/core'
|
|
104
|
-
* import { sessions } from '@/db/schema'
|
|
105
|
-
*
|
|
106
|
-
* app.use(createSessionMiddleware({ store: new DatabaseSessionStore(sessions) }))
|
|
107
|
-
* ```
|
|
51
|
+
* Database-backed session store built on the Guren ORM, the serverless default
|
|
52
|
+
* (no Redis on Lambda, Vercel, or Workers; reads are strongly consistent). Column
|
|
53
|
+
* property names of the `sessions` table must be `id` (text primary key), `data`,
|
|
54
|
+
* and `expiresAt`. Values must be JSON-serializable, unlike `MemorySessionStore`:
|
|
55
|
+
* Dates return as ISO strings, `undefined` properties drop, `bigint` throws.
|
|
108
56
|
*/
|
|
109
57
|
declare class DatabaseSessionStore implements SessionStore {
|
|
110
58
|
private readonly model;
|
|
@@ -114,17 +62,14 @@ declare class DatabaseSessionStore implements SessionStore {
|
|
|
114
62
|
write(id: string, data: SessionData, ttlSeconds: number): Promise<void>;
|
|
115
63
|
destroy(id: string): Promise<void>;
|
|
116
64
|
/**
|
|
117
|
-
* Refresh an existing session's TTL with
|
|
118
|
-
*
|
|
119
|
-
*
|
|
120
|
-
* resurrected — matching the `SessionStore.touch` contract and the memory
|
|
121
|
-
* store's behavior.
|
|
65
|
+
* Refresh an existing session's TTL with one conditional UPDATE. Missing and
|
|
66
|
+
* already-expired rows are left untouched, never resurrected, per the
|
|
67
|
+
* `SessionStore.touch` contract.
|
|
122
68
|
*/
|
|
123
69
|
touch(id: string, ttlSeconds: number): Promise<void>;
|
|
124
70
|
/**
|
|
125
|
-
* Delete sessions whose expiration
|
|
126
|
-
*
|
|
127
|
-
* scheduled job to keep the table small.
|
|
71
|
+
* Delete sessions whose expiration has passed. `read` already treats them as
|
|
72
|
+
* missing; this only keeps the table small.
|
|
128
73
|
*/
|
|
129
74
|
deleteExpired(now?: Date): Promise<void>;
|
|
130
75
|
private deserialize;
|
|
@@ -133,102 +78,44 @@ declare class DatabaseSessionStore implements SessionStore {
|
|
|
133
78
|
//#endregion
|
|
134
79
|
//#region src/oauth-state-store.d.ts
|
|
135
80
|
/**
|
|
136
|
-
* Database-backed OAuth state store built on the Guren ORM
|
|
137
|
-
*
|
|
138
|
-
*
|
|
139
|
-
*
|
|
140
|
-
*
|
|
141
|
-
* never sees the state that was just written. Backing the store with the
|
|
142
|
-
* database makes state visible to whichever instance handles the callback.
|
|
143
|
-
*
|
|
144
|
-
* Pass the Drizzle table for your `oauth_states` schema. Column property
|
|
145
|
-
* names must match `stateHash` (text primary key), `provider`,
|
|
146
|
-
* `redirectTo`, `expiresAt`, and `binding`:
|
|
147
|
-
*
|
|
148
|
-
* ```ts
|
|
149
|
-
* export const oauthStates = sqliteTable('oauth_states', {
|
|
150
|
-
* stateHash: text('state_hash').primaryKey(),
|
|
151
|
-
* provider: text('provider').notNull(),
|
|
152
|
-
* redirectTo: text('redirect_to'),
|
|
153
|
-
* expiresAt: integer('expires_at', { mode: 'timestamp_ms' }).notNull(),
|
|
154
|
-
* binding: text('binding'),
|
|
155
|
-
* })
|
|
156
|
-
* ```
|
|
157
|
-
*
|
|
158
|
-
* `binding` is required for `authorize({ bindTo })` to survive the round trip
|
|
159
|
-
* to the provider. Without the column the store cannot persist it, and every
|
|
160
|
-
* bound state comes back unbound.
|
|
161
|
-
*
|
|
162
|
-
* @example
|
|
163
|
-
* ```ts
|
|
164
|
-
* import { createOAuthManager, DatabaseOAuthStateStore } from '@guren/core'
|
|
165
|
-
* import { oauthStates } from '@/db/schema'
|
|
166
|
-
*
|
|
167
|
-
* export const oauth = createOAuthManager({
|
|
168
|
-
* stateStore: new DatabaseOAuthStateStore(oauthStates),
|
|
169
|
-
* })
|
|
170
|
-
* ```
|
|
81
|
+
* Database-backed OAuth state store built on the Guren ORM, for serverless, where
|
|
82
|
+
* authorize and callback can land on different instances. Column property names
|
|
83
|
+
* of the `oauth_states` table must be `stateHash` (text primary key), `provider`,
|
|
84
|
+
* `redirectTo`, `expiresAt`, and `binding` (else `authorize({ bindTo })` states come back unbound).
|
|
85
|
+
* @example `new DatabaseOAuthStateStore(oauthStates)`
|
|
171
86
|
*/
|
|
172
87
|
declare class DatabaseOAuthStateStore implements OAuthStateStore {
|
|
173
88
|
private readonly model;
|
|
174
89
|
constructor(table: unknown);
|
|
175
90
|
store(stateHash: string, payload: OAuthStatePayload): Promise<void>;
|
|
176
91
|
find(stateHash: string): Promise<OAuthStatePayload | null>;
|
|
177
|
-
/**
|
|
178
|
-
* Fetch the row for `stateHash`, clearing it out and returning null if
|
|
179
|
-
* expired. Shared by `find` and `consume`, which otherwise diverge only
|
|
180
|
-
* in what they do with a live row.
|
|
181
|
-
*/
|
|
92
|
+
/** Fetch the row for `stateHash`, clearing it and returning null if expired. */
|
|
182
93
|
private fetchLive;
|
|
183
94
|
delete(stateHash: string): Promise<void>;
|
|
184
95
|
/**
|
|
185
|
-
* Atomically fetch and delete a state,
|
|
186
|
-
*
|
|
187
|
-
*
|
|
188
|
-
*
|
|
189
|
-
*
|
|
190
|
-
* (RETURNING) or an affected-row count. `DrizzleAdapter`, the framework's
|
|
191
|
-
* default and only shipped adapter, always does this: RETURNING drivers
|
|
192
|
-
* (Postgres, SQLite, D1) resolve to the deleted row or `undefined` only
|
|
193
|
-
* when zero rows matched; MySQL resolves to a result carrying
|
|
194
|
-
* `affectedRows` (verified by inspection, not a dedicated test).
|
|
195
|
-
*
|
|
196
|
-
* The `ORMAdapter.delete` contract also permits a bare `void` return.
|
|
197
|
-
* A custom adapter (via `Model.useAdapter()`) that returns `void`
|
|
198
|
-
* unconditionally — on both a successful delete and a no-op — gives
|
|
199
|
-
* `consume()` no way to tell which caller won: the value is identical for
|
|
200
|
-
* both, so no post-hoc check can attribute the deletion. Rather than
|
|
201
|
-
* silently rejecting every real login for such adapters,
|
|
202
|
-
* `deleteRemovedRow` treats an unrecognized non-null result as removed —
|
|
203
|
-
* this reopens the pre-consume find-then-delete race window (multiple
|
|
204
|
-
* concurrent callers can pass) for adapters that can't report a match,
|
|
205
|
-
* but does not break login. It is fail-closed (returns null / rejects)
|
|
206
|
-
* only for `null`/`undefined`, DrizzleAdapter's definitive "no rows
|
|
207
|
-
* matched" signal.
|
|
96
|
+
* Atomically fetch and delete a state, so exactly one concurrent caller for a
|
|
97
|
+
* hash receives the payload. Relies on `delete()` reporting a match
|
|
98
|
+
* (`DrizzleAdapter`: RETURNING row, or MySQL `affectedRows`). An adapter
|
|
99
|
+
* returning bare `void` reopens the find-then-delete race: `deleteRemovedRow`
|
|
100
|
+
* fails closed only on `null`/`undefined`, Drizzle's definitive "no rows matched".
|
|
208
101
|
*/
|
|
209
102
|
consume(stateHash: string): Promise<OAuthStatePayload | null>;
|
|
210
103
|
/**
|
|
211
|
-
* Delete
|
|
212
|
-
*
|
|
213
|
-
* the table small.
|
|
104
|
+
* Delete states whose expiration has passed. `find` already rejects them; this
|
|
105
|
+
* only keeps the table small.
|
|
214
106
|
*/
|
|
215
107
|
deleteExpired(now?: Date): Promise<void>;
|
|
216
108
|
}
|
|
217
109
|
//#endregion
|
|
218
110
|
//#region src/attachments/types.d.ts
|
|
219
111
|
/**
|
|
220
|
-
* Public types for the attachments layer (RFC 0013)
|
|
221
|
-
*
|
|
222
|
-
* One table, one service, one processor interface: attachments ride the ORM's
|
|
112
|
+
* Public types for the attachments layer (RFC 0013): attachments ride the ORM's
|
|
223
113
|
* polymorphic `attachable` morph convention, bytes live on a `StorageManager`
|
|
224
114
|
* disk, and image work happens behind {@link ImageProcessor}.
|
|
225
115
|
*/
|
|
226
116
|
/**
|
|
227
|
-
* A named image variant specification
|
|
228
|
-
* `
|
|
229
|
-
*
|
|
230
|
-
* `fit` is limited to what `Bun.Image` actually supports (`'fill'` and
|
|
231
|
-
* `'inside'`); `'cover'` is reserved for a future, non-breaking addition.
|
|
117
|
+
* A named image variant specification. `fit` is limited to what `Bun.Image`
|
|
118
|
+
* supports; `'cover'` is reserved for a future, non-breaking addition.
|
|
232
119
|
*/
|
|
233
120
|
interface VariantSpec {
|
|
234
121
|
width?: number;
|
|
@@ -244,17 +131,11 @@ interface VariantSpec {
|
|
|
244
131
|
quality?: number;
|
|
245
132
|
}
|
|
246
133
|
/**
|
|
247
|
-
* Per-variant status entry
|
|
248
|
-
*
|
|
249
|
-
*
|
|
250
|
-
*
|
|
251
|
-
*
|
|
252
|
-
*
|
|
253
|
-
* - `pending` — generation is queued (`attach(..., { queued: true })`)
|
|
254
|
-
* and a worker has not finished it yet
|
|
255
|
-
* - `ready` — the variant object exists at `path`
|
|
256
|
-
* - `failed` — generation was attempted and failed
|
|
257
|
-
* - `unavailable` — the runtime has no image processor
|
|
134
|
+
* Per-variant status entry in the row's `variants` JSON column. Every *declared*
|
|
135
|
+
* variant gets an entry at attach time, which lets `attachmentUrl()` tell "not
|
|
136
|
+
* yet generated" (fall back) from "never declared" (throw). `pending` is queued,
|
|
137
|
+
* `ready` means the object exists at `path`, `failed` was attempted,
|
|
138
|
+
* `unavailable` means the runtime has no processor.
|
|
258
139
|
*/
|
|
259
140
|
interface AttachmentVariantRecord {
|
|
260
141
|
status: 'pending' | 'ready' | 'failed' | 'unavailable';
|
|
@@ -266,9 +147,7 @@ interface AttachmentVariantRecord {
|
|
|
266
147
|
/** Encoded size in bytes. */
|
|
267
148
|
size?: number;
|
|
268
149
|
}
|
|
269
|
-
/**
|
|
270
|
-
* A row of the `attachments` table, as returned by the attachment statics.
|
|
271
|
-
*/
|
|
150
|
+
/** A row of the `attachments` table, as returned by the attachment statics. */
|
|
272
151
|
interface AttachmentRecord {
|
|
273
152
|
/** ULID — sortable, unguessable object-key prefix. */
|
|
274
153
|
id: string;
|
|
@@ -298,12 +177,9 @@ interface AttachmentRecord {
|
|
|
298
177
|
updatedAt: Date;
|
|
299
178
|
}
|
|
300
179
|
/**
|
|
301
|
-
* The resource-facing shape returned by `withAttachments()
|
|
302
|
-
*
|
|
303
|
-
*
|
|
304
|
-
* `variants` has an entry for every *declared* variant name; a variant that
|
|
305
|
-
* is not `ready` yet falls back to the original's URL, so pages keep
|
|
306
|
-
* rendering (the `placeholder` LQIP covers the perceived-latency gap).
|
|
180
|
+
* The resource-facing shape returned by `withAttachments()`. `variants` has an
|
|
181
|
+
* entry for every *declared* variant name; one that is not `ready` yet falls
|
|
182
|
+
* back to the original's URL, so pages keep rendering.
|
|
307
183
|
*/
|
|
308
184
|
interface AttachmentData {
|
|
309
185
|
id: string;
|
|
@@ -322,22 +198,17 @@ interface AttachmentData {
|
|
|
322
198
|
}>;
|
|
323
199
|
}
|
|
324
200
|
/**
|
|
325
|
-
* Image processing behind the attachments pipeline.
|
|
326
|
-
*
|
|
327
|
-
*
|
|
328
|
-
*
|
|
329
|
-
*
|
|
330
|
-
*
|
|
331
|
-
* Implementations signal an OS-level codec gap by throwing an error whose
|
|
332
|
-
* `code` is `'ERR_IMAGE_FORMAT_UNSUPPORTED'` — format support is a runtime
|
|
333
|
-
* property (OS codecs), never a static table, so that error code is the only
|
|
334
|
-
* authority the pipeline branches on.
|
|
201
|
+
* Image processing behind the attachments pipeline. The default wraps
|
|
202
|
+
* `Bun.Image`; other runtimes inject their own via
|
|
203
|
+
* `configureAttachments({ processor })`. An OS-level codec gap is signalled by
|
|
204
|
+
* throwing with `code === 'ERR_IMAGE_FORMAT_UNSUPPORTED'`; format support is a
|
|
205
|
+
* runtime property, so that code is the only thing the pipeline branches on.
|
|
335
206
|
*/
|
|
336
207
|
interface ImageProcessor {
|
|
337
208
|
/**
|
|
338
|
-
* Full decode: validates the bytes, enforces `maxPixels`, reports
|
|
339
|
-
*
|
|
340
|
-
*
|
|
209
|
+
* Full decode: validates the bytes, enforces `maxPixels`, reports dimensions.
|
|
210
|
+
* Header sniffing is *not* validation (truncated files pass it), so
|
|
211
|
+
* implementations must decode pixels before resolving.
|
|
341
212
|
*/
|
|
342
213
|
probe(input: Uint8Array, limits: {
|
|
343
214
|
maxPixels: number;
|
|
@@ -356,33 +227,24 @@ interface ImageProcessor {
|
|
|
356
227
|
}>;
|
|
357
228
|
}
|
|
358
229
|
/**
|
|
359
|
-
* What an attachment collection accepts as image input.
|
|
360
|
-
*
|
|
361
|
-
*
|
|
362
|
-
* `placeholder` stay `null` (a `draftPdf` collection)
|
|
363
|
-
* - `'allow'` — images are decoded and measured when recognized; anything
|
|
364
|
-
* else is stored as opaque bytes
|
|
365
|
-
* - `'require'`— input must be a decodable image; non-images are rejected
|
|
366
|
-
* with a 422 `ValidationException`
|
|
367
|
-
* - `'forbid'` — inputs that sniff as images are rejected with 422
|
|
230
|
+
* What an attachment collection accepts as image input. Unset means opaque
|
|
231
|
+
* bytes with no image pipeline; `'allow'` decodes recognized images and stores
|
|
232
|
+
* anything else opaquely; `'require'` and `'forbid'` reject with a 422.
|
|
368
233
|
*/
|
|
369
234
|
type ImagePolicy = 'forbid' | 'allow' | 'require';
|
|
370
235
|
/**
|
|
371
|
-
* The bytes-only attach input. Filesystem path strings are
|
|
372
|
-
*
|
|
373
|
-
*
|
|
374
|
-
* so the pipeline never exposes the shape at all.
|
|
236
|
+
* The bytes-only attach input. Filesystem path strings are never accepted:
|
|
237
|
+
* `Bun.Image`'s path form is an arbitrary-file-read primitive once a
|
|
238
|
+
* user-influenced string reaches it.
|
|
375
239
|
*/
|
|
376
240
|
type AttachmentSource = File | Blob | Uint8Array;
|
|
377
241
|
//#endregion
|
|
378
242
|
//#region src/attachments/declaration.d.ts
|
|
379
243
|
/**
|
|
380
|
-
* How HEIC/HEIF input is handled.
|
|
381
|
-
* decoding depends on OS codecs — it works on macOS dev machines and fails
|
|
382
|
-
*
|
|
383
|
-
*
|
|
384
|
-
* JPEG and still answers 415 when the runtime cannot decode HEIC
|
|
385
|
-
* (`ERR_IMAGE_FORMAT_UNSUPPORTED`).
|
|
244
|
+
* How HEIC/HEIF input is handled. Defaults to `'reject'` (415) because HEIC
|
|
245
|
+
* decoding depends on OS codecs — it works on macOS dev machines and fails on
|
|
246
|
+
* Linux production. `'convert'` opts into decode-and-convert to JPEG, still
|
|
247
|
+
* answering 415 when the runtime cannot decode HEIC.
|
|
386
248
|
*/
|
|
387
249
|
type HeicPolicy = 'reject' | 'convert';
|
|
388
250
|
interface AttachedCollectionOptions<V extends string = never> {
|
|
@@ -399,10 +261,9 @@ interface AttachedCollectionOptions<V extends string = never> {
|
|
|
399
261
|
variants?: Record<V, VariantSpec>;
|
|
400
262
|
}
|
|
401
263
|
/**
|
|
402
|
-
* One collection's declaration as stored on the model's
|
|
403
|
-
*
|
|
404
|
-
*
|
|
405
|
-
* declared variant names into the mixin's compile-time checks.
|
|
264
|
+
* One collection's declaration as stored on the model's `static attachments`.
|
|
265
|
+
* The generics carry the collection kind and the declared variant names into
|
|
266
|
+
* the mixin's compile-time checks.
|
|
406
267
|
*/
|
|
407
268
|
interface AttachmentCollectionSpec<TKind extends 'one' | 'many' = 'one' | 'many', V extends string = string> {
|
|
408
269
|
kind: TKind;
|
|
@@ -416,26 +277,11 @@ interface AttachmentCollectionSpec<TKind extends 'one' | 'many' = 'one' | 'many'
|
|
|
416
277
|
type AttachmentsDeclaration = Record<string, AttachmentCollectionSpec<'one' | 'many', string>>;
|
|
417
278
|
/**
|
|
418
279
|
* Declare a single-attachment collection (`attach` replaces the previous
|
|
419
|
-
* attachment, purging its row and objects).
|
|
420
|
-
*
|
|
421
|
-
* @example
|
|
422
|
-
* export class Post extends Attachable(defineModel(posts), {
|
|
423
|
-
* cover: hasOneAttached({
|
|
424
|
-
* image: 'require',
|
|
425
|
-
* variants: { thumb: { width: 320 }, og: { width: 1200 } },
|
|
426
|
-
* }),
|
|
427
|
-
* draftPdf: hasOneAttached(), // opaque bytes; width/height/placeholder null
|
|
428
|
-
* }) {}
|
|
280
|
+
* attachment, purging its row and objects). Called with no options the bytes
|
|
281
|
+
* stay opaque: width/height/placeholder are null.
|
|
429
282
|
*/
|
|
430
283
|
declare function hasOneAttached<const V extends string = never>(options?: AttachedCollectionOptions<V>): AttachmentCollectionSpec<'one', V>;
|
|
431
|
-
/**
|
|
432
|
-
* Declare a multi-attachment collection (`attach` appends).
|
|
433
|
-
*
|
|
434
|
-
* @example
|
|
435
|
-
* export class Post extends Attachable(defineModel(posts), {
|
|
436
|
-
* images: hasManyAttached({ image: 'require' }),
|
|
437
|
-
* }) {}
|
|
438
|
-
*/
|
|
284
|
+
/** Declare a multi-attachment collection (`attach` appends). */
|
|
439
285
|
declare function hasManyAttached<const V extends string = never>(options?: AttachedCollectionOptions<V>): AttachmentCollectionSpec<'many', V>;
|
|
440
286
|
//#endregion
|
|
441
287
|
//#region src/attachments/engine.d.ts
|
|
@@ -445,23 +291,19 @@ interface AttachOptions {
|
|
|
445
291
|
/** Disk to store on, overriding the configured default. */
|
|
446
292
|
disk?: string;
|
|
447
293
|
/**
|
|
448
|
-
* Defer the full decode and variant generation to the queue: the request
|
|
449
|
-
*
|
|
450
|
-
*
|
|
451
|
-
*
|
|
452
|
-
* URLs fall back to the original. Requires a queue — either
|
|
453
|
-
* `configureAttachments({ queue })` or an already-booted QueueManager.
|
|
294
|
+
* Defer the full decode and variant generation to the queue: the request path
|
|
295
|
+
* runs only the synchronous gates, stores the original, seeds declared
|
|
296
|
+
* variants as `pending`, and dispatches `GenerateVariantsJob`. Variant URLs
|
|
297
|
+
* fall back to the original until the worker runs. Requires a queue.
|
|
454
298
|
*/
|
|
455
299
|
queued?: boolean;
|
|
456
300
|
}
|
|
457
301
|
interface ConfigureAttachmentsOptions {
|
|
458
302
|
/**
|
|
459
|
-
* The app's Drizzle `attachments` table
|
|
460
|
-
*
|
|
461
|
-
*
|
|
462
|
-
* `
|
|
463
|
-
* `contentType`, `size`, `width`, `height`, `variants` (JSON-capable),
|
|
464
|
-
* `placeholder`, `createdAt`, `updatedAt`.
|
|
303
|
+
* The app's Drizzle `attachments` table. Column property names must match the
|
|
304
|
+
* documented contract: `id`, `attachableType`, `attachableId`, `collection`,
|
|
305
|
+
* `disk`, `path`, `name`, `contentType`, `size`, `width`, `height`,
|
|
306
|
+
* `variants` (JSON-capable), `placeholder`, `createdAt`, `updatedAt`.
|
|
465
307
|
*/
|
|
466
308
|
table: unknown;
|
|
467
309
|
/** The app's StorageManager, resolved lazily (e.g. `() => container.make('storage')`). */
|
|
@@ -469,27 +311,21 @@ interface ConfigureAttachmentsOptions {
|
|
|
469
311
|
/** Default disk name for new attachments. */
|
|
470
312
|
disk: string;
|
|
471
313
|
/**
|
|
472
|
-
* Per-disk visibility
|
|
473
|
-
*
|
|
474
|
-
*
|
|
475
|
-
* when `delivery` is configured, else via `disk.temporaryUrl()`. Per
|
|
476
|
-
* disk, not per attachment, because at least one driver (R2) has no
|
|
477
|
-
* per-object visibility. Undeclared disks default to `'public'`.
|
|
314
|
+
* Per-disk visibility, and with the object form how a private disk's bytes are
|
|
315
|
+
* served (RFC 0015 §3). Per disk, not per attachment, because at least one
|
|
316
|
+
* driver (R2) has no per-object visibility. Undeclared disks are `'public'`.
|
|
478
317
|
*/
|
|
479
318
|
disks?: Record<string, DiskDeliveryConfig>;
|
|
480
319
|
/**
|
|
481
320
|
* Signed delivery route configuration (RFC 0015). Presence switches
|
|
482
|
-
* private-disk URLs from `disk.temporaryUrl()` to signed route URLs; the
|
|
483
|
-
*
|
|
484
|
-
* app's route registrar. Without this option nothing changes — v1
|
|
485
|
-
* behaviour and its documented limitations stand.
|
|
321
|
+
* private-disk URLs from `disk.temporaryUrl()` to signed route URLs; the route
|
|
322
|
+
* itself is mounted by `registerAttachmentRoutes(router)`.
|
|
486
323
|
*/
|
|
487
324
|
delivery?: DeliveryOptions;
|
|
488
325
|
/**
|
|
489
|
-
* Decode cap in pixels (decompression-bomb defense)
|
|
490
|
-
* decoded dimensions above
|
|
491
|
-
*
|
|
492
|
-
* raise it deliberately and should isolate their image workers.
|
|
326
|
+
* Decode cap in pixels (decompression-bomb defense); header-declared and
|
|
327
|
+
* decoded dimensions above it are rejected before a pixel buffer exists.
|
|
328
|
+
* There is deliberately no "unlimited" setting.
|
|
493
329
|
* @default 52_000_000
|
|
494
330
|
*/
|
|
495
331
|
maxPixels?: number;
|
|
@@ -500,23 +336,17 @@ interface ConfigureAttachmentsOptions {
|
|
|
500
336
|
*/
|
|
501
337
|
maxImageBytes?: number;
|
|
502
338
|
/**
|
|
503
|
-
*
|
|
504
|
-
*
|
|
505
|
-
*
|
|
506
|
-
* gates) or your own implementation (e.g. sharp-backed) on other runtimes.
|
|
339
|
+
* Defaults to the Bun-native processor when the runtime has `Bun.Image`. Pass
|
|
340
|
+
* `null` to force the processor-less path (variants `unavailable`, validation
|
|
341
|
+
* stops at the header gates), or your own implementation.
|
|
507
342
|
*/
|
|
508
343
|
processor?: ImageProcessor | null;
|
|
509
344
|
/**
|
|
510
|
-
* The app's QueueManager, resolved lazily (
|
|
511
|
-
*
|
|
512
|
-
* the
|
|
513
|
-
*
|
|
514
|
-
*
|
|
515
|
-
* pass the same manager the rest of the app dispatches through — a
|
|
516
|
-
* second manager here would redirect every later `Job.dispatch()` in the
|
|
517
|
-
* process. Without this option, `queued: true` falls back to the
|
|
518
|
-
* globally configured queue driver and throws a clear error when there
|
|
519
|
-
* is none.
|
|
345
|
+
* The app's QueueManager, resolved lazily; enables `attach(..., { queued })`.
|
|
346
|
+
* Materializing its default driver installs that driver process-wide, so pass
|
|
347
|
+
* the same manager the rest of the app dispatches through — a second one would
|
|
348
|
+
* redirect every later `Job.dispatch()`. Without this option, `queued: true`
|
|
349
|
+
* falls back to the globally configured driver.
|
|
520
350
|
*/
|
|
521
351
|
queue?: () => unknown;
|
|
522
352
|
/**
|
|
@@ -527,10 +357,9 @@ interface ConfigureAttachmentsOptions {
|
|
|
527
357
|
urlExpiresIn?: number;
|
|
528
358
|
}
|
|
529
359
|
/**
|
|
530
|
-
* What `GenerateVariantsJob` needs to finish a deferred attach.
|
|
531
|
-
*
|
|
532
|
-
*
|
|
533
|
-
* declaration edits and the worker needs no model registry to resolve them.
|
|
360
|
+
* What `GenerateVariantsJob` needs to finish a deferred attach. Specs are
|
|
361
|
+
* snapshotted at dispatch time, so an in-flight job survives later declaration
|
|
362
|
+
* edits and the worker needs no model registry.
|
|
534
363
|
*/
|
|
535
364
|
interface GenerateVariantsPayload {
|
|
536
365
|
attachmentId: string;
|
|
@@ -539,15 +368,11 @@ interface GenerateVariantsPayload {
|
|
|
539
368
|
variants?: Record<string, VariantSpec>;
|
|
540
369
|
}
|
|
541
370
|
/**
|
|
542
|
-
* How a private disk's bytes are served behind the signed route
|
|
543
|
-
*
|
|
544
|
-
*
|
|
545
|
-
*
|
|
546
|
-
*
|
|
547
|
-
* probe would misclassify exactly the disk that must not redirect.
|
|
548
|
-
* - `'redirect'` / `'proxy'`: force one behaviour.
|
|
549
|
-
* - `'direct'`: bypass the route entirely — v1's raw `temporaryUrl()`
|
|
550
|
-
* URLs, for disks that measured the extra hop and want it gone.
|
|
371
|
+
* How a private disk's bytes are served behind the signed route (RFC 0015 §3).
|
|
372
|
+
* `'auto'` redirects only on a driver's *declared* `capabilities.presignedGet`,
|
|
373
|
+
* never a probe: `LocalDriver.temporaryUrl()` succeeds with a plain public URL,
|
|
374
|
+
* so probing would misclassify exactly the disk that must not redirect.
|
|
375
|
+
* `'direct'` bypasses the route entirely for v1's raw `temporaryUrl()` URLs.
|
|
551
376
|
*/
|
|
552
377
|
type DeliveryServeMode = 'auto' | 'redirect' | 'proxy' | 'direct';
|
|
553
378
|
type DiskDeliveryConfig = 'public' | 'private' | {
|
|
@@ -556,8 +381,7 @@ type DiskDeliveryConfig = 'public' | 'private' | {
|
|
|
556
381
|
};
|
|
557
382
|
/**
|
|
558
383
|
* Per-URL options for `attachmentUrl()`. `disposition` accepts only
|
|
559
|
-
* `'attachment'`:
|
|
560
|
-
* types, and the route's allowlist can never be forced to inline — a
|
|
384
|
+
* `'attachment'`: the route's allowlist can never be forced to inline, so a
|
|
561
385
|
* signed `inline` value would change the URL while doing nothing.
|
|
562
386
|
*/
|
|
563
387
|
interface AttachmentUrlOptions {
|
|
@@ -571,13 +395,21 @@ interface DeliveryOptions {
|
|
|
571
395
|
*/
|
|
572
396
|
prefix?: string;
|
|
573
397
|
/**
|
|
574
|
-
*
|
|
575
|
-
*
|
|
576
|
-
* reserved for the framework.
|
|
398
|
+
* `Router.name()` silently overwrites duplicates, so the default is reserved
|
|
399
|
+
* for the framework.
|
|
577
400
|
* @default 'attachments.show'
|
|
578
401
|
*/
|
|
579
402
|
routeName?: string;
|
|
580
403
|
}
|
|
404
|
+
/**
|
|
405
|
+
* The single storage key prefix every attachment object lives under:
|
|
406
|
+
* `attachments/<id>/<name>` originals, `attachments/<id>/variants/…`
|
|
407
|
+
* derivatives, `attachments/` the prune sweep's listing. Exported because
|
|
408
|
+
* `guren check` names `<disk root>/attachments` from another package; a restated
|
|
409
|
+
* copy there would stop matching when this moves and report an exposed app safe.
|
|
410
|
+
*/
|
|
411
|
+
declare const ATTACHMENT_OBJECT_PREFIX = "attachments";
|
|
412
|
+
declare const DEFAULT_DELIVERY_ROUTE_NAME = "attachments.show";
|
|
581
413
|
interface PruneOptions {
|
|
582
414
|
/** Also delete `attachments/` storage prefixes that no row references. */
|
|
583
415
|
objects?: boolean;
|
|
@@ -587,17 +419,16 @@ interface PruneOptions {
|
|
|
587
419
|
interface PruneReport {
|
|
588
420
|
/** Rows examined. */
|
|
589
421
|
scannedRows: number;
|
|
590
|
-
/** Rows whose owning record
|
|
422
|
+
/** Rows whose owning record is gone (deleted unless dry-run). */
|
|
591
423
|
orphanRows: Array<{
|
|
592
424
|
id: string;
|
|
593
425
|
attachableType: string;
|
|
594
426
|
attachableId: string;
|
|
595
427
|
}>;
|
|
596
428
|
/**
|
|
597
|
-
* Morph types that could not be verified and were left untouched
|
|
598
|
-
*
|
|
599
|
-
*
|
|
600
|
-
* outage into a mass deletion.
|
|
429
|
+
* Morph types that could not be verified and were left untouched. A type that
|
|
430
|
+
* cannot be checked is never treated as absent: that turns an outage into a
|
|
431
|
+
* mass deletion.
|
|
601
432
|
*/
|
|
602
433
|
skippedTypes: Array<{
|
|
603
434
|
type: string;
|
|
@@ -619,11 +450,9 @@ interface PruneReport {
|
|
|
619
450
|
/** A record id accepted by the attachment statics (int and uuid/text PKs). */
|
|
620
451
|
type AttachableRecordId = string | number;
|
|
621
452
|
/**
|
|
622
|
-
*
|
|
623
|
-
*
|
|
624
|
-
*
|
|
625
|
-
* make TypeScript infer their variant-name parameter as `string` instead of
|
|
626
|
-
* the declared keys — silently disabling every variant-name check.
|
|
453
|
+
* Deliberately minimal: a tighter bound would become the contextual type of the
|
|
454
|
+
* `hasOneAttached()` / `hasManyAttached()` calls and widen their variant-name
|
|
455
|
+
* parameter to `string`, disabling every variant-name check.
|
|
627
456
|
*/
|
|
628
457
|
type DeclarationShape = Record<string, {
|
|
629
458
|
kind: 'one' | 'many';
|
|
@@ -641,27 +470,24 @@ type DetachRest<TSpec> = TSpec extends {
|
|
|
641
470
|
kind: 'many';
|
|
642
471
|
} ? [attachmentId?: string] : [];
|
|
643
472
|
/**
|
|
644
|
-
* Rejects declaration keys that shadow a real column of the base model's
|
|
645
|
-
*
|
|
646
|
-
*
|
|
647
|
-
* exempt — there is nothing concrete to check against.
|
|
473
|
+
* Rejects declaration keys that shadow a real column of the base model's table
|
|
474
|
+
* (the attachment would hide it at `withAttachments` time). A base whose record
|
|
475
|
+
* type is untyped is exempt.
|
|
648
476
|
*/
|
|
649
477
|
type CollisionFreeDeclaration<TBase extends typeof Model$1, TDecl> = string extends keyof TBase['recordType'] & string ? unknown : { [K in Extract<keyof TDecl, keyof TBase['recordType']>]: never; };
|
|
650
478
|
/**
|
|
651
|
-
* The statics the `Attachable` mixin adds
|
|
652
|
-
*
|
|
653
|
-
*
|
|
654
|
-
* names are compile errors.
|
|
479
|
+
* The statics the `Attachable` mixin adds, all delegating to the engine wired by
|
|
480
|
+
* `configureAttachments()`. Every collection argument is `keyof` the
|
|
481
|
+
* declaration, so typos and undeclared variant names are compile errors.
|
|
655
482
|
*/
|
|
656
483
|
interface AttachableStatic<TBase extends typeof Model$1, TDecl extends DeclarationShape> {
|
|
657
484
|
/** The declaration, statically readable (this is what `guren check` and codegen read). */
|
|
658
485
|
readonly attachments: TDecl;
|
|
659
486
|
/**
|
|
660
|
-
* Store bytes as an attachment on `collection`. `source` is bytes only
|
|
661
|
-
*
|
|
662
|
-
* `
|
|
663
|
-
*
|
|
664
|
-
* variant specs come from the declaration, not the call site.
|
|
487
|
+
* Store bytes as an attachment on `collection`. `source` is bytes only — path
|
|
488
|
+
* strings are never accepted. `hasOne` replaces the previous attachment (row
|
|
489
|
+
* and objects purged); `hasMany` appends. Validation and variant specs come
|
|
490
|
+
* from the declaration, not the call site.
|
|
665
491
|
*/
|
|
666
492
|
attach<K extends keyof TDecl & string>(recordId: AttachableRecordId, collection: K, source: AttachmentSource, options?: AttachOptions): Promise<AttachmentRecord>;
|
|
667
493
|
/**
|
|
@@ -679,146 +505,76 @@ interface AttachableStatic<TBase extends typeof Model$1, TDecl extends Declarati
|
|
|
679
505
|
id: string | number;
|
|
680
506
|
}, K extends keyof TDecl & string>(records: readonly TRecord[], names: readonly K[]): Promise<Array<TRecord & AttachedProps<TDecl, K>>>;
|
|
681
507
|
/**
|
|
682
|
-
* URL for a collection's attachment: `disk.url()` on public disks; on
|
|
683
|
-
*
|
|
684
|
-
*
|
|
685
|
-
*
|
|
686
|
-
*
|
|
687
|
-
* `urlExpiresIn` for this one URL. Returns `null` when nothing is
|
|
688
|
-
* attached.
|
|
508
|
+
* URL for a collection's attachment: `disk.url()` on public disks; on private
|
|
509
|
+
* ones a signed delivery-route URL when `delivery` is configured (RFC 0015),
|
|
510
|
+
* else `disk.temporaryUrl()`. A declared-but-not-ready variant falls back to
|
|
511
|
+
* the original; an undeclared variant name throws. `expiresIn` is in ms.
|
|
512
|
+
* Returns `null` when nothing is attached.
|
|
689
513
|
*/
|
|
690
514
|
attachmentUrl<K extends keyof TDecl & string>(record: PlainObject$1 | AttachableRecordId, collection: K, options?: AttachmentUrlOptions & {
|
|
691
515
|
variant?: VariantNamesOf<TDecl[NoInfer<K>]>;
|
|
692
516
|
}): Promise<string | null>;
|
|
693
517
|
/**
|
|
694
|
-
* Remove every attachment of a record
|
|
695
|
-
*
|
|
696
|
-
* reliable purge trigger, so the contract is explicit-plus-sweep.
|
|
518
|
+
* Remove every attachment of a record, objects first, rows after. Call it from
|
|
519
|
+
* destroy actions: model delete hooks are not a reliable purge trigger.
|
|
697
520
|
*/
|
|
698
521
|
purgeAttachments(recordId: AttachableRecordId): Promise<void>;
|
|
699
522
|
}
|
|
700
523
|
/**
|
|
701
|
-
* Mixin
|
|
702
|
-
*
|
|
703
|
-
* statically
|
|
704
|
-
* rely on for the model's other surfaces), and its collection names, kinds,
|
|
705
|
-
* and variant names are inferred as compile-time facts.
|
|
706
|
-
*
|
|
707
|
-
* Composes with other mixins the way `SoftDeletes` does.
|
|
708
|
-
*
|
|
524
|
+
* Mixin declaring attachment collections on a model (RFC 0013). The declaration
|
|
525
|
+
* sits in the heritage clause so `guren check` and `guren context` read it
|
|
526
|
+
* statically while collection names, kinds, and variant names are inferred types.
|
|
709
527
|
* @example
|
|
710
|
-
*
|
|
711
|
-
*
|
|
712
|
-
* export class Post extends Attachable(defineModel(posts), {
|
|
713
|
-
* cover: hasOneAttached({
|
|
714
|
-
* image: 'require',
|
|
715
|
-
* variants: { thumb: { width: 320 }, og: { width: 1200 } },
|
|
716
|
-
* }),
|
|
717
|
-
* images: hasManyAttached({ image: 'require' }),
|
|
718
|
-
* draftPdf: hasOneAttached(),
|
|
719
|
-
* }) {}
|
|
720
|
-
*
|
|
721
|
-
* // Later, anywhere:
|
|
722
|
-
* await Post.attach(post.id, 'cover', await this.file('cover'))
|
|
723
|
-
* const [withCover] = await Post.withAttachments([post], ['cover'])
|
|
724
|
-
* const url = await Post.attachmentUrl(post, 'cover', { variant: 'thumb' })
|
|
528
|
+
* class Post extends Attachable(defineModel(posts), { cover: hasOneAttached({ image: 'require' }), images: hasManyAttached() }) {}
|
|
725
529
|
*/
|
|
726
530
|
declare function Attachable<TBase extends typeof Model$1, const TDecl extends DeclarationShape>(Base: TBase, declaration: TDecl & CollisionFreeDeclaration<TBase, TDecl>): TBase & AttachableStatic<TBase, TDecl>;
|
|
727
531
|
//#endregion
|
|
728
532
|
//#region src/attachments/configure.d.ts
|
|
729
533
|
interface ConfiguredAttachments {
|
|
730
534
|
/**
|
|
731
|
-
* A
|
|
732
|
-
* `morphTo('attachable', 'attachable')` pre-declared
|
|
733
|
-
*
|
|
734
|
-
*
|
|
735
|
-
* exports no bare `Attachment` (it would collide with the mail /
|
|
736
|
-
* notification / Slack attachment vocabulary).
|
|
535
|
+
* A model bound to the app's `attachments` table with
|
|
536
|
+
* `morphTo('attachable', 'attachable')` pre-declared. The framework exports no
|
|
537
|
+
* bare `Attachment`: it would collide with the mail / notification / Slack
|
|
538
|
+
* attachment vocabulary.
|
|
737
539
|
*/
|
|
738
540
|
Attachment: typeof Model$1;
|
|
739
541
|
}
|
|
740
542
|
/**
|
|
741
|
-
* Wire the attachments layer, once per app
|
|
742
|
-
*
|
|
743
|
-
*
|
|
744
|
-
* lazily and throw a clear error when it was never called.
|
|
745
|
-
*
|
|
543
|
+
* Wire the attachments layer, once per app: the app owns the table, the
|
|
544
|
+
* framework returns the model. `Attachable` statics resolve this lazily and
|
|
545
|
+
* throw a clear error when it was never called.
|
|
746
546
|
* @example
|
|
747
|
-
*
|
|
748
|
-
* // config/attachments.ts
|
|
749
|
-
* import { configureAttachments } from '@guren/core'
|
|
750
|
-
* import { attachments } from '@/db/schema'
|
|
751
|
-
*
|
|
752
|
-
* export const { Attachment } = configureAttachments({
|
|
753
|
-
* table: attachments,
|
|
754
|
-
* storage: () => container.make('storage'),
|
|
755
|
-
* disk: 'media',
|
|
756
|
-
* })
|
|
757
|
-
* ```
|
|
547
|
+
* export const { Attachment } = configureAttachments({ table: attachments, storage: () => container.make('storage'), disk: 'media' })
|
|
758
548
|
*/
|
|
759
549
|
declare function configureAttachments(options: ConfigureAttachmentsOptions): ConfiguredAttachments;
|
|
760
550
|
//#endregion
|
|
761
551
|
//#region src/attachments/delivery.d.ts
|
|
762
552
|
/**
|
|
763
|
-
* The signed attachment delivery route's controller (RFC 0015 §1).
|
|
764
|
-
*
|
|
765
|
-
*
|
|
766
|
-
*
|
|
767
|
-
*
|
|
768
|
-
* Raw on purpose, too: every semantic parameter must be re-read from the
|
|
769
|
-
* same `URLSearchParams` parse the signature canonicalizes with. Hono's
|
|
770
|
-
* query decoder disagrees with `URLSearchParams` on malformed
|
|
771
|
-
* percent-encoding, and a parser mismatch there is a signed-URL rewrite
|
|
772
|
-
* primitive.
|
|
553
|
+
* The signed attachment delivery route's controller (RFC 0015 §1). It hands the
|
|
554
|
+
* *raw* `Request` to the engine so every semantic parameter is re-read from the
|
|
555
|
+
* same `URLSearchParams` parse the signature canonicalizes with: Hono's query
|
|
556
|
+
* decoder disagrees with `URLSearchParams` on malformed percent-encoding, and
|
|
557
|
+
* that mismatch is a signed-URL rewrite primitive.
|
|
773
558
|
*/
|
|
774
559
|
declare class AttachmentDeliveryController extends Controller {
|
|
775
560
|
show(): Promise<Response>;
|
|
776
561
|
}
|
|
777
562
|
/**
|
|
778
|
-
* Mount the signed delivery route (RFC 0015 §6)
|
|
779
|
-
* route registrar:
|
|
780
|
-
*
|
|
781
|
-
* ```ts
|
|
782
|
-
* // routes/web.ts
|
|
783
|
-
* import { registerAttachmentRoutes } from '@guren/core'
|
|
784
|
-
*
|
|
785
|
-
* export function registerWebRoutes(router: Router): void {
|
|
786
|
-
* registerAttachmentRoutes(router)
|
|
787
|
-
* // …app routes…
|
|
788
|
-
* }
|
|
789
|
-
* ```
|
|
563
|
+
* Mount the signed delivery route (RFC 0015 §6) from the app's route registrar.
|
|
790
564
|
*
|
|
791
|
-
*
|
|
792
|
-
*
|
|
793
|
-
*
|
|
794
|
-
* booted, so a config-dependent throw here would break every inspection
|
|
795
|
-
* tool. The controller resolves the engine per request instead; at runtime
|
|
796
|
-
* providers register before routes mount, so the configured prefix and
|
|
797
|
-
* route name are picked up whenever they exist.
|
|
565
|
+
* Never throws and does not require `configureAttachments()` to have run: route
|
|
566
|
+
* tooling invokes registrars against a bare `Router` with no providers booted.
|
|
567
|
+
* The controller resolves the engine per request instead.
|
|
798
568
|
*/
|
|
799
569
|
declare function registerAttachmentRoutes(router: Router): void;
|
|
800
570
|
//#endregion
|
|
801
571
|
//#region src/attachments/prune-command.d.ts
|
|
802
572
|
/**
|
|
803
|
-
* Console sweeper for the attachments layer (RFC 0013 §8)
|
|
804
|
-
* `attachableType`/`attachableId` pair
|
|
805
|
-
*
|
|
806
|
-
*
|
|
807
|
-
*
|
|
808
|
-
* prefixes left behind by crashed or raced jobs.
|
|
809
|
-
*
|
|
810
|
-
* Register it in the app's console kernel:
|
|
811
|
-
*
|
|
812
|
-
* ```ts
|
|
813
|
-
* // src/console.ts
|
|
814
|
-
* import { AttachmentsPruneCommand } from '@guren/core'
|
|
815
|
-
* kernel.register(AttachmentsPruneCommand)
|
|
816
|
-
* ```
|
|
817
|
-
*
|
|
818
|
-
* Orphan rows are detected by resolving each `attachableType` through
|
|
819
|
-
* `Model.morphMap` and querying for the records — set
|
|
820
|
-
* `Model.morphMap = { Post, User, ... }` for every model that declares
|
|
821
|
-
* attachments, or their rows are reported as unverifiable and left alone.
|
|
573
|
+
* Console sweeper for the attachments layer (RFC 0013 §8): the polymorphic
|
|
574
|
+
* `attachableType`/`attachableId` pair carries no foreign key, so deletion is
|
|
575
|
+
* explicit (`purgeAttachments()`) plus this sweep. Register it in the console
|
|
576
|
+
* kernel. Orphans are found by resolving `attachableType` through `Model.morphMap`;
|
|
577
|
+
* a model missing there has its rows reported as unverifiable and left alone.
|
|
822
578
|
*/
|
|
823
579
|
declare class AttachmentsPruneCommand extends Command {
|
|
824
580
|
static signature: string;
|
|
@@ -828,29 +584,18 @@ declare class AttachmentsPruneCommand extends Command {
|
|
|
828
584
|
//#endregion
|
|
829
585
|
//#region src/attachments/generate-variants-job.d.ts
|
|
830
586
|
/**
|
|
831
|
-
* Queue job behind `attach(..., { queued: true })` (RFC 0013 Part 2):
|
|
832
|
-
*
|
|
833
|
-
* opted in, and generates the declared variants, flipping their `pending`
|
|
834
|
-
* status records to `ready`/`failed`.
|
|
587
|
+
* Queue job behind `attach(..., { queued: true })` (RFC 0013 Part 2): the
|
|
588
|
+
* deferred full decode, opted-in HEIC conversion, and the declared variants.
|
|
835
589
|
*
|
|
836
|
-
*
|
|
837
|
-
*
|
|
838
|
-
* work happens — point it at a runtime with an image processor (Bun with
|
|
839
|
-
* `Bun.Image`, or a custom `configureAttachments({ processor })`), or every
|
|
840
|
-
* variant settles as `unavailable`.
|
|
590
|
+
* The worker is where the image work happens — point it at a runtime with an
|
|
591
|
+
* image processor, or every variant settles as `unavailable`.
|
|
841
592
|
*/
|
|
842
593
|
declare class GenerateVariantsJob extends Job<GenerateVariantsPayload> {
|
|
843
|
-
/**
|
|
844
|
-
* Pinned wire name: queued messages must survive bundler identifier
|
|
845
|
-
* mangling and any future rename of this class.
|
|
846
|
-
*/
|
|
594
|
+
/** Pinned: queued messages must survive identifier mangling and renames. */
|
|
847
595
|
static jobName: string;
|
|
848
596
|
handle(payload: GenerateVariantsPayload): Promise<void>;
|
|
849
|
-
/**
|
|
850
|
-
* After the last retry, stop `pending` variants from looking in-flight
|
|
851
|
-
* forever — their URLs already fall back to the original either way.
|
|
852
|
-
*/
|
|
597
|
+
/** After the last retry, stop `pending` variants looking in-flight forever. */
|
|
853
598
|
failed(payload: GenerateVariantsPayload, _error: Error): Promise<void>;
|
|
854
599
|
}
|
|
855
600
|
//#endregion
|
|
856
|
-
export { type AccessorDefinitions, type AccessorFn, type AttachOptions, Attachable, type AttachableRecordId, type AttachableStatic, type AttachedCollectionOptions, type AttachmentCollectionSpec, type AttachmentData, AttachmentDeliveryController, type AttachmentRecord, type AttachmentSource, type AttachmentUrlOptions, type AttachmentVariantRecord, type AttachmentsDeclaration, AttachmentsPruneCommand, type AwsDataApiDatabase, type AwsDataApiDatabaseOptions, type AwsDataApiSeederContext, type BelongsToManyRecord, type BelongsToManyRelationResult, type BelongsToRecord, type BelongsToRelationResult, type BelongsToRequiredRecord, type CastType, type ConfigureAttachmentsOptions, type ConfiguredAttachments, type D1DatabaseHandle, type D1DatabaseOptions, DatabaseApiTokenStore, type DatabaseApiTokenStoreOptions, DatabaseOAuthStateStore, DatabaseSessionStore, type DatabaseSessionStoreOptions, type DeliveryOptions, type DeliveryServeMode, type DiskDeliveryConfig, DrizzleAdapter, type EagerLoadConstraint, type FindManyOptions, GenerateVariantsJob, type GenerateVariantsPayload, type GroupCondition, type HasManyRecord, type HasManyRelationResult, type HasManyThroughRecord, type HasManyThroughRelationResult, type HasOneRecord, type HasOneRelationResult, type HeicPolicy, type HookCallback, type HookName, type ImagePolicy, type ImageProcessor, type InferModelInsert, type InferModelRecord, MassAssignmentException, type MigrationRunSummary, type MigrationStatusEntry, Model, type ModelHooks, ModelNotFoundException, type ModelObserver, type ModelObserverConstructor, type ModelPaginationMeta, type ModelQueryOptions, type MorphManyRecord, type MorphManyRelationResult, type MorphToRecord, type MorphToRelationResult, type MutatorDefinitions, type MutatorFn, type MySqlDatabase, type MySqlDatabaseOptions, type MySqlSeederContext, type ORMAdapter, type ORMAdapterAdvanced, type OrderByClause, type OrderByInput, type OrderDefinition, type OrderDirection, type PaginateOptions, type PaginatedResult, type PlainObject, type PostgresDatabase, type PostgresDatabaseOptions, type PostgresSeederContext, type PruneOptions, type PruneReport, QueryBuilder, type QueryBuilderOptions, type ScopeFunction, type SeederContext, type SeederHandler, type SeederRunSummary, type SimpleCondition, SoftDeletes, type SoftDeletesStatic, type SqliteDatabase, type SqliteDatabaseOptions, type SqliteSeederContext, type TransactionHandle, type TransactionModelScope, type VariantSpec, type WhereClause, type WhereCondition, type WhereGroupCallback, type WhereOperator, type WithRelations, configureAttachments, createAwsDataApiDatabase, createD1Database, createMySqlDatabase, createPostgresDatabase, createSqliteDatabase, defineModel, defineSeeder, hasManyAttached, hasOneAttached, registerAttachmentRoutes, runSeeders };
|
|
601
|
+
export { ATTACHMENT_OBJECT_PREFIX, type AccessorDefinitions, type AccessorFn, type AttachOptions, Attachable, type AttachableRecordId, type AttachableStatic, type AttachedCollectionOptions, type AttachmentCollectionSpec, type AttachmentData, AttachmentDeliveryController, type AttachmentRecord, type AttachmentSource, type AttachmentUrlOptions, type AttachmentVariantRecord, type AttachmentsDeclaration, AttachmentsPruneCommand, type AwsDataApiDatabase, type AwsDataApiDatabaseOptions, type AwsDataApiSeederContext, type BelongsToManyRecord, type BelongsToManyRelationResult, type BelongsToRecord, type BelongsToRelationResult, type BelongsToRequiredRecord, type CastType, type ConfigureAttachmentsOptions, type ConfiguredAttachments, type D1DatabaseHandle, type D1DatabaseOptions, DEFAULT_DELIVERY_ROUTE_NAME, DatabaseApiTokenStore, type DatabaseApiTokenStoreOptions, DatabaseOAuthStateStore, DatabaseSessionStore, type DatabaseSessionStoreOptions, type DeliveryOptions, type DeliveryServeMode, type DiskDeliveryConfig, DrizzleAdapter, type EagerLoadConstraint, type FindManyOptions, GenerateVariantsJob, type GenerateVariantsPayload, type GroupCondition, type HasManyRecord, type HasManyRelationResult, type HasManyThroughRecord, type HasManyThroughRelationResult, type HasOneRecord, type HasOneRelationResult, type HeicPolicy, type HookCallback, type HookName, type ImagePolicy, type ImageProcessor, type InferModelInsert, type InferModelRecord, MassAssignmentException, type MigrationRunSummary, type MigrationStatusEntry, Model, type ModelHooks, ModelNotFoundException, type ModelObserver, type ModelObserverConstructor, type ModelPaginationMeta, type ModelQueryOptions, type MorphManyRecord, type MorphManyRelationResult, type MorphToRecord, type MorphToRelationResult, type MutatorDefinitions, type MutatorFn, type MySqlDatabase, type MySqlDatabaseOptions, type MySqlSeederContext, type ORMAdapter, type ORMAdapterAdvanced, type OrderByClause, type OrderByInput, type OrderDefinition, type OrderDirection, type PaginateOptions, type PaginatedResult, type PlainObject, type PostgresDatabase, type PostgresDatabaseOptions, type PostgresSeederContext, type PruneOptions, type PruneReport, QueryBuilder, type QueryBuilderOptions, type ScopeFunction, type SeederContext, type SeederHandler, type SeederRunSummary, type SimpleCondition, SoftDeletes, type SoftDeletesStatic, type SqliteDatabase, type SqliteDatabaseOptions, type SqliteSeederContext, type TransactionHandle, type TransactionModelScope, type VariantSpec, type WhereClause, type WhereCondition, type WhereGroupCallback, type WhereOperator, type WithRelations, configureAttachments, createAwsDataApiDatabase, createD1Database, createMySqlDatabase, createPostgresDatabase, createSqliteDatabase, defineModel, defineSeeder, hasManyAttached, hasOneAttached, registerAttachmentRoutes, runSeeders };
|