Writing a plugin

A plugin is a function that gets a scope and its options. Everything a plugin can do is the API of the app: routes, hooks, decorations, onOperation. This page is about what matters when the plugin is for other people. The hooks page has the basics.

Shared or scopedCopy Anchor Link

import { plugin } from "@vxnsin/inkan";

const admin = plugin((app) => {                       // scoped: a scope of its own
  app.onRequest(requireAdmin);
  app.get("/stats", () => stats());
});

const poweredBy = plugin((app) => {                    // shared: acts on the scope around it
  app.onSend((ctx, answer) => void (answer.headers["x-powered-by"] = "tea"));
}, { shared: true, name: "powered-by" });

app.register(admin, {}, { prefix: "/admin" });
app.register(poweredBy);

A scoped plugin gets a scope inside the one it is registered in. Its hooks and decorations reach its own routes and nothing outside. Right for a plugin that brings routes: an admin area, a webhook receiver.

A shared plugin works in the scope it is registered in. Registered on the app, its hooks run for every route; registered inside another plugin, for that plugin's routes. Right for a plugin whose point is to act on the routes around it: a rate limit, sessions, headers. rateLimit, compress and every package under More middleware are shared.

dev and prefixCopy Anchor Link

const debug = plugin((scope) => {
  if (!scope.dev) return;                                   // nothing in production
  scope.get("/_debug", () => ({ mountedAt: scope.prefix || "/" }));
});

