kizunajs 2.0.0-beta.2 → 2.0.0-beta.21
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 +3 -2
- package/dist/{adapter-CZW-unqX.mjs → adapter-BSqNrxhq.mjs} +522 -104
- package/dist/adapter-C3WYdSfx.d.cts +2754 -0
- package/dist/{adapter-DDR_yo9L.cjs → adapter-ClaFZoab.cjs} +638 -196
- package/dist/adapter-D4bTPElA.d.mts +2754 -0
- package/dist/adapter.cjs +37 -29
- package/dist/adapter.d.cts +3 -5
- package/dist/adapter.d.mts +3 -5
- package/dist/adapter.mjs +5 -5
- package/dist/{error-response-C8Ragjcd.cjs → error-response-C9ymqSU4.cjs} +25 -5
- package/dist/{error-response-C839d8By.mjs → error-response-CNQaKVYd.mjs} +20 -6
- package/dist/{security-scheme-BrszwGD5.d.cts → error-response-NoOGdh8H.d.mts} +151 -24
- package/dist/{security-scheme-D3nb4XKj.d.mts → error-response-YbkRMKno.d.cts} +151 -24
- package/dist/generator.cjs +190 -95
- package/dist/generator.d.cts +189 -28
- package/dist/generator.d.mts +189 -28
- package/dist/generator.mjs +151 -60
- package/dist/index.cjs +159 -84
- package/dist/index.d.cts +193 -253
- package/dist/index.d.mts +193 -253
- package/dist/index.mjs +112 -38
- package/dist/jobs-entry.cjs +12 -11
- package/dist/jobs-entry.d.cts +1 -1
- package/dist/jobs-entry.d.mts +1 -1
- package/dist/jobs-entry.mjs +3 -2
- package/dist/plugin-Dw-yCjTY.cjs +233 -0
- package/dist/{cache-CLN5y0Xp.mjs → plugin-server-BztlE1fz.mjs} +188 -49
- package/dist/{cache-BgohRj0i.cjs → plugin-server-kUsK7thV.cjs} +238 -93
- package/dist/plugin-xxCxibmu.mjs +138 -0
- package/dist/plugin.cjs +8 -72
- package/dist/plugin.d.cts +3 -3
- package/dist/plugin.d.mts +3 -3
- package/dist/plugin.mjs +2 -68
- package/dist/{protected-resource-metadata-CA0v5cjg.d.mts → protected-resource-metadata-B9hMFQ9N.d.cts} +1 -1
- package/dist/{protected-resource-metadata-Cprrv0mt.d.cts → protected-resource-metadata-CfBVsqIk.d.mts} +1 -1
- package/dist/{schemas-C56no6bv.cjs → schemas-DNPVDvkd.cjs} +28 -1
- package/dist/{schemas-CJQcc97N.mjs → schemas-HW2FDsvz.mjs} +23 -2
- package/dist/schemas.cjs +3 -2
- package/dist/schemas.d.cts +24 -3
- package/dist/schemas.d.mts +24 -3
- package/dist/schemas.mjs +3 -3
- package/package.json +1 -1
- package/src/adapter.ts +245 -29
- package/src/api-definition.ts +12 -16
- package/src/api.ts +7 -3
- package/src/brand.ts +29 -0
- package/src/config.ts +51 -10
- package/src/configured.ts +13 -6
- package/src/define-config.ts +118 -39
- package/src/generator.ts +363 -46
- package/src/group-routes.ts +106 -0
- package/src/groups.ts +140 -0
- package/src/handler-pipeline.ts +78 -19
- package/src/index.ts +15 -6
- package/src/job-runner.ts +5 -0
- package/src/job-transport.ts +3 -3
- package/src/job.ts +8 -6
- package/src/jobs-dev-runner.ts +6 -0
- package/src/jobs.ts +61 -8
- package/src/kizuna.ts +56 -33
- package/src/plugin-server.ts +129 -19
- package/src/plugin.ts +269 -127
- package/src/routes.ts +80 -32
- package/src/schemas.ts +1 -0
- package/src/tool-answer.ts +21 -0
- package/src/tool-definitions.ts +166 -0
- package/src/tool-events.ts +90 -18
- package/src/tool-records.ts +11 -3
- package/src/tool-runner.ts +298 -0
- package/src/types.ts +90 -24
- package/src/zod-internals.ts +22 -5
- package/src/zod-meta.ts +7 -2
- package/dist/adapter-BGfMqEkM.d.cts +0 -563
- package/dist/adapter-Ci3cfcoT.d.mts +0 -563
- package/dist/api-definition-BHnh15zD.d.mts +0 -803
- package/dist/api-definition-DQj-ewHy.d.cts +0 -803
- package/dist/error-response-BBGSdgYw.d.mts +0 -67
- package/dist/error-response-Do38sr-9.d.cts +0 -67
- package/dist/plugin-Cz0kn6Lk.d.mts +0 -830
- package/dist/plugin-DhKvx_T0.d.cts +0 -830
- package/src/tags.ts +0 -67
|
@@ -1,563 +0,0 @@
|
|
|
1
|
-
import { H as ResponseHeaders, J as Routes, L as Method, W as RouteDefinition, a as SecurityScheme, nt as ProblemDetails, z as RequiredPermissions } from "./security-scheme-D3nb4XKj.mjs";
|
|
2
|
-
import { $ as PathParamsCheck, B as Router, F as HandlersFromRoutes, Kt as NoCredential, L as RequestContextValues, P as HandlerReturn, Rt as Credential, W as ValidationStage, a as PluginArgs, at as EncodeStreamOptions, n as ApiPlugins, z as RouteHandler } from "./plugin-Cz0kn6Lk.mjs";
|
|
3
|
-
import { Q as JobsConfig, X as Jobs, Z as JobsArg, a as RequestContextOf, dt as JobRunner, ft as JobRunnerOptions, h as TagSet, i as JobsOf, it as JobErrorHandler, n as ApiPluginsOf, o as RoutesOf, p as TagKeysOf, s as SchemesOf, t as ApiDefinition, vt as JobTransport } from "./api-definition-BHnh15zD.mjs";
|
|
4
|
-
import { z } from "zod";
|
|
5
|
-
|
|
6
|
-
//#region src/access-check.d.ts
|
|
7
|
-
interface AccessCheckInput {
|
|
8
|
-
roles: readonly string[] | undefined;
|
|
9
|
-
requires: RequiredPermissions | undefined;
|
|
10
|
-
requiredSchemes: readonly string[];
|
|
11
|
-
schemes: Record<string, SecurityScheme> | undefined;
|
|
12
|
-
securityContext: Record<string, unknown>;
|
|
13
|
-
}
|
|
14
|
-
/**
|
|
15
|
-
* A guard's return with `permissions` settled: what the role holds, narrowed to
|
|
16
|
-
* the list the guard returned when it returned one. Anything the role cannot
|
|
17
|
-
* hold is dropped. Unchanged for an identity whose roles carry no permissions.
|
|
18
|
-
*/
|
|
19
|
-
declare const withPermissions: (scheme: string, definition: SecurityScheme | undefined, result: unknown) => unknown;
|
|
20
|
-
/**
|
|
21
|
-
* The permissions a route requires that an OAuth caller's role holds but the
|
|
22
|
-
* token does not carry. A token with more scope would pass, so the `403` says
|
|
23
|
-
* `insufficient_scope`. Empty when no new token could help.
|
|
24
|
-
*/
|
|
25
|
-
declare const insufficientScope: (input: AccessCheckInput) => string[];
|
|
26
|
-
/**
|
|
27
|
-
* The `403` detail when the caller holds none of the roles the route accepts
|
|
28
|
-
* or lacks a permission it requires, or `undefined`.
|
|
29
|
-
*/
|
|
30
|
-
declare const requiresDenial: (input: AccessCheckInput) => string | undefined;
|
|
31
|
-
//#endregion
|
|
32
|
-
//#region src/route-matcher.d.ts
|
|
33
|
-
interface RouteMatch {
|
|
34
|
-
routeKey: string;
|
|
35
|
-
route: RouteDefinition;
|
|
36
|
-
params: Record<string, string>;
|
|
37
|
-
}
|
|
38
|
-
type MatchResult = {
|
|
39
|
-
kind: 'matched';
|
|
40
|
-
match: RouteMatch;
|
|
41
|
-
} | {
|
|
42
|
-
kind: 'method-mismatch';
|
|
43
|
-
allowed: Method[];
|
|
44
|
-
} | {
|
|
45
|
-
kind: 'not-found';
|
|
46
|
-
};
|
|
47
|
-
declare const sortFlattenedRoutes: <T extends {
|
|
48
|
-
route: RouteDefinition;
|
|
49
|
-
}>(routes: T[]) => T[];
|
|
50
|
-
declare const matchRoute: (method: string, pathname: string, routes: Routes, basePath?: string) => MatchResult;
|
|
51
|
-
//#endregion
|
|
52
|
-
//#region src/plugin-server.d.ts
|
|
53
|
-
/**
|
|
54
|
-
* The plugin routes `assembleApi` stashed on the api. Empty without plugins, so
|
|
55
|
-
* an adapter can mount it unconditionally.
|
|
56
|
-
*/
|
|
57
|
-
declare const pluginRoutesOf: (api: unknown) => Routes;
|
|
58
|
-
/**
|
|
59
|
-
* Their handlers, keyed to match {@link pluginRoutesOf}.
|
|
60
|
-
*/
|
|
61
|
-
declare const pluginRouterOf: (api: unknown) => Record<string, unknown>;
|
|
62
|
-
/**
|
|
63
|
-
* What each plugin exports, for the adapter to pass into the pipeline as the
|
|
64
|
-
* handler args' `plugins`.
|
|
65
|
-
*/
|
|
66
|
-
declare const pluginExportsOf: (api: unknown) => Record<string, unknown>;
|
|
67
|
-
/**
|
|
68
|
-
* Run every plugin's `serve`. Deferred until the api object exists, because
|
|
69
|
-
* `serve` receives it.
|
|
70
|
-
*/
|
|
71
|
-
declare const resolvePluginServers: (plugins: ApiPlugins | undefined, api: unknown) => Record<string, {
|
|
72
|
-
router: Record<string, unknown>;
|
|
73
|
-
exports?: unknown;
|
|
74
|
-
}>;
|
|
75
|
-
//#endregion
|
|
76
|
-
//#region src/routes.d.ts
|
|
77
|
-
/**
|
|
78
|
-
* Define a group of routes under a tag. Pass the tag set declared with
|
|
79
|
-
* `k.tags` for completion on the group tag and route-level `tags`; the
|
|
80
|
-
* tag is stamped onto every route in the group.
|
|
81
|
-
*/
|
|
82
|
-
declare function tagRoutes<const T extends Routes<TagKeysOf<Set>>, Set extends TagSet>(tags: Set, tag: TagKeysOf<Set>, routes: T & PathParamsCheck<T>): T;
|
|
83
|
-
declare function tagRoutes<const T extends Routes<TagKeysOf<Set>>, Set extends TagSet>(tags: Set, routes: T & PathParamsCheck<T>): T;
|
|
84
|
-
declare function tagRoutes<const T extends Routes>(tag: string, routes: T & PathParamsCheck<T>): T;
|
|
85
|
-
declare function tagRoutes<const T extends Routes>(routes: T & PathParamsCheck<T>): T;
|
|
86
|
-
//#endregion
|
|
87
|
-
//#region src/response-error.d.ts
|
|
88
|
-
interface ResponseErrorPayload {
|
|
89
|
-
status: number;
|
|
90
|
-
body: unknown;
|
|
91
|
-
headers?: ResponseHeaders;
|
|
92
|
-
}
|
|
93
|
-
declare class ResponseError<R extends RouteDefinition = never> extends Error {
|
|
94
|
-
readonly status: number;
|
|
95
|
-
readonly body: unknown;
|
|
96
|
-
readonly headers?: ResponseHeaders;
|
|
97
|
-
constructor(response: [R] extends [never] ? ResponseErrorPayload : HandlerReturn<R>);
|
|
98
|
-
}
|
|
99
|
-
//#endregion
|
|
100
|
-
//#region src/server-surface.d.ts
|
|
101
|
-
/**
|
|
102
|
-
* The handler tree for an api or route group, typed against it, with an
|
|
103
|
-
* adapter's handler context substituted in. Adapter packages check their own
|
|
104
|
-
* surface against this; an app types a handler by writing it on the route.
|
|
105
|
-
*/
|
|
106
|
-
type ApiRouter<C, HandlerContext> = C extends ApiDefinition ? HandlersFromRoutes<RoutesOf<C>, HandlerContext & RequestContextValues<RequestContextOf<C>> & PluginArgs<ApiPluginsOf<C>> & JobsArg<JobsOf<C>>, SchemesOf<C>> : C extends Routes ? Router<C, HandlerContext> : never;
|
|
107
|
-
//#endregion
|
|
108
|
-
//#region src/adapter.d.ts
|
|
109
|
-
declare class ResponseValidationError extends Error {
|
|
110
|
-
readonly routeKey: string;
|
|
111
|
-
readonly status: number;
|
|
112
|
-
readonly issues: z.core.$ZodIssue[];
|
|
113
|
-
constructor(routeKey: string, status: number, issues: z.core.$ZodIssue[]);
|
|
114
|
-
}
|
|
115
|
-
declare const API_META: unique symbol;
|
|
116
|
-
declare const ROUTER_META: unique symbol;
|
|
117
|
-
declare const GUARDS_META: unique symbol;
|
|
118
|
-
declare const SCHEMES_META: unique symbol;
|
|
119
|
-
declare const GUARD_SCHEMA_META: unique symbol;
|
|
120
|
-
declare const REQUEST_CONTEXT_META: unique symbol;
|
|
121
|
-
declare const JOBS_META: unique symbol;
|
|
122
|
-
type ApiBrand = {
|
|
123
|
-
readonly [API_META]: true;
|
|
124
|
-
};
|
|
125
|
-
type ApiWithRouter<R extends Routes = Routes> = ApiBrand & {
|
|
126
|
-
/**
|
|
127
|
-
* The api's route tree. Read it here rather than off the api object: the
|
|
128
|
-
* api carries the parts that serve the routes, it is not the routes itself.
|
|
129
|
-
*/
|
|
130
|
-
readonly routes: R;
|
|
131
|
-
readonly [ROUTER_META]: Record<string, unknown>;
|
|
132
|
-
};
|
|
133
|
-
/**
|
|
134
|
-
* The marker a guard's `deny` returns. Distinguishes a denial
|
|
135
|
-
* from the context object a passing guard returns.
|
|
136
|
-
*/
|
|
137
|
-
declare const GUARD_DENY: unique symbol;
|
|
138
|
-
/**
|
|
139
|
-
* The result of `deny` inside a guard, short-circuits the
|
|
140
|
-
* request with an RFC 9457 problem details response of the given status.
|
|
141
|
-
*/
|
|
142
|
-
interface GuardDenial {
|
|
143
|
-
readonly [GUARD_DENY]: true;
|
|
144
|
-
status: number;
|
|
145
|
-
body: GuardDenialBody;
|
|
146
|
-
/**
|
|
147
|
-
* The `WWW-Authenticate` challenge RFC 9110 section 11.6.1 requires on a `401`.
|
|
148
|
-
*/
|
|
149
|
-
headers?: ResponseHeaders;
|
|
150
|
-
}
|
|
151
|
-
/**
|
|
152
|
-
* Reject the request from inside a guard. Extra `headers` ride on the
|
|
153
|
-
* response; a `www-authenticate` among them replaces the default challenge.
|
|
154
|
-
*/
|
|
155
|
-
type GuardDenialBody = {
|
|
156
|
-
detail: string;
|
|
157
|
-
} & Record<string, unknown>;
|
|
158
|
-
type GuardDeny<Body = {
|
|
159
|
-
detail: string;
|
|
160
|
-
}, Status extends number = number> = (denial: {
|
|
161
|
-
status: Status;
|
|
162
|
-
body: Body;
|
|
163
|
-
headers?: ResponseHeaders;
|
|
164
|
-
}) => GuardDenial;
|
|
165
|
-
/**
|
|
166
|
-
* Format a `Bearer` challenge for a `WWW-Authenticate` header, with auth
|
|
167
|
-
* parameters as RFC 9110 quoted strings (`error`, `scope`, `resource_metadata`,
|
|
168
|
-
* ...). `undefined` values are omitted; with none left, the bare scheme remains.
|
|
169
|
-
*/
|
|
170
|
-
declare const bearerChallenge: (parameters: Record<string, string | undefined>) => string;
|
|
171
|
-
/**
|
|
172
|
-
* The `deny` a guard for this identity receives. The challenge rides along with
|
|
173
|
-
* the denial, so a `401` cannot reach the wire without one.
|
|
174
|
-
*/
|
|
175
|
-
declare const guardDenyFor: (scheme: SecurityScheme | undefined) => GuardDeny<GuardDenialBody>;
|
|
176
|
-
declare const isGuardDenial: (value: unknown) => value is GuardDenial;
|
|
177
|
-
/**
|
|
178
|
-
* The runtime behavior of a guard. It receives one object: the adapter's handler
|
|
179
|
-
* context (e.g. `req`/`res`) plus the credential the identity's method extracted
|
|
180
|
-
* from the request (or `null` if absent), a `deny` helper, and the request
|
|
181
|
-
* context resolved for this request, absent
|
|
182
|
-
* when the api declares none. It returns the context the scheme provides
|
|
183
|
-
* (nested under `auth`, keyed by the identity's name in the handler args) or
|
|
184
|
-
* `deny(...)` to reject.
|
|
185
|
-
*/
|
|
186
|
-
type GuardRun<HandlerContext = unknown> = (args: HandlerContext & Credential & {
|
|
187
|
-
params: Record<string, string>;
|
|
188
|
-
deny: GuardDeny;
|
|
189
|
-
requestContext?: Record<string, unknown>;
|
|
190
|
-
}) => Promise<Record<string, unknown> | GuardDenial | void> | Record<string, unknown> | GuardDenial | void;
|
|
191
|
-
/**
|
|
192
|
-
* Guards keyed by the security scheme name they satisfy. A route's resolved
|
|
193
|
-
* `security` selects which guards run before its handler.
|
|
194
|
-
*/
|
|
195
|
-
type GuardMap<HandlerContext = unknown> = Record<string, GuardRun<HandlerContext>>;
|
|
196
|
-
/**
|
|
197
|
-
* The runtime behavior of a request context resolver. It runs on every route
|
|
198
|
-
* before the guards, receives the handler context plus the matched route's
|
|
199
|
-
* `params`, and returns the value the guards and handlers read under the
|
|
200
|
-
* context's name. It never denies a request.
|
|
201
|
-
*/
|
|
202
|
-
type RequestContextRun<HandlerContext = unknown> = (args: HandlerContext & {
|
|
203
|
-
params: Record<string, string>;
|
|
204
|
-
headers: Record<string, string | string[] | undefined>;
|
|
205
|
-
}) => Promise<unknown> | unknown;
|
|
206
|
-
/**
|
|
207
|
-
* The api's own definition, for plugins needing more than the routes.
|
|
208
|
-
*/
|
|
209
|
-
declare const contractOf: <C = unknown>(api: unknown) => C;
|
|
210
|
-
/**
|
|
211
|
-
* What kizuna puts in handler args. Must agree with the spread in `runPipeline`.
|
|
212
|
-
*/
|
|
213
|
-
declare const HANDLER_ARG_KEYS: readonly ["params", "query", "body", "headers", "throwError", "auth", "requestContext", "plugins"];
|
|
214
|
-
/**
|
|
215
|
-
* The adapter's own context, with kizuna's arguments removed.
|
|
216
|
-
*/
|
|
217
|
-
declare const adapterContextOf: (args: Record<string, unknown>) => Record<string, unknown>;
|
|
218
|
-
/**
|
|
219
|
-
* Request context resolvers keyed by the name they were declared under in `defineConfig()`.
|
|
220
|
-
*/
|
|
221
|
-
type RequestContextMap<HandlerContext = unknown> = Record<string, RequestContextRun<HandlerContext>>;
|
|
222
|
-
interface ApiParts {
|
|
223
|
-
router: unknown;
|
|
224
|
-
guards?: unknown;
|
|
225
|
-
requestContext?: unknown;
|
|
226
|
-
}
|
|
227
|
-
/**
|
|
228
|
-
* Brand an api's routes with the parts that serve them, for the adapter to read back when mounting.
|
|
229
|
-
*/
|
|
230
|
-
declare const assembleApi: <const R extends Routes>(contract: {
|
|
231
|
-
routes: R;
|
|
232
|
-
securitySchemes?: Record<string, SecurityScheme>;
|
|
233
|
-
guardSchema?: z.ZodType;
|
|
234
|
-
plugins?: ApiPlugins;
|
|
235
|
-
}, parts: ApiParts) => ApiWithRouter<R>;
|
|
236
|
-
/**
|
|
237
|
-
* The endpoints jobs are served on, in the {@link Routes} shape the request
|
|
238
|
-
* pipeline takes.
|
|
239
|
-
*/
|
|
240
|
-
declare const jobRoutes: (meta: JobsMeta) => Routes;
|
|
241
|
-
/**
|
|
242
|
-
* Their handlers, in the {@link Router} shape the request pipeline takes.
|
|
243
|
-
*/
|
|
244
|
-
declare const jobRouter: <HandlerContext>(meta: JobsMeta) => Router<Routes, HandlerContext>;
|
|
245
|
-
/**
|
|
246
|
-
* Type-only key under which an {@link Adapter} carries the handler context its
|
|
247
|
-
* framework hands to every handler. Never present at runtime.
|
|
248
|
-
*/
|
|
249
|
-
declare const ADAPTER_CONTEXT: unique symbol;
|
|
250
|
-
/**
|
|
251
|
-
* What serves an API on one framework. Name it under `adapter` in
|
|
252
|
-
* `defineConfig`, and the `api` you get back mounts onto that framework's app,
|
|
253
|
-
* hands every handler that framework's own request, and types both.
|
|
254
|
-
*
|
|
255
|
-
* @example
|
|
256
|
-
* // kizuna.config.ts
|
|
257
|
-
* export default defineConfig({
|
|
258
|
-
* adapter: expressAdapter(),
|
|
259
|
-
* routes,
|
|
260
|
-
* });
|
|
261
|
-
*
|
|
262
|
-
* // src/index.ts
|
|
263
|
-
* kizuna.api.mount(app);
|
|
264
|
-
*/
|
|
265
|
-
interface Adapter<HandlerContext = unknown, MountArgs extends readonly unknown[] = readonly unknown[], Mounted = unknown> {
|
|
266
|
-
/**
|
|
267
|
-
* The framework this serves, for error messages.
|
|
268
|
-
*/
|
|
269
|
-
readonly name: string;
|
|
270
|
-
/**
|
|
271
|
-
* Register every route of an api on the framework. What it takes after the
|
|
272
|
-
* api, and what it hands back, is the framework's own.
|
|
273
|
-
*/
|
|
274
|
-
readonly mount: (api: ApiWithRouter, ...args: MountArgs) => Mounted;
|
|
275
|
-
readonly [ADAPTER_CONTEXT]?: HandlerContext;
|
|
276
|
-
}
|
|
277
|
-
/**
|
|
278
|
-
* Any adapter, whatever its framework takes. A `mount` reads its own arguments,
|
|
279
|
-
* so a concrete adapter is not assignable to a widened one; this stands in
|
|
280
|
-
* wherever an adapter is a constraint rather than a value.
|
|
281
|
-
*/
|
|
282
|
-
type AnyAdapter = Adapter<any, any, any>;
|
|
283
|
-
/**
|
|
284
|
-
* The handler context an adapter hands to every handler, `{}` when none is
|
|
285
|
-
* declared.
|
|
286
|
-
*/
|
|
287
|
-
type HandlerContextOf<A> = A extends Adapter<infer HandlerContext, any, any> ? HandlerContext : {};
|
|
288
|
-
/**
|
|
289
|
-
* What an adapter's `mount` takes after the api.
|
|
290
|
-
*/
|
|
291
|
-
type MountArgsOf<A> = A extends Adapter<any, infer MountArgs, any> ? MountArgs : readonly unknown[];
|
|
292
|
-
/**
|
|
293
|
-
* What an adapter's `mount` hands back.
|
|
294
|
-
*/
|
|
295
|
-
type MountedOf<A> = A extends Adapter<any, any, infer Mounted> ? Mounted : never;
|
|
296
|
-
interface ServerOptions {
|
|
297
|
-
/**
|
|
298
|
-
* Carries a queued job to whatever runs it. Without one, `queue` runs the job
|
|
299
|
-
* in this process and it is lost on a crash.
|
|
300
|
-
*/
|
|
301
|
-
jobTransport?: JobTransport;
|
|
302
|
-
onJobError?: JobErrorHandler;
|
|
303
|
-
}
|
|
304
|
-
/**
|
|
305
|
-
* Warn when a job asks for something its transport will drop.
|
|
306
|
-
*/
|
|
307
|
-
declare const warnUnsupportedJobOptions: (jobs: Jobs | undefined, transport: JobTransport | undefined, logger?: Pick<Console, "warn">) => void;
|
|
308
|
-
/**
|
|
309
|
-
* What `JOBS_META` carries: the api's jobs, the handler for each, and how
|
|
310
|
-
* this deployment runs them.
|
|
311
|
-
*/
|
|
312
|
-
interface JobsMeta extends JobRunnerOptions {
|
|
313
|
-
jobs: Jobs;
|
|
314
|
-
handlers: Record<string, unknown>;
|
|
315
|
-
config?: JobsConfig;
|
|
316
|
-
}
|
|
317
|
-
/**
|
|
318
|
-
* Namespaced so it cannot collide with a route key of your own.
|
|
319
|
-
*/
|
|
320
|
-
declare const DISPATCH_ROUTE_KEY = "kizuna:dispatch";
|
|
321
|
-
/**
|
|
322
|
-
* The endpoint a scheduler ticks to run whichever jobs are due.
|
|
323
|
-
*/
|
|
324
|
-
declare const dispatchRoute: (meta: JobsMeta) => RouteDefinition;
|
|
325
|
-
/**
|
|
326
|
-
* Runs each due job rather than queueing it, so the transport never sees a tick.
|
|
327
|
-
*/
|
|
328
|
-
declare const dispatchHandler: <HandlerContext>(meta: JobsMeta) => RouteHandler<RouteDefinition, HandlerContext>;
|
|
329
|
-
/**
|
|
330
|
-
* Namespaced so it cannot collide with a route key of your own.
|
|
331
|
-
*/
|
|
332
|
-
declare const RUN_ROUTE_KEY = "kizuna:run";
|
|
333
|
-
/**
|
|
334
|
-
* The endpoint a queue delivers one job to, naming it in the body.
|
|
335
|
-
*/
|
|
336
|
-
declare const runRoute: (meta: JobsMeta) => RouteDefinition;
|
|
337
|
-
/**
|
|
338
|
-
* Answers with whatever the job answered, so a queue reads its own retry
|
|
339
|
-
* contract off the status.
|
|
340
|
-
*/
|
|
341
|
-
declare const runHandler: <HandlerContext>(meta: JobsMeta) => RouteHandler<RouteDefinition, HandlerContext>;
|
|
342
|
-
declare const jobRunnerFrom: (meta: JobsMeta | undefined) => JobRunner<Jobs> | undefined;
|
|
343
|
-
/**
|
|
344
|
-
* The dotted keys of the jobs a handler was actually bound to. A job without one
|
|
345
|
-
* cannot run, so nothing should schedule or subscribe to it.
|
|
346
|
-
*/
|
|
347
|
-
declare const boundJobKeys: (meta: JobsMeta | undefined) => Set<string>;
|
|
348
|
-
type RouteMatcher = (method: string, path: string, routes: Routes, basePath?: string) => MatchResult;
|
|
349
|
-
interface AdapterRequest<NativeRequest> {
|
|
350
|
-
request: NativeRequest;
|
|
351
|
-
method: string;
|
|
352
|
-
/**
|
|
353
|
-
* - `core-match`: core matches the path against the routes (Next-style catch-all routing).
|
|
354
|
-
* - `pre-resolved`: adapter has already routed the request and tells core which route was matched (Express-style per-route registration).
|
|
355
|
-
*/
|
|
356
|
-
resolution: {
|
|
357
|
-
kind: 'core-match';
|
|
358
|
-
path: string;
|
|
359
|
-
} | {
|
|
360
|
-
kind: 'pre-resolved';
|
|
361
|
-
routeKey: string;
|
|
362
|
-
route: RouteDefinition;
|
|
363
|
-
params: Record<string, string>;
|
|
364
|
-
};
|
|
365
|
-
query: unknown;
|
|
366
|
-
headers: unknown;
|
|
367
|
-
readBody: (route: RouteDefinition) => Promise<unknown> | unknown;
|
|
368
|
-
}
|
|
369
|
-
/**
|
|
370
|
-
* Outcome of `runPipeline`. The adapter's `respond` translates this to a native response.
|
|
371
|
-
*
|
|
372
|
-
* Note: `raw-response` is an escape hatch for `onError` overrides, its `response` is
|
|
373
|
-
* cast back to the adapter's `NativeResponse` by `respond`.
|
|
374
|
-
*/
|
|
375
|
-
type AdapterResult = {
|
|
376
|
-
kind: 'not-found';
|
|
377
|
-
} | {
|
|
378
|
-
kind: 'method-not-allowed';
|
|
379
|
-
allowed: Method[];
|
|
380
|
-
} | {
|
|
381
|
-
kind: 'unsupported-media-type';
|
|
382
|
-
expected: string;
|
|
383
|
-
received: string;
|
|
384
|
-
headers?: ResponseHeaders;
|
|
385
|
-
} | {
|
|
386
|
-
kind: 'invalid-body';
|
|
387
|
-
detail: string;
|
|
388
|
-
headers?: ResponseHeaders;
|
|
389
|
-
} | {
|
|
390
|
-
kind: 'validation-failed';
|
|
391
|
-
stage: ValidationStage;
|
|
392
|
-
detail: string;
|
|
393
|
-
issues: z.core.$ZodIssue[];
|
|
394
|
-
headers?: ResponseHeaders;
|
|
395
|
-
} | {
|
|
396
|
-
kind: 'no-handler';
|
|
397
|
-
routeKey: string;
|
|
398
|
-
headers?: ResponseHeaders;
|
|
399
|
-
} | {
|
|
400
|
-
kind: 'guard-denied';
|
|
401
|
-
status: number;
|
|
402
|
-
body: GuardDenialBody;
|
|
403
|
-
/**
|
|
404
|
-
* The `WWW-Authenticate` challenge RFC 9110 requires on a `401`, or
|
|
405
|
-
* the `insufficient_scope` one RFC 6750 sends on a `403`.
|
|
406
|
-
*/
|
|
407
|
-
headers?: ResponseHeaders;
|
|
408
|
-
} | {
|
|
409
|
-
kind: 'handler-error';
|
|
410
|
-
routeKey: string;
|
|
411
|
-
route: RouteDefinition;
|
|
412
|
-
error: unknown;
|
|
413
|
-
headers?: ResponseHeaders;
|
|
414
|
-
} | {
|
|
415
|
-
kind: 'success';
|
|
416
|
-
routeKey: string;
|
|
417
|
-
route: RouteDefinition;
|
|
418
|
-
status: number;
|
|
419
|
-
body: unknown;
|
|
420
|
-
headers?: ResponseHeaders;
|
|
421
|
-
} | {
|
|
422
|
-
kind: 'not-acceptable';
|
|
423
|
-
headers?: ResponseHeaders;
|
|
424
|
-
} | {
|
|
425
|
-
kind: 'raw-response';
|
|
426
|
-
response: unknown;
|
|
427
|
-
};
|
|
428
|
-
interface AdapterDefinition<NativeRequest, NativeResponse, HandlerContext, ResponseContext = Record<string, never>> {
|
|
429
|
-
buildHandlerContext: (request: AdapterRequest<NativeRequest>, context: ResponseContext) => HandlerContext | Promise<HandlerContext>;
|
|
430
|
-
respond: (result: AdapterResult, context: ResponseContext) => NativeResponse | Promise<NativeResponse>;
|
|
431
|
-
/**
|
|
432
|
-
* Return an `AdapterResult` to override the default `handler-error` outcome; return `void` to let it pass through.
|
|
433
|
-
*/
|
|
434
|
-
onError?: (error: unknown, request: AdapterRequest<NativeRequest>) => AdapterResult | void | Promise<AdapterResult | void>;
|
|
435
|
-
matcher?: RouteMatcher;
|
|
436
|
-
}
|
|
437
|
-
interface HandleArgs<NativeRequest, HandlerContext, ResponseContext, TRoutes extends Routes> {
|
|
438
|
-
routes: TRoutes;
|
|
439
|
-
router: Router<TRoutes, HandlerContext>;
|
|
440
|
-
request: AdapterRequest<NativeRequest>;
|
|
441
|
-
responseContext: ResponseContext;
|
|
442
|
-
/**
|
|
443
|
-
* Guards keyed by security scheme name. The matched route's resolved
|
|
444
|
-
* `security` selects which run before its handler; their returned context is
|
|
445
|
-
* merged into the handler args.
|
|
446
|
-
*/
|
|
447
|
-
guards?: GuardMap<HandlerContext>;
|
|
448
|
-
/**
|
|
449
|
-
* The api's identities keyed by name. The runtime extracts each required
|
|
450
|
-
* scheme's credential from the request (per its declared location) and passes
|
|
451
|
-
* it to that scheme's guard.
|
|
452
|
-
*/
|
|
453
|
-
schemes?: Record<string, SecurityScheme>;
|
|
454
|
-
/**
|
|
455
|
-
* What each plugin exports, reaching handlers under `plugins`.
|
|
456
|
-
*/
|
|
457
|
-
pluginExports?: Record<string, unknown>;
|
|
458
|
-
/**
|
|
459
|
-
* Request context resolvers keyed by name. Each runs on every route before
|
|
460
|
-
* the guards; its value lands in the guard and handler args under `requestContext`, keyed by its name.
|
|
461
|
-
*/
|
|
462
|
-
requestContext?: RequestContextMap<HandlerContext>;
|
|
463
|
-
/**
|
|
464
|
-
* The api's jobs bound to their handlers. Every handler receives it as
|
|
465
|
-
* `jobs`, so a route can run a job in process without an HTTP hop.
|
|
466
|
-
*/
|
|
467
|
-
jobs?: JobRunner<Jobs>;
|
|
468
|
-
basePath?: string;
|
|
469
|
-
responseValidation?: boolean;
|
|
470
|
-
}
|
|
471
|
-
/**
|
|
472
|
-
* Read a raw header value as a single string: the first entry of an array
|
|
473
|
-
* header, `undefined` when absent. For guards and request context resolvers on
|
|
474
|
-
* adapters that expose raw header records.
|
|
475
|
-
*/
|
|
476
|
-
declare const getHeaderValue: (value: unknown) => string | undefined;
|
|
477
|
-
/**
|
|
478
|
-
* Extract the credential an identity's authentication method expects from the
|
|
479
|
-
* request, labelled with its scheme kind: the value of the named
|
|
480
|
-
* header/query/cookie for `apiKey`, the decoded `username`/`password` for HTTP
|
|
481
|
-
* `basic`, or the bearer token for everything else. The credential is `null`
|
|
482
|
-
* when it is absent or malformed.
|
|
483
|
-
*/
|
|
484
|
-
declare const extractCredential: (scheme: SecurityScheme, request: AdapterRequest<unknown>) => Credential | NoCredential;
|
|
485
|
-
/**
|
|
486
|
-
* The request pipeline `createAdapter` builds: what matches a request to a
|
|
487
|
-
* route, runs the guards and the handler, and hands the result back to the
|
|
488
|
-
* framework.
|
|
489
|
-
*/
|
|
490
|
-
interface RequestPipeline<NativeRequest, NativeResponse, HandlerContext, ResponseContext> {
|
|
491
|
-
handle: <T extends Routes>(args: HandleArgs<NativeRequest, HandlerContext, ResponseContext, T>) => Promise<NativeResponse>;
|
|
492
|
-
eachRoute: <T extends Routes>(routes: T, router: Router<T, HandlerContext>) => Iterable<{
|
|
493
|
-
routeKey: string;
|
|
494
|
-
route: RouteDefinition;
|
|
495
|
-
handler: RouteHandler<RouteDefinition, HandlerContext>;
|
|
496
|
-
}>;
|
|
497
|
-
}
|
|
498
|
-
/**
|
|
499
|
-
* The handler tree a routes tree already carries, mirroring its shape so
|
|
500
|
-
* everything that walks a router by dotted key finds the route's own handler.
|
|
501
|
-
*/
|
|
502
|
-
declare const routerFromRoutes: (routes: Routes) => Record<string, unknown>;
|
|
503
|
-
declare const createAdapter: <NativeRequest, NativeResponse, HandlerContext, ResponseContext = Record<string, never>>(definition: AdapterDefinition<NativeRequest, NativeResponse, HandlerContext, ResponseContext>) => RequestPipeline<NativeRequest, NativeResponse, HandlerContext, ResponseContext>;
|
|
504
|
-
/**
|
|
505
|
-
* Decides the bytes that go on the wire for an error (status >= 400). The default emits the
|
|
506
|
-
* canonical RFC 9457 Problem Details as `application/problem+json`.
|
|
507
|
-
*
|
|
508
|
-
* **Most migrations don't need this.** Carrying your existing fields as Problem Details
|
|
509
|
-
* extension members keeps a single body valid for both old and new clients.
|
|
510
|
-
*
|
|
511
|
-
* **Reach for it only when** an older client needs a different content type (plain
|
|
512
|
-
* `application/json`) or a structurally different body. It receives the request, so if you
|
|
513
|
-
* can tell clients apart (a version header, `Accept`, …) you can serve the legacy shape to
|
|
514
|
-
* old clients and Problem Details to new ones during a transition, then delete it.
|
|
515
|
-
*/
|
|
516
|
-
type ErrorFormatter<NativeRequest = unknown> = (problem: ProblemDetails & Record<string, unknown>, context: {
|
|
517
|
-
status: number;
|
|
518
|
-
request: NativeRequest;
|
|
519
|
-
}) => {
|
|
520
|
-
contentType: string;
|
|
521
|
-
body: unknown;
|
|
522
|
-
};
|
|
523
|
-
/**
|
|
524
|
-
* Maps an `AdapterResult` to `{ status, headers, body }` using Kizuna's default
|
|
525
|
-
* JSON conventions (e.g. 405 with an `Allow` header, 400 with `{ detail, errors }`
|
|
526
|
-
* for validation failures). Adapters that speak JSON delegate `respond` to this
|
|
527
|
-
* instead of writing the switch by hand.
|
|
528
|
-
*
|
|
529
|
-
* Every error (status >= 400) is an RFC 9457 Problem Details object run through
|
|
530
|
-
* `formatError`, there is no custom-error-shape passthrough. Pass an `ErrorFormatter`
|
|
531
|
-
* to reshape the wire bytes for migration; the canonical problem is unchanged.
|
|
532
|
-
*
|
|
533
|
-
* `raw-response` is excluded, it carries a framework-specific `NativeResponse`
|
|
534
|
-
* the adapter must return directly, so handle that case before calling this.
|
|
535
|
-
*
|
|
536
|
-
* Pass `requestMethod` where kizuna's rendering is the last stop before the
|
|
537
|
-
* wire: a HEAD request then keeps GET's status and headers, gains a
|
|
538
|
-
* `Content-Length`, and loses the content (RFC 9110 §9.3.2). Leave it
|
|
539
|
-
* unset where the framework discards HEAD content itself (Express, Fastify, Hono).
|
|
540
|
-
*/
|
|
541
|
-
interface RenderedResult {
|
|
542
|
-
status: number;
|
|
543
|
-
headers: ResponseHeaders;
|
|
544
|
-
body: unknown;
|
|
545
|
-
raw?: boolean;
|
|
546
|
-
/**
|
|
547
|
-
* A streamed response carries this in place of `body`. Check it first.
|
|
548
|
-
*/
|
|
549
|
-
stream?: (options: EncodeStreamOptions) => ReadableStream<Uint8Array>;
|
|
550
|
-
}
|
|
551
|
-
declare const renderJsonResult: (result: Exclude<AdapterResult, {
|
|
552
|
-
kind: "raw-response";
|
|
553
|
-
}>, formatError?: ErrorFormatter, request?: unknown, requestMethod?: string) => RenderedResult;
|
|
554
|
-
/**
|
|
555
|
-
* Content-type-aware body parser for Web Fetch `Request`.
|
|
556
|
-
*
|
|
557
|
-
* Reusable across any Fetch-based adapter.
|
|
558
|
-
*
|
|
559
|
-
* */
|
|
560
|
-
declare const parseFetchBody: (request: Request, route: RouteDefinition) => Promise<unknown>;
|
|
561
|
-
declare const headersToObject: (headers: Headers) => ResponseHeaders;
|
|
562
|
-
//#endregion
|
|
563
|
-
export { jobRunnerFrom as $, RenderedResult as A, bearerChallenge as B, JOBS_META as C, REQUEST_CONTEXT_META as D, MountedOf as E, RouteMatcher as F, dispatchRoute as G, contractOf as H, SCHEMES_META as I, guardDenyFor as J, extractCredential as K, ServerOptions as L, RequestContextRun as M, RequestPipeline as N, ROUTER_META as O, ResponseValidationError as P, jobRoutes as Q, adapterContextOf as R, HandlerContextOf as S, MountArgsOf as T, createAdapter as U, boundJobKeys as V, dispatchHandler as W, isGuardDenial as X, headersToObject as Y, jobRouter as Z, GuardDeny as _, AccessCheckInput as _t, AdapterRequest as a, warnUnsupportedJobOptions as at, HANDLER_ARG_KEYS as b, withPermissions as bt, ApiBrand as c, tagRoutes as ct, DISPATCH_ROUTE_KEY as d, pluginRoutesOf as dt, parseFetchBody as et, ErrorFormatter as f, resolvePluginServers as ft, GuardDenialBody as g, sortFlattenedRoutes as gt, GuardDenial as h, matchRoute as ht, AdapterDefinition as i, runRoute as it, RequestContextMap as j, RUN_ROUTE_KEY as k, ApiParts as l, pluginExportsOf as lt, GUARD_SCHEMA_META as m, RouteMatch as mt, API_META as n, routerFromRoutes as nt, AdapterResult as o, ApiRouter as ot, GUARDS_META as p, MatchResult as pt, getHeaderValue as q, Adapter as r, runHandler as rt, AnyAdapter as s, ResponseError as st, ADAPTER_CONTEXT as t, renderJsonResult as tt, ApiWithRouter as u, pluginRouterOf as ut, GuardMap as v, insufficientScope as vt, JobsMeta as w, HandleArgs as x, GuardRun as y, requiresDenial as yt, assembleApi as z };
|