@dimah-s3/server 1.7.1 → 2.0.0-beta.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/README.md +72 -16
- package/dist/adapters/express.d.ts +7 -7
- package/dist/adapters/express.d.ts.map +1 -1
- package/dist/adapters/express.js +94 -94
- package/dist/adapters/express.js.map +1 -1
- package/dist/adapters/fastify.d.ts +11 -5
- package/dist/adapters/fastify.d.ts.map +1 -1
- package/dist/adapters/fastify.js +94 -94
- package/dist/adapters/fastify.js.map +1 -1
- package/dist/adapters/node.d.ts +20 -3
- package/dist/adapters/node.d.ts.map +1 -1
- package/dist/adapters/node.js +92 -92
- package/dist/adapters/node.js.map +1 -1
- package/dist/api/context.d.ts +8 -4
- package/dist/api/context.d.ts.map +1 -1
- package/dist/api/{routes/index.d.ts → core-endpoints.d.ts} +43 -68
- package/dist/api/core-endpoints.d.ts.map +1 -0
- package/dist/api/create-s3-endpoint.d.ts +70 -48
- package/dist/api/create-s3-endpoint.d.ts.map +1 -1
- package/dist/api/create-s3-middleware.d.ts +19 -16
- package/dist/api/create-s3-middleware.d.ts.map +1 -1
- package/dist/api/router-context.d.ts +23 -0
- package/dist/api/router-context.d.ts.map +1 -0
- package/dist/api/router.d.ts +15 -5
- package/dist/api/router.d.ts.map +1 -1
- package/dist/config/feature-toggle.d.ts +16 -0
- package/dist/config/feature-toggle.d.ts.map +1 -0
- package/dist/config/resolve-config.d.ts +9 -0
- package/dist/config/resolve-config.d.ts.map +1 -0
- package/dist/config/resolve-routes.d.ts +37 -0
- package/dist/config/resolve-routes.d.ts.map +1 -0
- package/dist/dimah-s3.d.ts +22 -32
- package/dist/dimah-s3.d.ts.map +1 -1
- package/dist/helpers/authorize-download.d.ts +25 -0
- package/dist/helpers/authorize-download.d.ts.map +1 -0
- package/dist/helpers/aws-errors.d.ts +16 -0
- package/dist/helpers/aws-errors.d.ts.map +1 -0
- package/dist/helpers/best-effort.d.ts +22 -3
- package/dist/helpers/best-effort.d.ts.map +1 -1
- package/dist/helpers/checksum-config.d.ts +13 -0
- package/dist/helpers/checksum-config.d.ts.map +1 -0
- package/dist/helpers/constraints.d.ts +17 -12
- package/dist/helpers/constraints.d.ts.map +1 -1
- package/dist/helpers/error-boundary.d.ts +28 -0
- package/dist/helpers/error-boundary.d.ts.map +1 -0
- package/dist/helpers/finalize-confirmed.d.ts +42 -13
- package/dist/helpers/finalize-confirmed.d.ts.map +1 -1
- package/dist/helpers/head-object.d.ts +6 -9
- package/dist/helpers/head-object.d.ts.map +1 -1
- package/dist/helpers/hooks.d.ts +29 -15
- package/dist/helpers/hooks.d.ts.map +1 -1
- package/dist/helpers/inline-types.d.ts +24 -7
- package/dist/helpers/inline-types.d.ts.map +1 -1
- package/dist/helpers/list-parts.d.ts +4 -6
- package/dist/helpers/list-parts.d.ts.map +1 -1
- package/dist/helpers/metadata-encoding.d.ts +15 -0
- package/dist/helpers/metadata-encoding.d.ts.map +1 -0
- package/dist/helpers/object-meta.d.ts +39 -0
- package/dist/helpers/object-meta.d.ts.map +1 -0
- package/dist/helpers/object-s3.d.ts +5 -2
- package/dist/helpers/object-s3.d.ts.map +1 -1
- package/dist/helpers/open-target.d.ts +89 -0
- package/dist/helpers/open-target.d.ts.map +1 -0
- package/dist/helpers/part-layout.d.ts +19 -0
- package/dist/helpers/part-layout.d.ts.map +1 -0
- package/dist/helpers/presign.d.ts +54 -0
- package/dist/helpers/presign.d.ts.map +1 -0
- package/dist/helpers/request.d.ts +6 -11
- package/dist/helpers/request.d.ts.map +1 -1
- package/dist/helpers/resolve-target.d.ts +28 -20
- package/dist/helpers/resolve-target.d.ts.map +1 -1
- package/dist/helpers/sniff-object.d.ts +22 -0
- package/dist/helpers/sniff-object.d.ts.map +1 -0
- package/dist/helpers/ticket.d.ts +75 -0
- package/dist/helpers/ticket.d.ts.map +1 -0
- package/dist/index.d.ts +4 -12
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +2647 -1579
- package/dist/index.js.map +1 -1
- package/dist/operations/catalog.d.ts +16 -0
- package/dist/operations/catalog.d.ts.map +1 -0
- package/dist/operations/confirm.d.ts +19 -0
- package/dist/operations/confirm.d.ts.map +1 -0
- package/dist/operations/delete-many.d.ts +18 -0
- package/dist/operations/delete-many.d.ts.map +1 -0
- package/dist/operations/delete.d.ts +14 -0
- package/dist/operations/delete.d.ts.map +1 -0
- package/dist/operations/download.d.ts +20 -0
- package/dist/operations/download.d.ts.map +1 -0
- package/dist/operations/file.d.ts +38 -0
- package/dist/operations/file.d.ts.map +1 -0
- package/dist/operations/multipart/abort.d.ts +20 -0
- package/dist/operations/multipart/abort.d.ts.map +1 -0
- package/dist/operations/multipart/complete.d.ts +21 -0
- package/dist/operations/multipart/complete.d.ts.map +1 -0
- package/dist/operations/multipart/init.d.ts +19 -0
- package/dist/operations/multipart/init.d.ts.map +1 -0
- package/dist/operations/multipart/list-parts.d.ts +11 -0
- package/dist/operations/multipart/list-parts.d.ts.map +1 -0
- package/dist/operations/multipart/open-multipart.d.ts +25 -0
- package/dist/operations/multipart/open-multipart.d.ts.map +1 -0
- package/dist/operations/multipart/sign-part.d.ts +20 -0
- package/dist/operations/multipart/sign-part.d.ts.map +1 -0
- package/dist/operations/put.d.ts +18 -0
- package/dist/operations/put.d.ts.map +1 -0
- package/dist/operations/run-operation.d.ts +18 -0
- package/dist/operations/run-operation.d.ts.map +1 -0
- package/dist/operations/s3-api.d.ts +12 -0
- package/dist/operations/s3-api.d.ts.map +1 -0
- package/dist/operations/upload.d.ts +19 -0
- package/dist/operations/upload.d.ts.map +1 -0
- package/dist/plugin/apply-plugins.d.ts +9 -11
- package/dist/plugin/apply-plugins.d.ts.map +1 -1
- package/dist/plugin/chain-hooks.d.ts +12 -9
- package/dist/plugin/chain-hooks.d.ts.map +1 -1
- package/dist/plugin/define-plugin.d.ts +11 -4
- package/dist/plugin/define-plugin.d.ts.map +1 -1
- package/dist/plugin/index.d.ts +1 -2
- package/dist/plugin/index.d.ts.map +1 -1
- package/dist/plugin/types.d.ts +52 -56
- package/dist/plugin/types.d.ts.map +1 -1
- package/dist/plugins.d.ts +10 -8
- package/dist/plugins.d.ts.map +1 -1
- package/dist/plugins.js +325 -1627
- package/dist/plugins.js.map +1 -1
- package/dist/route.d.ts +0 -1
- package/dist/route.d.ts.map +1 -1
- package/dist/types/config.d.ts +171 -172
- package/dist/types/config.d.ts.map +1 -1
- package/dist/types/hook-contexts.d.ts +139 -147
- package/dist/types/hook-contexts.d.ts.map +1 -1
- package/dist/types/index.d.ts +3 -3
- package/dist/types/index.d.ts.map +1 -1
- package/dist/types/locals.d.ts +37 -0
- package/dist/types/locals.d.ts.map +1 -0
- package/dist/types/resolved.d.ts +118 -0
- package/dist/types/resolved.d.ts.map +1 -0
- package/package.json +8 -12
- package/dist/api/bind-endpoints.d.ts +0 -12
- package/dist/api/bind-endpoints.d.ts.map +0 -1
- package/dist/api/index.d.ts +0 -6
- package/dist/api/index.d.ts.map +0 -1
- package/dist/api/index.js +0 -1353
- package/dist/api/index.js.map +0 -1
- package/dist/api/routes/catalog.d.ts +0 -9
- package/dist/api/routes/catalog.d.ts.map +0 -1
- package/dist/api/routes/confirm.d.ts +0 -13
- package/dist/api/routes/confirm.d.ts.map +0 -1
- package/dist/api/routes/delete-batch.d.ts +0 -14
- package/dist/api/routes/delete-batch.d.ts.map +0 -1
- package/dist/api/routes/delete.d.ts +0 -26
- package/dist/api/routes/delete.d.ts.map +0 -1
- package/dist/api/routes/download.d.ts +0 -21
- package/dist/api/routes/download.d.ts.map +0 -1
- package/dist/api/routes/file.d.ts +0 -20
- package/dist/api/routes/file.d.ts.map +0 -1
- package/dist/api/routes/index.d.ts.map +0 -1
- package/dist/api/routes/multipart/abort.d.ts +0 -16
- package/dist/api/routes/multipart/abort.d.ts.map +0 -1
- package/dist/api/routes/multipart/complete.d.ts +0 -22
- package/dist/api/routes/multipart/complete.d.ts.map +0 -1
- package/dist/api/routes/multipart/init.d.ts +0 -22
- package/dist/api/routes/multipart/init.d.ts.map +0 -1
- package/dist/api/routes/multipart/list-parts.d.ts +0 -17
- package/dist/api/routes/multipart/list-parts.d.ts.map +0 -1
- package/dist/api/routes/multipart/part.d.ts +0 -20
- package/dist/api/routes/multipart/part.d.ts.map +0 -1
- package/dist/api/routes/upload.d.ts +0 -22
- package/dist/api/routes/upload.d.ts.map +0 -1
- package/dist/errors.d.ts +0 -23
- package/dist/errors.d.ts.map +0 -1
- package/dist/helpers/expires.d.ts +0 -21
- package/dist/helpers/expires.d.ts.map +0 -1
- package/dist/helpers/features.d.ts +0 -17
- package/dist/helpers/features.d.ts.map +0 -1
- package/dist/helpers/index.d.ts +0 -19
- package/dist/helpers/index.d.ts.map +0 -1
- package/dist/helpers/is-aws-not-found.d.ts +0 -5
- package/dist/helpers/is-aws-not-found.d.ts.map +0 -1
- package/dist/helpers/previous-key.d.ts +0 -5
- package/dist/helpers/previous-key.d.ts.map +0 -1
- package/dist/helpers/resolve-route.d.ts +0 -33
- package/dist/helpers/resolve-route.d.ts.map +0 -1
- package/dist/plugin/hook-registry.d.ts +0 -21
- package/dist/plugin/hook-registry.d.ts.map +0 -1
- package/dist/put.d.ts +0 -15
- package/dist/put.d.ts.map +0 -1
package/dist/types/config.d.ts
CHANGED
|
@@ -1,18 +1,9 @@
|
|
|
1
1
|
import type { S3Client } from "@aws-sdk/client-s3";
|
|
2
|
-
import type { S3ObjectAcl, UploadPresignMethod } from "@dimah-s3/core";
|
|
3
|
-
import type { DeleteGuardContext, DeleteOnDeletedContext, DownloadGuardContext, DownloadOnPresignedContext, DownloadResolveInfo, GuardContext, MultipartGuardContext, MultipartOnAbortContext,
|
|
2
|
+
import type { ContentDispositionType, S3Api, S3ObjectAcl, S3RouteName, UploadPresignMethod } from "@dimah-s3/core";
|
|
3
|
+
import type { DeleteGuardContext, DeleteOnDeletedContext, DownloadGuardContext, DownloadOnPresignedContext, DownloadResolveContext, DownloadResolveInfo, GuardContext, MultipartGuardContext, MultipartOnAbortContext, RouteGuardContext, S3Operation, UploadConfirmGuardContext, UploadGuardContext, UploadObjectContext, UploadObjectInfo, UploadOnConfirmedContext, UploadOnStartContext } from "./hook-contexts";
|
|
4
|
+
import type { DimahS3Locals, DimahS3RoutePluginOptions, Guard, LifecycleHook } from "./locals";
|
|
4
5
|
import type { DimahS3Plugin } from "../plugin/types.js";
|
|
5
|
-
|
|
6
|
-
/** The three nested features on a named route. */
|
|
7
|
-
export declare const ROUTE_FEATURES: readonly ["upload", "download", "delete"];
|
|
8
|
-
export type RouteFeature = (typeof ROUTE_FEATURES)[number];
|
|
9
|
-
/**
|
|
10
|
-
* Endpoint operations. Multipart is nested under upload — it is not a
|
|
11
|
-
* fourth route feature.
|
|
12
|
-
*/
|
|
13
|
-
export declare const ROUTE_OPERATIONS: readonly ["upload", "download", "delete", "multipart"];
|
|
14
|
-
export type RouteOperation = (typeof ROUTE_OPERATIONS)[number];
|
|
15
|
-
/** `true` or an options object enables the feature; omit or `false` disables it. */
|
|
6
|
+
/** `true` or an options object turns the feature on; omit it or pass `false` to keep it off. */
|
|
16
7
|
export type FeatureToggle<T> = boolean | T;
|
|
17
8
|
/** Optional structured logger on {@link DimahS3Config}. */
|
|
18
9
|
export type DimahS3Logger = {
|
|
@@ -21,154 +12,160 @@ export type DimahS3Logger = {
|
|
|
21
12
|
warn?: (message: string, ...args: unknown[]) => void;
|
|
22
13
|
error?: (message: string, ...args: unknown[]) => void;
|
|
23
14
|
};
|
|
24
|
-
export type DisabledFeature = {
|
|
25
|
-
enabled: false;
|
|
26
|
-
};
|
|
27
|
-
export type EnabledFeature<T extends object> = T & {
|
|
28
|
-
enabled: true;
|
|
29
|
-
};
|
|
30
|
-
export type ResolvedFeature<T extends object> = EnabledFeature<T> | DisabledFeature;
|
|
31
15
|
/**
|
|
32
|
-
*
|
|
33
|
-
*
|
|
34
|
-
*
|
|
16
|
+
* Subject an upload ticket is bound to, such as a user or tenant id. A ticket
|
|
17
|
+
* issued for one subject is rejected for another. Return `undefined` to
|
|
18
|
+
* issue an unbound ticket.
|
|
19
|
+
*
|
|
20
|
+
* It runs after the instance and route guards, when a ticket is issued and
|
|
21
|
+
* each time one is used, so `locals` holds only what those guards returned.
|
|
22
|
+
* Feature guards such as `upload.guard` have not run yet.
|
|
23
|
+
*/
|
|
24
|
+
export type TicketSubject = (context: RouteGuardContext) => string | undefined | Promise<string | undefined>;
|
|
25
|
+
/**
|
|
26
|
+
* Multipart uploads under `upload.multipart`. Init runs `upload.guard` and
|
|
27
|
+
* `upload.onStart`. Complete runs `guard` (`action: "complete"`), then
|
|
28
|
+
* `upload.confirmGuard` and `upload.onConfirmed`.
|
|
35
29
|
*/
|
|
36
30
|
export type MultipartConfig = {
|
|
37
|
-
/**
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
31
|
+
/**
|
|
32
|
+
* Preferred part size in bytes. The server raises it when the file would
|
|
33
|
+
* need more than 10,000 parts, and keeps it within S3's part limits.
|
|
34
|
+
* @default 8388608 (8 MiB)
|
|
35
|
+
*/
|
|
36
|
+
partSize?: number;
|
|
37
|
+
/**
|
|
38
|
+
* Seconds a multipart ticket stays valid. Abort accepts an expired ticket
|
|
39
|
+
* for 7 more days.
|
|
40
|
+
* @default 86400
|
|
41
|
+
*/
|
|
42
|
+
ticketExpiresIn?: number;
|
|
43
|
+
/** Authorizes part signing, list, abort and complete. Branch on `action` if needed. */
|
|
44
|
+
guard?: Guard<MultipartGuardContext>;
|
|
45
|
+
onAbort?: LifecycleHook<MultipartOnAbortContext>;
|
|
43
46
|
};
|
|
44
|
-
/** Upload feature: constraints, object identity
|
|
47
|
+
/** Upload feature: constraints, object identity and lifecycle hooks. */
|
|
45
48
|
export type UploadConfig = {
|
|
46
49
|
/** HTML `accept` tokens (`image/*`, `.pdf`, `application/pdf`). */
|
|
47
50
|
fileTypes?: string[];
|
|
48
|
-
/**
|
|
49
|
-
* Max declared size, signed part size, listed multipart total, and
|
|
50
|
-
* HeadObject size in bytes.
|
|
51
|
-
*/
|
|
51
|
+
/** Largest file in bytes. Checked on the declared size and again after HeadObject. */
|
|
52
52
|
maxFileSize?: number;
|
|
53
53
|
/**
|
|
54
|
-
* Server-owned object identity. Return `
|
|
55
|
-
* the route `keyPrefix`, `key` for the rest of the key
|
|
56
|
-
*
|
|
57
|
-
* `
|
|
58
|
-
* Runs on upload / multipart init only. Default key is
|
|
59
|
-
* `{keyPrefix}/{uuid}/{name}` (`keyPrefix` defaults to the route name).
|
|
60
|
-
* `keyPrefix: false` generates `{uuid}/{name}` and skips the follow-up
|
|
61
|
-
* namespace check.
|
|
54
|
+
* Server-owned object identity. Return `keyFolder` for a path segment
|
|
55
|
+
* under the route `keyPrefix`, or `key` for the rest of the key, plus
|
|
56
|
+
* optional S3 `metadata`, `acl`, `storageClass`, `cacheControl` and
|
|
57
|
+
* `tagging`. The default key is `{keyPrefix}/{uuid}/{name}`.
|
|
62
58
|
*/
|
|
63
59
|
object?: (context: UploadObjectContext) => UploadObjectInfo | void | Promise<UploadObjectInfo | void>;
|
|
64
60
|
/**
|
|
65
|
-
*
|
|
61
|
+
* ACL used when `object` does not return one.
|
|
66
62
|
* @default "private"
|
|
67
63
|
*/
|
|
68
64
|
acl?: S3ObjectAcl;
|
|
69
|
-
/**
|
|
65
|
+
/**
|
|
66
|
+
* Presign verb. R2 has no presigned POST.
|
|
67
|
+
* @default "PUT"
|
|
68
|
+
*/
|
|
70
69
|
method?: UploadPresignMethod;
|
|
71
|
-
/**
|
|
70
|
+
/**
|
|
71
|
+
* Presigned URL TTL in seconds, capped by the instance `maxExpiresIn`.
|
|
72
|
+
* @default 600
|
|
73
|
+
*/
|
|
72
74
|
expiresIn?: number;
|
|
73
75
|
/**
|
|
74
|
-
*
|
|
75
|
-
*
|
|
76
|
+
* Seconds after the URL expires during which confirm is still accepted.
|
|
77
|
+
* @default 3600
|
|
78
|
+
*/
|
|
79
|
+
confirmWindow?: number;
|
|
80
|
+
/**
|
|
81
|
+
* Require a SHA-256 `checksum` from the client and sign it into the
|
|
82
|
+
* upload. `verifyContent` turns it on; `false` together with
|
|
83
|
+
* `verifyContent` throws.
|
|
76
84
|
*/
|
|
77
85
|
checksum?: boolean;
|
|
78
86
|
/**
|
|
79
|
-
*
|
|
80
|
-
*
|
|
87
|
+
* After confirm, read the first bytes of the object and check them against
|
|
88
|
+
* the declared type. An upload without a type is checked against the type
|
|
89
|
+
* its name gives (`x.png` is checked as `image/png`), since downloads serve
|
|
90
|
+
* it inline as that type. A mismatch deletes the object and returns
|
|
91
|
+
* `FILE_CONTENT_MISMATCH`.
|
|
81
92
|
*/
|
|
82
|
-
|
|
83
|
-
/**
|
|
84
|
-
guard?: (context: UploadGuardContext) => Promise<void> | void;
|
|
85
|
-
/** After a single-shot URL is signed. Multipart uses `multipart.onInit`. */
|
|
86
|
-
onPresigned?: (context: UploadOnPresignedContext) => Promise<void> | void;
|
|
87
|
-
/** Confirm and multipart complete. */
|
|
88
|
-
confirmGuard?: (context: UploadConfirmGuardContext) => Promise<void> | void;
|
|
89
|
-
/** After HeadObject on confirm and multipart complete. */
|
|
90
|
-
onConfirmed?: (context: UploadOnConfirmedContext) => Promise<void> | void;
|
|
91
|
-
/** Opt-in multipart. Default off. */
|
|
93
|
+
verifyContent?: boolean;
|
|
94
|
+
/** Opt-in multipart uploads. Off by default. */
|
|
92
95
|
multipart?: FeatureToggle<MultipartConfig>;
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
+
/** Presign, multipart init and `s3.put`. */
|
|
97
|
+
guard?: Guard<UploadGuardContext>;
|
|
98
|
+
/** Once the upload can begin. A throw cancels it. */
|
|
99
|
+
onStart?: LifecycleHook<UploadOnStartContext>;
|
|
100
|
+
/** Confirm and multipart complete, after HeadObject. A rejection deletes the object. */
|
|
101
|
+
confirmGuard?: Guard<UploadConfirmGuardContext>;
|
|
96
102
|
/**
|
|
97
|
-
*
|
|
98
|
-
* A
|
|
99
|
-
*
|
|
100
|
-
* Independent of {@link UploadConfig.expiresIn}.
|
|
103
|
+
* After the object is verified. It runs at least once per upload: dedupe
|
|
104
|
+
* on `uploadToken`. A plain `Error` returns `500` and keeps the object;
|
|
105
|
+
* reject content in `confirmGuard` instead.
|
|
101
106
|
*/
|
|
102
|
-
|
|
107
|
+
onConfirmed?: LifecycleHook<UploadOnConfirmedContext>;
|
|
108
|
+
};
|
|
109
|
+
/** Download feature. A config object, or `true`, turns it on. */
|
|
110
|
+
export type DownloadConfig = {
|
|
103
111
|
/**
|
|
104
|
-
*
|
|
112
|
+
* Largest presign TTL in seconds. A shorter client `expiresIn` is used as
|
|
113
|
+
* is. `resolve` can choose another TTL, capped by the instance
|
|
114
|
+
* `maxExpiresIn`.
|
|
115
|
+
* @default 600
|
|
105
116
|
*/
|
|
106
|
-
|
|
117
|
+
maxExpiresIn?: number;
|
|
118
|
+
/** @default "attachment" */
|
|
119
|
+
disposition?: ContentDispositionType;
|
|
107
120
|
/**
|
|
108
|
-
* MIME types, or `type/*` wildcards, that may open
|
|
109
|
-
*
|
|
110
|
-
*
|
|
111
|
-
*
|
|
112
|
-
* XML (including `image/svg+xml`), or JavaScript; list those exactly to
|
|
113
|
-
* allow them. An object stored as `application/octet-stream` is typed from
|
|
114
|
-
* its file name, and that type is signed as `ResponseContentType`.
|
|
115
|
-
* Uses `resolveInlineDisposition` from `@dimah-s3/core`, and the catalog
|
|
116
|
-
* returns this list so a client can call the same helper.
|
|
121
|
+
* MIME types, or `type/*` wildcards, that may open inline. Anything else
|
|
122
|
+
* is sent as `attachment`. `false` never opens inline. The default is
|
|
123
|
+
* `DEFAULT_INLINE_TYPES` from `@dimah-s3/core`, without `application/pdf`
|
|
124
|
+
* in proxy mode.
|
|
117
125
|
*/
|
|
118
|
-
inlineTypes?: readonly string[];
|
|
126
|
+
inlineTypes?: readonly string[] | false;
|
|
119
127
|
/**
|
|
120
|
-
* `"presign"`
|
|
121
|
-
*
|
|
128
|
+
* `"presign"` returns an S3 URL. `"proxy"` returns a `/file` URL that
|
|
129
|
+
* streams through the server.
|
|
130
|
+
* @default "presign"
|
|
122
131
|
*/
|
|
123
132
|
mode?: "presign" | "proxy";
|
|
124
|
-
/**
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
resolve?: (context: DownloadGuardContext) => DownloadResolveInfo | void | Promise<DownloadResolveInfo | void>;
|
|
129
|
-
guard?: (context: DownloadGuardContext) => Promise<void> | void;
|
|
130
|
-
onPresigned?: (context: DownloadOnPresignedContext) => Promise<void> | void;
|
|
133
|
+
/** Per-request download options. Returned values override route defaults. */
|
|
134
|
+
resolve?: (context: DownloadResolveContext) => DownloadResolveInfo | void | Promise<DownloadResolveInfo | void>;
|
|
135
|
+
guard?: Guard<DownloadGuardContext>;
|
|
136
|
+
onPresigned?: LifecycleHook<DownloadOnPresignedContext>;
|
|
131
137
|
};
|
|
132
|
-
/** Delete feature. A config object
|
|
138
|
+
/** Delete feature. A config object, or `true`, turns it on. */
|
|
133
139
|
export type DeleteConfig = {
|
|
134
|
-
guard?:
|
|
135
|
-
onDeleted?:
|
|
140
|
+
guard?: Guard<DeleteGuardContext>;
|
|
141
|
+
onDeleted?: LifecycleHook<DeleteOnDeletedContext>;
|
|
136
142
|
};
|
|
137
143
|
/**
|
|
138
|
-
* Named file route
|
|
139
|
-
*
|
|
140
|
-
* Prefer one feature per route; combine only when those callers share
|
|
141
|
-
* the key namespace.
|
|
144
|
+
* Named file route under {@link DimahS3Config.routes}. Upload, download,
|
|
145
|
+
* delete and `upload.multipart` stay off until set.
|
|
142
146
|
*/
|
|
143
147
|
export type DimahS3RouteConfig = {
|
|
144
|
-
/**
|
|
148
|
+
/** Overrides the instance S3 client for this route. */
|
|
145
149
|
client?: S3Client;
|
|
146
|
-
/**
|
|
150
|
+
/** Overrides the instance bucket for this route. */
|
|
147
151
|
bucket?: string;
|
|
148
152
|
/**
|
|
149
|
-
* Object-key namespace. Defaults to the route name.
|
|
150
|
-
*
|
|
151
|
-
*
|
|
152
|
-
*
|
|
153
|
-
* This is route isolation, not per-user ownership — add
|
|
154
|
-
* `download.guard` / `delete.guard` or `db()`.
|
|
153
|
+
* Object-key namespace. Defaults to the route name. Uploads write under
|
|
154
|
+
* it, and every other operation rejects keys outside it (`KEY_INVALID`).
|
|
155
|
+
* `false` removes the bound. This isolates routes; it does not check who
|
|
156
|
+
* owns an object.
|
|
155
157
|
*/
|
|
156
158
|
keyPrefix?: string | false;
|
|
157
|
-
/** Runs before every operation on this route. */
|
|
158
|
-
guard?:
|
|
159
|
-
/**
|
|
160
|
-
|
|
161
|
-
* Hooks from opted-out plugins are not merged onto this route.
|
|
162
|
-
*/
|
|
163
|
-
plugins?: {
|
|
164
|
-
readonly [pluginId: string]: false;
|
|
165
|
-
};
|
|
159
|
+
/** Runs before every operation on this route, after the instance guard. */
|
|
160
|
+
guard?: Guard<RouteGuardContext>;
|
|
161
|
+
/** Per-plugin options for this route. `{ db: false }` turns a plugin off. */
|
|
162
|
+
plugins?: DimahS3RoutePluginOptions;
|
|
166
163
|
upload?: FeatureToggle<UploadConfig>;
|
|
167
164
|
download?: FeatureToggle<DownloadConfig>;
|
|
168
165
|
delete?: FeatureToggle<DeleteConfig>;
|
|
169
166
|
};
|
|
170
167
|
/**
|
|
171
|
-
* Options for
|
|
168
|
+
* Options for `dimahS3()`.
|
|
172
169
|
*
|
|
173
170
|
* @example
|
|
174
171
|
* ```ts
|
|
@@ -176,92 +173,94 @@ export type DimahS3RouteConfig = {
|
|
|
176
173
|
* client: awsS3,
|
|
177
174
|
* bucket: "my-bucket",
|
|
178
175
|
* routes: {
|
|
179
|
-
* uploads: route({
|
|
180
|
-
* upload: { fileTypes: ["image/*"], multipart: true },
|
|
181
|
-
* }),
|
|
176
|
+
* uploads: route({ upload: { fileTypes: ["image/*"], multipart: true } }),
|
|
182
177
|
* },
|
|
183
178
|
* });
|
|
184
179
|
* ```
|
|
185
180
|
*/
|
|
186
181
|
export type DimahS3Config = {
|
|
187
182
|
/**
|
|
188
|
-
* Default AWS SDK v3 `S3Client`. Required unless every route sets
|
|
189
|
-
*
|
|
183
|
+
* Default AWS SDK v3 `S3Client`. Required unless every route sets one. It
|
|
184
|
+
* must set `requestChecksumCalculation: "WHEN_REQUIRED"`.
|
|
190
185
|
*/
|
|
191
186
|
client?: S3Client;
|
|
192
|
-
/**
|
|
193
|
-
* Default bucket. Required unless every route sets
|
|
194
|
-
* {@link DimahS3RouteConfig.bucket}.
|
|
195
|
-
*/
|
|
187
|
+
/** Default bucket. Required unless every route sets one. */
|
|
196
188
|
bucket?: string;
|
|
197
189
|
/**
|
|
198
|
-
* API path prefix
|
|
199
|
-
* Must match `createS3Client({ basePath })` on the client.
|
|
190
|
+
* API path prefix. Must match `createS3Client({ basePath })`.
|
|
200
191
|
* @default "/api/s3"
|
|
201
192
|
*/
|
|
202
193
|
basePath?: string;
|
|
203
194
|
/**
|
|
204
|
-
*
|
|
205
|
-
*
|
|
195
|
+
* Absolute API URL, such as `https://app.example.com/api/s3`. Its path
|
|
196
|
+
* must equal `basePath` when both are set. Proxy download URLs use it,
|
|
197
|
+
* and in-process calls without a `request` use it as their URL.
|
|
198
|
+
*/
|
|
199
|
+
baseURL?: string;
|
|
200
|
+
/**
|
|
201
|
+
* Upload ticket secret, at least 32 characters. Pass an array to rotate:
|
|
202
|
+
* the first value signs, and every value verifies. Defaults to the
|
|
203
|
+
* `DIMAH_S3_SECRET` environment variable.
|
|
204
|
+
*/
|
|
205
|
+
secret?: string | readonly string[];
|
|
206
|
+
/** Binds upload tickets to a subject. Defaults to the first plugin that provides one. */
|
|
207
|
+
ticketSubject?: TicketSubject;
|
|
208
|
+
/**
|
|
209
|
+
* Largest presign TTL in seconds for any route.
|
|
206
210
|
* @default 604800
|
|
207
211
|
*/
|
|
208
212
|
maxExpiresIn?: number;
|
|
209
213
|
/**
|
|
210
|
-
*
|
|
211
|
-
*
|
|
214
|
+
* Largest JSON request body in bytes, counted on the stream.
|
|
215
|
+
* @default 1048576
|
|
212
216
|
*/
|
|
217
|
+
maxRequestBodySize?: number;
|
|
218
|
+
/** Logs config errors and unexpected failures. `false` silences the default `console` logger. */
|
|
213
219
|
logger?: DimahS3Logger | false;
|
|
214
|
-
/** Called after an unexpected throw is mapped to `INTERNAL_ERROR`. */
|
|
215
|
-
onError?: (error: unknown, context: {
|
|
216
|
-
request?: Request;
|
|
217
|
-
}) => void;
|
|
218
|
-
/** Runs before every operation, before route lookup. Throw to reject. */
|
|
219
|
-
guard?: (context: GuardContext) => Promise<void> | void;
|
|
220
220
|
/**
|
|
221
|
-
*
|
|
222
|
-
*
|
|
221
|
+
* Called with every unexpected failure before it becomes `500
|
|
222
|
+
* INTERNAL_ERROR`, such as a hook that threw a plain `Error` or an S3
|
|
223
|
+
* outage. `operation` is the call it failed in, when known. A throw or a
|
|
224
|
+
* rejection from it is logged, never sent to the client.
|
|
223
225
|
*/
|
|
226
|
+
onError?: (error: unknown, context: {
|
|
227
|
+
request: Request;
|
|
228
|
+
operation?: S3Operation;
|
|
229
|
+
}) => void | Promise<void>;
|
|
230
|
+
/** Runs before every operation, before route lookup. */
|
|
231
|
+
guard?: Guard<GuardContext>;
|
|
232
|
+
/** Server plugins, such as `db()` from `@dimah-s3/db`. */
|
|
224
233
|
plugins?: readonly DimahS3Plugin[];
|
|
225
234
|
/** Named file routes. At least one is required. */
|
|
226
235
|
routes: Record<string, DimahS3RouteConfig>;
|
|
227
236
|
};
|
|
228
|
-
|
|
229
|
-
export type
|
|
230
|
-
|
|
237
|
+
/** Options for in-process calls through `s3.api` and `s3.put`. */
|
|
238
|
+
export type S3ServerCallOptions = {
|
|
239
|
+
/** Headers for the synthetic request. Ignored when `request` is set. */
|
|
240
|
+
headers?: HeadersInit;
|
|
241
|
+
/**
|
|
242
|
+
* Aborts the call and the S3 requests behind it, like the browser
|
|
243
|
+
* option. Ignored when `request` is set: its own signal is used.
|
|
244
|
+
*/
|
|
245
|
+
signal?: AbortSignal;
|
|
246
|
+
/** Request that hooks see. Defaults to one built from `baseURL` (or `basePath`) and `headers`. */
|
|
247
|
+
request?: Request;
|
|
248
|
+
/** Trusted values that seed `locals` before guards run. Never read from HTTP. */
|
|
249
|
+
locals?: Partial<DimahS3Locals>;
|
|
231
250
|
};
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
251
|
+
/** `s3.api`: the browser client's shape, plus {@link S3ServerCallOptions}. */
|
|
252
|
+
export type DimahS3Api = S3Api<S3ServerCallOptions>;
|
|
253
|
+
/** Input to `s3.put`. */
|
|
254
|
+
export type PutInput = {
|
|
255
|
+
route: S3RouteName;
|
|
237
256
|
name: string;
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
/**
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
delete: ResolvedFeature<DeleteConfig>;
|
|
247
|
-
};
|
|
248
|
-
/**
|
|
249
|
-
* A {@link ResolvedRoute} after the named operation has been asserted on.
|
|
250
|
-
* `route.upload.fileTypes` is typed as present only after opening `"upload"`.
|
|
251
|
-
*/
|
|
252
|
-
export type OpenedRoute<F extends RouteOperation> = F extends "multipart" ? ResolvedRoute & {
|
|
253
|
-
upload: EnabledUploadConfig & {
|
|
254
|
-
multipart: EnabledFeature<MultipartConfig>;
|
|
255
|
-
};
|
|
256
|
-
} : F extends "upload" ? ResolvedRoute & {
|
|
257
|
-
upload: EnabledUploadConfig;
|
|
258
|
-
} : F extends "download" ? ResolvedRoute & {
|
|
259
|
-
download: EnabledFeature<DownloadConfig>;
|
|
260
|
-
} : F extends "delete" ? ResolvedRoute & {
|
|
261
|
-
delete: EnabledFeature<DeleteConfig>;
|
|
262
|
-
} : never;
|
|
263
|
-
/** Instance config after {@link dimahS3} normalizes routes and plugins. */
|
|
264
|
-
export type ResolvedDimahS3Config = Omit<DimahS3Config, "routes" | "plugins"> & {
|
|
265
|
-
routes: Record<string, ResolvedRoute>;
|
|
257
|
+
type?: string;
|
|
258
|
+
body: Blob | ReadableStream<Uint8Array> | Uint8Array | ArrayBuffer | string;
|
|
259
|
+
/** Byte size. Required for a `ReadableStream`. */
|
|
260
|
+
size?: number;
|
|
261
|
+
/** S3 user metadata written on the object. */
|
|
262
|
+
metadata?: Record<string, string>;
|
|
263
|
+
/** Visible to hooks (for example the db folder). Never written to S3. */
|
|
264
|
+
clientMetadata?: Record<string, string>;
|
|
266
265
|
};
|
|
267
266
|
//# sourceMappingURL=config.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/types/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,KAAK,
|
|
1
|
+
{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/types/config.ts"],"names":[],"mappings":"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"}
|