Every scope says, read-only, whether the app runs in development (scope.dev, the app's dev option) and under which path prefix it was registered (scope.prefix: "" for the app, "/admin" for register(plugin, options, { prefix: "/admin" })). A plugin that sets a cookie path or builds a link from its own routes reads prefix instead of asking for it again, and puts paths together with joinPath(scope.prefix, "/login"), which leaves one slash between the parts.

The second argument of register is what the plugin is handed, the third where it is mounted: a plugin's options never need a prefix of their own.

decorate or decorateRequestCopy Anchor Link

app.decorate("db", pool);                                          // one value, for every request
app.decorateRequest("user", (ctx) => sessions.get(ctx.cookies.sid)); // made per request

decorate puts one value on the context's prototype: it costs nothing per request. Use it for things every request shares: a pool, a client, a config.

decorateRequest puts a getter there instead. init runs the first time a request reads ctx.user, and the value is kept on that context, so it runs at most once per request, and never for a request that does not ask. Hooks see it too, and setting ctx.user = … in a hook wins over init. init can read other decorations. Both refuse a name the context already has, so a plugin cannot hide ctx.params or another plugin's decoration.

Async decorationsCopy Anchor Link

An init that returns a promise makes ctx.user that promise, typed Promise<User>: made once however often it is read, never for a request that does not read it, and a problem it throws is the answer.

app.decorateRequest("user", async (ctx) => {
  const user = await sessions.load(ctx.cookies.sid);
  if (!user) throw problem(401, "unauthorized");
  return user;
}, { resolve: "preHandler", when: (route) => route.security.length > 0 });

app.get("/me", { security: { apiKey: "sid", in: "cookie" } }, ({ user }) => user.name); // the value, not a promise

With resolve: "preHandler" the promise is awaited after the input is checked and before the preHandler hooks, so they and the handler see the value itself, typed without the promise. That loads it for every request of the routes it covers, read or not, so when picks them, asked once per route with its ctx.route view. Reading it on a route when leaves out throws, instead of handing over a promise typed as the value; onRequest hooks, which run before it is awaited, still get the promise. Apps that do not use it pay nothing for it.

Typed decorations out of shared pluginsCopy Anchor Link

A shared plugin that returns its scope hands on the types of what it decorated. After register, the handlers see them:

type User = { id: number; roles: string[] };

const auth = plugin(
  (app, o: { header: string }) =>
    app.decorateRequest("user", (ctx): User | undefined => {
      const id = ctx.headers[o.header];
      return id ? { id: Number(id), roles: ["admin"] } : undefined;
    }),
  { shared: true, name: "auth" },
);

inkan()
  .register(auth, { header: "x-user" })
  .get("/me", (ctx) => ({ id: ctx.user?.id ?? null })); // ctx.user: User | undefined

Type the options on the parameter (o: { header: string }), not as a type argument, or there is nothing left to infer from. An async plugin works the same: return the scope at the end. A scoped plugin keeps its decorations to itself, in the types too.

For a plugin written in JavaScript, or one that does not return its scope, say what it adds in the type: Plugin<Options, Needs, Adds>.

import type { Plugin } from "@vxnsin/inkan";

export declare function session(options: { secret: string }): Plugin<{}, {}, { session: Session }>;

Routes out of plugins, in the typed clientCopy Anchor Link

A plugin made with plugin(), shared or not, that returns its scope hands on the routes it defined in that chain. After register, the typed client knows them, under the prefix they were registered with:

const auth = plugin((app) =>
  app
    .post("/login", { body: t.object({ name: t.string(), password: t.string() }), response: { 200: t.object({ ok: t.boolean() }) } }, login)
    .post("/logout", {}, logout),
);

export const api = inkan().register(auth, {}, { prefix: "/auth" }).get("/teas", listTeas);

// web.ts
const shop = client<typeof api>("https://shop.example");
await shop.post("/auth/login", { body: { name: "ana", password } }); // typed, body and answers

Prefixes add up through plugins that register others. A plain function passed to register hands no types on; neither do routes added one statement at a time. For a plugin written in JavaScript, the fourth type parameter says which routes it brings: Plugin<Options, Needs, Adds, Routes>.

ctx.route: security and metaCopy Anchor Link

Every hook sees the route that matched as ctx.route: its method, its path as written (/teas/:id), the security it asks for (its own or its group's; empty for none), and its meta. The object is made once per route, before the first request.

meta is free-form, for plugins to read:

app.get("/reports", { security: "bearer", meta: { auth: { roles: ["admin"] } } }, list);

app.onRequest((ctx) => {
  const roles = ctx.route?.meta.auth?.roles ?? [];
  if (roles.length && !roles.some((r) => ctx.user?.roles.includes(r))) throw problem(403, "forbidden");
});

A plugin names what it reads by extending the exported RouteMeta interface. Then a wrong shape does not compile, and the editor suggests the field:

declare module "@vxnsin/inkan" {
  interface RouteMeta {
    auth?: { roles: string[] };
  }
}

RouteMeta takes symbol keys as well, so a plugin can keep a key to itself: one only it can write, which no route spec can set by accident.

export const INTERNAL = Symbol("my-plugin");

declare module "@vxnsin/inkan" {
  interface RouteMeta {
    [INTERNAL]?: boolean;
  }
}

A hook that needs a header no route lists reads ctx.rawHeaders: ctx.headers is cut down to a route's header schema, rawHeaders is the request's as it arrived (read it, do not change it). ctx.secure and ctx.protocol say whether the request came over TLS, the proxies' word included under trustProxy.

onOperation(): adding to OpenAPICopy Anchor Link

A plugin that adds a header or an answer should say so in the document. onOperation runs for every route of its scope when the document is written, never per request:

app.onOperation((op, route, components) => {
  if (!route.security?.includes("bearer")) return;
  components.securitySchemes!.bearer!.bearerFormat = "JWT";
  op.responses["403"] ??= { description: "The token does not allow this" };
  (op.parameters ??= []).push({ name: "x-tenant", in: "header", required: false, schema: { type: "string" } });
});

op is the OpenAPI operation, components the document's components: securitySchemes already holds the schemes the routes ask for, and new sections (responses, parameters) are kept. route is an OperationRoute: the frozen ctx.route view (method, path, security, meta) plus the spec the route was written with, read-only; change the operation instead. Outer scopes' hooks run first. A hook added after the document was written still reaches it: it is written again.

The fourth argument, ref(schema, name?), puts a t.* schema into the document once, under components.schemas, and returns { $ref } to it, as a route's named schemas are. An unnamed schema needs name:

import { t } from "@vxnsin/inkan";

const Locked = t.object({ until: t.string() });

app.onOperation((op, route, components, ref) => {
  if (!route.meta.locks) return;
  op.responses["423"] ??= {
    description: "Locked",
    content: { "application/json": { schema: ref(Locked, "Locked") } },
  };
});

Hook order: order: "last"Copy Anchor Link

Hooks run outermost scope first, in the order they were added. A hook that has to come after all the others of its kind says so with { order: "last" }, which every hook takes. An onSend hook that changes the bytes of the body is the usual case:

app.onSend((ctx, answer) => sign(answer), { order: "last" });

Last hooks run after every other hook of their kind on the route, again outermost first. compress is one, so a hook that reads the body (an ETag, a signature) sees it before it is packed, wherever either was registered.

around(): wrapping the handlerCopy Anchor Link

const timing = plugin((scope) => {
  scope.around(async (ctx, next) => {
    const t0 = performance.now();
    await next();
    ctx.header("server-timing", `app;dur=${(performance.now() - t0).toFixed(1)}`);
  });
}, { shared: true, name: "timing" });

around(fn) wraps the handler of every route of the scope and the scopes inside it, those defined before the call too, where a route's own middleware runs: after the input is checked and the preHandler hooks. await next() runs the rest. Outer scopes' around wrap inner ones', and each is joined into the route once, before the first request. Right for timing, a transaction around the handler, or an AsyncLocalStorage of your own. Experimental.

stateKey: a slot of your own in ctx.stateCopy Anchor Link

import { stateKey } from "@vxnsin/inkan";

export const tenant = stateKey<Tenant>("tenant");

const tenants = plugin((scope) => {
  scope.onRequest((ctx) => tenant.set(ctx, lookUp(ctx.headers.host)));
}, { shared: true, name: "tenants" });

app.get("/me", (ctx) => tenant.get(ctx)?.name);

A string key in ctx.state is anybody's: two plugins that pick "tenant" overwrite each other. stateKey<T>(name) keeps the value under a symbol of its own, typed, and the plugin exports the key to whoever should read it. Experimental.

The pages inkan serves itselfCopy Anchor Link

/docs, /openapi.json and /_inkan are answered before any hook runs, so no plugin's hooks (secure headers, auth, a rate limit) apply to them. To put hooks on one, turn it off (docs: false, openapi: false, inspector: false) and serve it from a route of your own.

Behind a proxyCopy Anchor Link

ctx.ip is the socket's address unless the app trusts its proxies. A plugin that keys on the client, like rateLimit, reads ctx.ip and gets the right one once the app says trustProxy (see App options). Do not read x-forwarded-for yourself: anyone can send it.

Cookies outside a contextCopy Anchor Link

parseCookies(header) and serializeCookie(name, value, options) are exported for plugins that read or write cookies on their own, with the same defaults as ctx.setCookie (Path=/, HttpOnly, SameSite=Lax).

Publishing itCopy Anchor Link

Name it inkan-<name>, keep inkan a peer dependency, and add it to the list: see Publish a plugin. Everything already out there, official and community, is on Hanko.