@guren/core 1.13.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/index.d.ts +168 -441
- package/dist/index.js +150 -401
- package/dist/internal/deploy-build.d.ts +101 -287
- package/dist/internal/deploy-build.js +127 -357
- package/package.json +4 -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,28 +395,18 @@ 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
|
}
|
|
581
404
|
/**
|
|
582
405
|
* The single storage key prefix every attachment object lives under:
|
|
583
|
-
* `attachments/<id>/<name>`
|
|
584
|
-
*
|
|
585
|
-
*
|
|
586
|
-
*
|
|
587
|
-
* Exported, and re-exported from `@guren/core`, because the layout is not
|
|
588
|
-
* private to this file. `guren check`'s attachments rules judge, from
|
|
589
|
-
* another package, whether uploaded bytes land somewhere the app serves
|
|
590
|
-
* statically — and the ones that reach the objects themselves have to name
|
|
591
|
-
* `<disk root>/attachments` to do it. A restated copy of the prefix over
|
|
592
|
-
* there does not fail loudly when this layout moves (a shard level, a
|
|
593
|
-
* rename): it stops matching, answers "not reachable", and reports an
|
|
594
|
-
* exposed app as safe. A build-failing security rule failing *open*, with
|
|
595
|
-
* nothing going red anywhere. Import this instead of restating it.
|
|
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.
|
|
596
410
|
*/
|
|
597
411
|
declare const ATTACHMENT_OBJECT_PREFIX = "attachments";
|
|
598
412
|
declare const DEFAULT_DELIVERY_ROUTE_NAME = "attachments.show";
|
|
@@ -605,17 +419,16 @@ interface PruneOptions {
|
|
|
605
419
|
interface PruneReport {
|
|
606
420
|
/** Rows examined. */
|
|
607
421
|
scannedRows: number;
|
|
608
|
-
/** Rows whose owning record
|
|
422
|
+
/** Rows whose owning record is gone (deleted unless dry-run). */
|
|
609
423
|
orphanRows: Array<{
|
|
610
424
|
id: string;
|
|
611
425
|
attachableType: string;
|
|
612
426
|
attachableId: string;
|
|
613
427
|
}>;
|
|
614
428
|
/**
|
|
615
|
-
* Morph types that could not be verified and were left untouched
|
|
616
|
-
*
|
|
617
|
-
*
|
|
618
|
-
* 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.
|
|
619
432
|
*/
|
|
620
433
|
skippedTypes: Array<{
|
|
621
434
|
type: string;
|
|
@@ -637,11 +450,9 @@ interface PruneReport {
|
|
|
637
450
|
/** A record id accepted by the attachment statics (int and uuid/text PKs). */
|
|
638
451
|
type AttachableRecordId = string | number;
|
|
639
452
|
/**
|
|
640
|
-
*
|
|
641
|
-
*
|
|
642
|
-
*
|
|
643
|
-
* make TypeScript infer their variant-name parameter as `string` instead of
|
|
644
|
-
* 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.
|
|
645
456
|
*/
|
|
646
457
|
type DeclarationShape = Record<string, {
|
|
647
458
|
kind: 'one' | 'many';
|
|
@@ -659,27 +470,24 @@ type DetachRest<TSpec> = TSpec extends {
|
|
|
659
470
|
kind: 'many';
|
|
660
471
|
} ? [attachmentId?: string] : [];
|
|
661
472
|
/**
|
|
662
|
-
* Rejects declaration keys that shadow a real column of the base model's
|
|
663
|
-
*
|
|
664
|
-
*
|
|
665
|
-
* 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.
|
|
666
476
|
*/
|
|
667
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; };
|
|
668
478
|
/**
|
|
669
|
-
* The statics the `Attachable` mixin adds
|
|
670
|
-
*
|
|
671
|
-
*
|
|
672
|
-
* 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.
|
|
673
482
|
*/
|
|
674
483
|
interface AttachableStatic<TBase extends typeof Model$1, TDecl extends DeclarationShape> {
|
|
675
484
|
/** The declaration, statically readable (this is what `guren check` and codegen read). */
|
|
676
485
|
readonly attachments: TDecl;
|
|
677
486
|
/**
|
|
678
|
-
* Store bytes as an attachment on `collection`. `source` is bytes only
|
|
679
|
-
*
|
|
680
|
-
* `
|
|
681
|
-
*
|
|
682
|
-
* 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.
|
|
683
491
|
*/
|
|
684
492
|
attach<K extends keyof TDecl & string>(recordId: AttachableRecordId, collection: K, source: AttachmentSource, options?: AttachOptions): Promise<AttachmentRecord>;
|
|
685
493
|
/**
|
|
@@ -697,146 +505,76 @@ interface AttachableStatic<TBase extends typeof Model$1, TDecl extends Declarati
|
|
|
697
505
|
id: string | number;
|
|
698
506
|
}, K extends keyof TDecl & string>(records: readonly TRecord[], names: readonly K[]): Promise<Array<TRecord & AttachedProps<TDecl, K>>>;
|
|
699
507
|
/**
|
|
700
|
-
* URL for a collection's attachment: `disk.url()` on public disks; on
|
|
701
|
-
*
|
|
702
|
-
*
|
|
703
|
-
*
|
|
704
|
-
*
|
|
705
|
-
* `urlExpiresIn` for this one URL. Returns `null` when nothing is
|
|
706
|
-
* 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.
|
|
707
513
|
*/
|
|
708
514
|
attachmentUrl<K extends keyof TDecl & string>(record: PlainObject$1 | AttachableRecordId, collection: K, options?: AttachmentUrlOptions & {
|
|
709
515
|
variant?: VariantNamesOf<TDecl[NoInfer<K>]>;
|
|
710
516
|
}): Promise<string | null>;
|
|
711
517
|
/**
|
|
712
|
-
* Remove every attachment of a record
|
|
713
|
-
*
|
|
714
|
-
* 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.
|
|
715
520
|
*/
|
|
716
521
|
purgeAttachments(recordId: AttachableRecordId): Promise<void>;
|
|
717
522
|
}
|
|
718
523
|
/**
|
|
719
|
-
* Mixin
|
|
720
|
-
*
|
|
721
|
-
* statically
|
|
722
|
-
* rely on for the model's other surfaces), and its collection names, kinds,
|
|
723
|
-
* and variant names are inferred as compile-time facts.
|
|
724
|
-
*
|
|
725
|
-
* Composes with other mixins the way `SoftDeletes` does.
|
|
726
|
-
*
|
|
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.
|
|
727
527
|
* @example
|
|
728
|
-
*
|
|
729
|
-
*
|
|
730
|
-
* export class Post extends Attachable(defineModel(posts), {
|
|
731
|
-
* cover: hasOneAttached({
|
|
732
|
-
* image: 'require',
|
|
733
|
-
* variants: { thumb: { width: 320 }, og: { width: 1200 } },
|
|
734
|
-
* }),
|
|
735
|
-
* images: hasManyAttached({ image: 'require' }),
|
|
736
|
-
* draftPdf: hasOneAttached(),
|
|
737
|
-
* }) {}
|
|
738
|
-
*
|
|
739
|
-
* // Later, anywhere:
|
|
740
|
-
* await Post.attach(post.id, 'cover', await this.file('cover'))
|
|
741
|
-
* const [withCover] = await Post.withAttachments([post], ['cover'])
|
|
742
|
-
* const url = await Post.attachmentUrl(post, 'cover', { variant: 'thumb' })
|
|
528
|
+
* class Post extends Attachable(defineModel(posts), { cover: hasOneAttached({ image: 'require' }), images: hasManyAttached() }) {}
|
|
743
529
|
*/
|
|
744
530
|
declare function Attachable<TBase extends typeof Model$1, const TDecl extends DeclarationShape>(Base: TBase, declaration: TDecl & CollisionFreeDeclaration<TBase, TDecl>): TBase & AttachableStatic<TBase, TDecl>;
|
|
745
531
|
//#endregion
|
|
746
532
|
//#region src/attachments/configure.d.ts
|
|
747
533
|
interface ConfiguredAttachments {
|
|
748
534
|
/**
|
|
749
|
-
* A
|
|
750
|
-
* `morphTo('attachable', 'attachable')` pre-declared
|
|
751
|
-
*
|
|
752
|
-
*
|
|
753
|
-
* exports no bare `Attachment` (it would collide with the mail /
|
|
754
|
-
* 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.
|
|
755
539
|
*/
|
|
756
540
|
Attachment: typeof Model$1;
|
|
757
541
|
}
|
|
758
542
|
/**
|
|
759
|
-
* Wire the attachments layer, once per app
|
|
760
|
-
*
|
|
761
|
-
*
|
|
762
|
-
* lazily and throw a clear error when it was never called.
|
|
763
|
-
*
|
|
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.
|
|
764
546
|
* @example
|
|
765
|
-
*
|
|
766
|
-
* // config/attachments.ts
|
|
767
|
-
* import { configureAttachments } from '@guren/core'
|
|
768
|
-
* import { attachments } from '@/db/schema'
|
|
769
|
-
*
|
|
770
|
-
* export const { Attachment } = configureAttachments({
|
|
771
|
-
* table: attachments,
|
|
772
|
-
* storage: () => container.make('storage'),
|
|
773
|
-
* disk: 'media',
|
|
774
|
-
* })
|
|
775
|
-
* ```
|
|
547
|
+
* export const { Attachment } = configureAttachments({ table: attachments, storage: () => container.make('storage'), disk: 'media' })
|
|
776
548
|
*/
|
|
777
549
|
declare function configureAttachments(options: ConfigureAttachmentsOptions): ConfiguredAttachments;
|
|
778
550
|
//#endregion
|
|
779
551
|
//#region src/attachments/delivery.d.ts
|
|
780
552
|
/**
|
|
781
|
-
* The signed attachment delivery route's controller (RFC 0015 §1).
|
|
782
|
-
*
|
|
783
|
-
*
|
|
784
|
-
*
|
|
785
|
-
*
|
|
786
|
-
* Raw on purpose, too: every semantic parameter must be re-read from the
|
|
787
|
-
* same `URLSearchParams` parse the signature canonicalizes with. Hono's
|
|
788
|
-
* query decoder disagrees with `URLSearchParams` on malformed
|
|
789
|
-
* percent-encoding, and a parser mismatch there is a signed-URL rewrite
|
|
790
|
-
* 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.
|
|
791
558
|
*/
|
|
792
559
|
declare class AttachmentDeliveryController extends Controller {
|
|
793
560
|
show(): Promise<Response>;
|
|
794
561
|
}
|
|
795
562
|
/**
|
|
796
|
-
* Mount the signed delivery route (RFC 0015 §6)
|
|
797
|
-
* route registrar:
|
|
798
|
-
*
|
|
799
|
-
* ```ts
|
|
800
|
-
* // routes/web.ts
|
|
801
|
-
* import { registerAttachmentRoutes } from '@guren/core'
|
|
802
|
-
*
|
|
803
|
-
* export function registerWebRoutes(router: Router): void {
|
|
804
|
-
* registerAttachmentRoutes(router)
|
|
805
|
-
* // …app routes…
|
|
806
|
-
* }
|
|
807
|
-
* ```
|
|
563
|
+
* Mount the signed delivery route (RFC 0015 §6) from the app's route registrar.
|
|
808
564
|
*
|
|
809
|
-
*
|
|
810
|
-
*
|
|
811
|
-
*
|
|
812
|
-
* booted, so a config-dependent throw here would break every inspection
|
|
813
|
-
* tool. The controller resolves the engine per request instead; at runtime
|
|
814
|
-
* providers register before routes mount, so the configured prefix and
|
|
815
|
-
* 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.
|
|
816
568
|
*/
|
|
817
569
|
declare function registerAttachmentRoutes(router: Router): void;
|
|
818
570
|
//#endregion
|
|
819
571
|
//#region src/attachments/prune-command.d.ts
|
|
820
572
|
/**
|
|
821
|
-
* Console sweeper for the attachments layer (RFC 0013 §8)
|
|
822
|
-
* `attachableType`/`attachableId` pair
|
|
823
|
-
*
|
|
824
|
-
*
|
|
825
|
-
*
|
|
826
|
-
* prefixes left behind by crashed or raced jobs.
|
|
827
|
-
*
|
|
828
|
-
* Register it in the app's console kernel:
|
|
829
|
-
*
|
|
830
|
-
* ```ts
|
|
831
|
-
* // src/console.ts
|
|
832
|
-
* import { AttachmentsPruneCommand } from '@guren/core'
|
|
833
|
-
* kernel.register(AttachmentsPruneCommand)
|
|
834
|
-
* ```
|
|
835
|
-
*
|
|
836
|
-
* Orphan rows are detected by resolving each `attachableType` through
|
|
837
|
-
* `Model.morphMap` and querying for the records — set
|
|
838
|
-
* `Model.morphMap = { Post, User, ... }` for every model that declares
|
|
839
|
-
* 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.
|
|
840
578
|
*/
|
|
841
579
|
declare class AttachmentsPruneCommand extends Command {
|
|
842
580
|
static signature: string;
|
|
@@ -846,28 +584,17 @@ declare class AttachmentsPruneCommand extends Command {
|
|
|
846
584
|
//#endregion
|
|
847
585
|
//#region src/attachments/generate-variants-job.d.ts
|
|
848
586
|
/**
|
|
849
|
-
* Queue job behind `attach(..., { queued: true })` (RFC 0013 Part 2):
|
|
850
|
-
*
|
|
851
|
-
* opted in, and generates the declared variants, flipping their `pending`
|
|
852
|
-
* 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.
|
|
853
589
|
*
|
|
854
|
-
*
|
|
855
|
-
*
|
|
856
|
-
* work happens — point it at a runtime with an image processor (Bun with
|
|
857
|
-
* `Bun.Image`, or a custom `configureAttachments({ processor })`), or every
|
|
858
|
-
* 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`.
|
|
859
592
|
*/
|
|
860
593
|
declare class GenerateVariantsJob extends Job<GenerateVariantsPayload> {
|
|
861
|
-
/**
|
|
862
|
-
* Pinned wire name: queued messages must survive bundler identifier
|
|
863
|
-
* mangling and any future rename of this class.
|
|
864
|
-
*/
|
|
594
|
+
/** Pinned: queued messages must survive identifier mangling and renames. */
|
|
865
595
|
static jobName: string;
|
|
866
596
|
handle(payload: GenerateVariantsPayload): Promise<void>;
|
|
867
|
-
/**
|
|
868
|
-
* After the last retry, stop `pending` variants from looking in-flight
|
|
869
|
-
* forever — their URLs already fall back to the original either way.
|
|
870
|
-
*/
|
|
597
|
+
/** After the last retry, stop `pending` variants looking in-flight forever. */
|
|
871
598
|
failed(payload: GenerateVariantsPayload, _error: Error): Promise<void>;
|
|
872
599
|
}
|
|
873
600
|
//#endregion
|