Web 標準の Request / Response だけで書かれた、小さな Web フレームワーク。
Bun・Deno・Node.js・Cloudflare Workers・ブラウザ(Service Worker)で、同じコードが動きます。
import { createApp } from "@senrijs/senri";
import { devtools } from "@senrijs/senri/dev";
import { serve } from "@senrijs/senri/serve";
const app = createApp({ dev: devtools() }); // 開発中の親切なエラーページなど。NODE_ENV=production では何もしない
app.get("/hello", () => "こんにちは!"); // 文字列 → text/plain
app.get("/users/:id", ({ id }) => ({ id })); // オブジェクト → JSON(id の型はパスから推論)
serve(app); // Bun でも Deno でも Node.js でも本番のビルドでは dev: devtools() を外すと、開発用のコードがバンドルに入らず、本体だけ(bun build で minify して約 17.7 KB、gzip 後 7.0 KB)になります(開発モード)。
- 返した値がレスポンスになる。 文字列はテキスト、オブジェクトは JSON。
Responseもそのまま返せます - 型はパスから。
/users/:idと書けば、ハンドラーのidに型が付きます。Standard Schema(Zod・Valibot・ArkType など)で、パラメーター・クエリ・ボディも確かめられます - 開発モードが親切。 エラーページ(該当コード・ヒント・エディタで開く)、404 の「もしかして」、リクエストを玉ねぎのように見られるダッシュボード(
/_senri)、層ごとのServer-Timing - 本番でも玉ねぎが見える。
otel({ api, middlewareSpans: true })の 1 行で、ミドルウェアとハンドラーが入れ子の span になって、OpenTelemetry のトレースに出ます(本番のトレース) - どこでも動く。 Web 標準の API だけで書いていて、
evalもnew Functionも使いません。ブラウザの Service Worker でも動きます
npm create senri@latest my-appフォルダ名や --template(ランタイム: Bun・Node.js・Deno・Cloudflare Workers)を省くと、その分を聞かれます(両方渡せば質問なし)。devtools() と serve(app)(Workers は export default app)が入った、すぐ動く最小のアプリができます。作り終わると、そのランタイムで動かすコマンドが表示されます。
| ランタイム | 起動 | URL |
|---|---|---|
| Bun | bun install → bun run dev |
http://localhost:3927 |
| Node.js | npm install → npm run dev |
http://localhost:3927 |
| Deno | deno task dev |
http://localhost:3927 |
| Cloudflare Workers | npm install → npm run dev |
http://localhost:8787 |
bun create senri my-app
pnpm create senri my-app
deno run -A npm:create-senri my-app
npm create senri@latest my-app -- --template workers # 質問なしで作る(bun / node / deno / workers)npm install @senrijs/senri # Node.js / Bun
bun add @senrijs/senri
deno add jsr:@senrijs/senriNode.js は 22 以降で動きます(create-senri の Node.js のテンプレートは、TypeScript をそのまま動かすので 22.18 以降)。
@senrijs/senri/serve の serve() は、ランタイムを自動で判別して起動します。
import { serve } from "@senrijs/senri/serve";
const server = await serve(app); // 起動すると、URL と登録されているルートの一覧を表示する
server.url; // 例: "http://localhost:3927"
await server.stop(); // 処理中のリクエストを待ってから止めるポートは次の順に、最初に見つかったものを使います。
serve(app, { port: 8080 })で明示したポート(0なら空いているポートを自動で選ぶ)- 環境変数
PORT(数字でない、範囲外などのときは、黙って別のポートで待ち受けずにエラーにします) - デフォルトの
3927
Deno では、環境変数を読む許可(--allow-env=PORT など)があるときだけ PORT を読みます。許可がなければ、プロンプトを出さずにデフォルトを使います。
ランタイムの API を直接使うこともできます。
Bun.serve({ port: 3927, fetch: app.fetch }); // Bun
Deno.serve({ port: 3927 }, app.fetch); // Deno
import { serve } from "@senrijs/senri/node"; // Node.js
serve(app, { port: 3927 });アプリをそのまま export default します。c.env と c.executionCtx が使えます。
import { createApp } from "@senrijs/senri";
type Env = { GREETING: string };
const app = createApp<{ Bindings: Env }>();
app.get("/", (_, c) => {
c.executionCtx.waitUntil(logSomewhere());
return c.env.GREETING; // string
});
export default app;- 変数の型も決めるときは
createApp<{ Bindings: Env; Variables: { user: User } }>()と書きます。変数だけなら、今までどおりcreateApp<{ user: User }>()です getIp(c)(@senrijs/senri/ip)は、Cloudflare が付けるCF-Connecting-IPを読みます(Workers で動いているときだけ)- 開発モードのダッシュボードは作りません(
/_senriはふつうの 404)。エラーページは出ますが、該当コードは出ません - wrangler は1つのファイルにまとめるので、
dev: devtools()を残すと、開発用のコード(約 200KB)もバンドルに入ります。本番のビルドでは外してください - Workers では
NODE_ENVが読めないので、devtools()はlocalhostへのリクエスト(wrangler dev)のときだけ開発用の出力をします(開発モード) - 静的ファイルは
@senrijs/senri/staticではなく、Workers の Static Assets で配ってください
Service Worker の fetch イベントに、そのまま答えられます。サーバーなしで、ページからの fetch に Senri が返事をします。
// sw.ts(bun build や Vite でまとめて、navigator.serviceWorker.register("/sw.js") で登録する)
import { createApp } from "@senrijs/senri";
const app = createApp();
app.get("/api/todos/:id", ({ id }) => ({ id, done: false }));
self.addEventListener("fetch", (e) => {
if (new URL(e.request.url).pathname.startsWith("/api/")) e.respondWith(app.fetch(e.request));
});- ページの中で
app.fetch(new Request(...))を直接呼ぶこともできます - CI で、Chromium のページと Service Worker の両方で動くことを確かめています(
scripts/browser.ts)
serve() は SIGTERM / SIGINT を受けると、次の順に止まります。
health()の/readyzを 503 にする(ロードバランサーが新しいリクエストを送ってこないように)- 新しい接続を受けるのをやめ、処理中のリクエストが終わるのを待つ(
shutdownTimeout、既定 10 秒。過ぎたら残りの接続を切る) onShutdownを呼んでから終わる。待っている間にもう一度シグナルを受けたら、すぐに終わる
serve(app, {
shutdownTimeout: 30_000,
onShutdown: () => db.close(),
});ランタイムの既定どおりにしたいときは gracefulShutdown: false にします。
serve() の maxRequestBodySize(バイト数)で、サーバー全体の本文の上限を決められます。超えたら 413 です。
- 省略したときは、どのランタイムでも上限なしです(0.3.0 から。Bun の
Bun.serveの既定の 128 MiB も使いません) - 本文を全部読むときの上限は、アプリの
createApp({ maxBodySize })(既定 1 MiB)で決まります
serve(app, { maxRequestBodySize: 1024 * 1024 * 1024 }); // 1 GiB- Content-Length があれば読む前に断り、ない(チャンク転送)ときは読みながら数えます
- これはサーバー全体の上限です。ルートごとの上限は
bodyLimit()、uploadLimit()、multipart()の上限で付けてください(アプリの既定の上限を置き換えます) - Node.js の
node:httpは、リクエストを受け取り終えるまでの時間を既定で 5 分にしています(requestTimeout)。遅い回線で大きいファイルを送ると、途中で 408 になることがあります
app.get("/users/me", () => "それは自分です"); // 静的なセグメントが優先(登録順は関係ない)
app.get("/users/:id", ({ id }) => `user ${id}`);
app.post("/users", async (_, c) => c.json(await c.body(), 201));
app.on(["PUT", "PATCH"], "/users/:id", () => "updated");
app.all("/any", () => "どのメソッドでも");
app.routes({ "GET /ping": () => "pong" }); // 表の形でもまとめて登録できるapp.get/post/put/patch/delete/head/options/all、任意のメソッドはapp.on(method | method[], path, handler)- HEAD は、登録していなければ GET のルートで処理してボディを捨てます。OPTIONS は、登録していなければ 204 と
Allowを返します(ワイルドカードのルートは数えません) QUERYメソッド(RFC 10008)はapp.on("QUERY", path, handler)で登録します。ボディがなければ 400、Content-Type がなければ 415 にします- CONNECT / TRACE / TRACK は扱いません(501)
- 同じメソッド + 同じパス(パラメーター名だけ違うものも含む)を2回登録するとエラーになります
- 省略できるパラメーター(
:id?)や正規表現(:id{[0-9]+})はありません。こう書くと登録時のエラーになります。値はハンドラーかスキーマで確かめてください
| 返すもの | レスポンス |
|---|---|
| 文字列 | text/plain; charset=utf-8 |
| オブジェクト・配列 | JSON |
Blob / ArrayBuffer / Uint8Array など / ReadableStream / FormData / URLSearchParams |
そのままボディ |
Response |
そのまま |
関数を返す(呼び忘れ)のは型エラーで、実行時も 500 になります。
import { setCookie } from "@senrijs/senri/cookie";
app.get("/", (_, c) => c.html("<h1>こんにちは</h1>")); // text/html; charset=utf-8
app.get("/old", (_, c) => c.redirect("/new", 301)); // 既定は 302
app.post("/login", (_, c) => {
setCookie(c, "session", "abc"); // c.header() で設定したものも付く
return c.redirect("/dashboard", 303);
});c.html()は本文をそのまま返します。利用者の入力を入れるときは、自分でエスケープしてくださいc.redirect()の status は 301 / 302 / 303 / 307 / 308 だけです。c.status()は見ません。/loginのような相対パスも渡せますc.header("location", ...)よりc.redirect()の値が優先です- ASCII 以外はどのランタイムでも同じ形にエンコードします。絶対 URL は
new URL()に任せ(https://例え.jp/→https://xn--r8jz45g.jp/)、相対パスは ASCII 以外の部分だけパーセントエンコードします(%2Fなどは二重にしません) - CR / LF を含む値と、エンコードできない値はエラーになります。ただし、ほかのサイトへの URL は通すので、
c.query("next")のような外からの値は、行き先を確かめてから渡してください(オープンリダイレクトの対策) - ブラウザの Service Worker とページの中の
app.fetch()では、ResponseからSet-Cookieが消えるので、Cookie は付きません(ブラウザの制限です)
import { stream, streamSSE, streamText } from "@senrijs/senri/streaming";
app.get("/events", (_, c) =>
streamSSE(c, async (s) => {
s.onAbort(() => console.log("切断されました"));
for (let i = 0; !s.aborted; i++) {
await s.writeSSE({ event: "tick", id: String(i), data: String(i) });
await s.sleep(1000);
}
}),
);stream()はバイト列、streamText()はテキスト、streamSSE()は Server-Sent Events を少しずつ送ります- クライアントが切断すると
s.abortedがtrueになり、s.onAbort()で登録した関数が動きます。s.write()は読み手が追いつくまで待ちます - 途中のエラーで 500 は返せません。
onErrorを渡すと最後に書き込めて、正常に閉じます。渡さなければ、ログに出して接続を切ります(途中までのダウンロードが完了に見えないように) streamSSE()は最初に: connectedのコメントを送るので、ヘッダーはすぐ届きます。compress()は SSE を圧縮しません- Cloudflare Workers(workerd で確認)では、切断に気づくのは次に書き込んだときです。静かなストリームでは
onAbortは呼ばれず、streamSSE()の既定の heartbeat があれば 15 秒以内に呼ばれました。急ぐ後片付けは任せないでください。途中のエラーでも、ランタイムが本文を正常に閉じます streamSSE()は既定で5秒ごとに: pingのコメントを送ります(heartbeat)。Bun のBun.serveは既定で約10秒(早いと 8.8 秒)、プロキシもよく1分ほどで、黙っている接続を切るからです。クライアントはコメントを無視します。間隔は{ heartbeat: 15_000 }で変えられ、{ heartbeat: false }で止められます(最初の: connectedは残ります)。読み手が止まっている間は送りません
import { multipart } from "@senrijs/senri/multipart";
app.post("/upload", async (_, c) => {
for await (const part of multipart(c, { maxFileSize: 100 * 1024 * 1024 })) {
if (part.filename !== undefined) await save(crypto.randomUUID(), part.stream);
else console.log(part.name, await part.text());
}
return "ok";
});multipart/form-dataを1パーツずつ読みます。本文を全部メモリに読まないので、大きいファイルを届いた分からそのまま保存先(ファイル、オブジェクトストレージなど)へ流せます。保存先は自由です- パーツは
name、filename(フィールドならundefined。ファイルを選ばなかったファイル欄は"")、contentType(なければtext/plain)、headers、stream、text()、bytes()を持ちます - 上限:
maxParts(既定 100)、maxFileSize(既定 10 MiB)、maxFieldSize(既定 64 KiB)、maxHeaderSize(パーツのヘッダー、既定 8 KiB)、maxTotalSize(本文全体、既定 100 MiB。maxFileSizeをそれより大きくしたら、それに合わせる)。超えたら 413 です。壊れた本文やboundaryがないときは 400、multipart でなければ 415 です - ループが次へ進むと、読み残したパーツは読み飛ばします。そのあとで前のパーツの
streamを読むとエラーなので、保存はawaitしてから次へ進んでください。breakで抜けると、それ以上は読みません - 本文を読んだあと(
c.body()、uploadLimit()、ルートのbodyのスキーマ)や、2回目に呼ぶとエラーです。小さいファイルをFileで受け取って種類まで確かめるならuploadLimit()、大きいファイルを流すならmultipart()と、ルートごとに使い分けてください part.filenameとpart.contentTypeは、送られてきたそのままの値です。保存先のパスには使わず、crypto.randomUUID()などで決めるかsafeFileName()を通してください- 本文全体の上限は
maxTotalSizeで付けられます。bodyLimit()を一緒に使ってもかまいません multipart()を使うルートでは、アプリの本文の既定の上限(createApp({ maxBodySize }))の代わりに、multipart()の上限が効きます
import { createRouter } from "@senrijs/senri";
const posts = createRouter("/users/:id/posts");
posts.get("/", ({ id }) => `user ${id} の投稿`); // id に型が付く
posts.get("/:postId", ({ id, postId }) => `${id} / ${postId}`);
app.route(posts);
app.route("/admin", adminApp); // 別の createApp() をつなぐこともできるルートを表にまとめて定義すると、ルートの型(パス・パラメーター・スキーマ・ハンドラーの戻り値)を持ったまま、ファイルの外に出せます。
import { createApp, defineRoutes, endpoint, mergeRoutes } from "@senrijs/senri";
import { z } from "zod";
// キーは "メソッド /パス"。パラメーターはキーから型が付く
export const userRoutes = defineRoutes({
"GET /users/:id": ({ id }) => ({ id }),
// スキーマを付けるルートは endpoint(schemas, handler) で包む(app.post(path, schemas, handler) と同じ引数)
"POST /users": endpoint({ body: z.object({ name: z.string() }) }, (_, c) => ({ created: c.valid("body").name })),
});
// 前置きは 2 段で書く。前置きのパラメーターも、中のハンドラーで型が付く
export const orgRoutes = defineRoutes("/orgs/:orgId")({
"GET /": ({ orgId }) => `org ${orgId}`, // "GET /orgs/:orgId"
"GET /members/:memberId": ({ orgId, memberId }) => ({ orgId, memberId }),
});
// 表を合わせる(同じキーが 2 つあればエラー)
export const routes = mergeRoutes(userRoutes, orgRoutes);
const app = createApp();
app.routes(routes);- 前置きは
/で始め、/で終わらないように書きます("/users") c.get()に型を付けるときは、前置きと一緒にアプリの型を渡します:defineRoutes<"/admin", Vars>("/admin")({ ... })- パスの書き方の確認と、同じルートの 2 回登録の確認は、
app.routes()に渡したときにapp.get()と同じく行います
const auth: Middleware<{ user: User }> = async (c, next) => {
const user = await findUser(c.req.headers.get("authorization"));
if (!user) {
c.status(401);
return "ログインしてね";
}
c.set("user", user);
await next();
};
// 表の全部のルートに付ける(前置きがなければ "")
export const adminRoutes = defineRoutes("/admin", { use: [auth] })({
"GET /me": (_, c) => ({ user: c.get("user") }), // c.get("user") は User | undefined
// このルートだけに付ける
"DELETE /users/:id": endpoint({ use: [requireOwner], params: idSchema }, ({ id }) => deleteUser(id)),
});- 動く順番は、アプリの
app.use()→ 表のuse→ ルートのuse→ スキーマの確認 → ハンドラーです。ミドルウェアが値を返したら、スキーマの確認(本文を読む)の前に止まります - ミドルウェアを
Middleware<{ user: User }>のように書くと、c.get("user")に型が付きます - そのルートに当たったリクエストでだけ動きます。開発モードのタイムラインと、ダッシュボードの「ルート」の行にも出ます
表の型(typeof routes)をクライアントに渡すと、パス・パラメーター・クエリ・ボディ・レスポンスに型が付きます。サーバーのコードは型だけ読むので、クライアントのバンドルには入りません。
// server/routes.ts
export const routes = mergeRoutes(userRoutes, orgRoutes);
export type Api = typeof routes;
// client.ts
import { client } from "@senrijs/senri/client";
import type { Api } from "./server/routes.ts";
const api = client<Api>("https://example.com", {
headers: () => ({ authorization: `Bearer ${getToken()}` }), // 関数なら、呼ぶたびに読む
});
const res = await api("GET /users/:id", { params: { id: "1" } });
if (res.ok) {
res.data; // ハンドラーの戻り値を JSON にしたあとの型({ id: string })
} else {
res.status; // 404 など
res.error; // 本文(unknown)
}
await api("POST /users", { body: { name: "a" } }); // ボディはスキーマの入力の型- 呼び方は、表のキーと同じ文字列です。パラメーターはエンコードしてパスに入れ、
queryは文字列にして付け(配列は同じキーを繰り返す)、bodyは JSON で送ります(FormData・URLSearchParams・Blob・バイト列・ストリームはそのまま) - 戻り値は
{ ok, status, data, error, response }です。2xx でなくても例外にしません(ネットワークのエラーと、壊れた JSON だけ例外) - 本文は Content-Type で読み分けます。JSON は値に、
text/*は文字列に、それ以外はBlobにします dataの型はハンドラーの戻り値です。Dateはstringになるなど、JSON にしたあとの形にします。endpoint({ response })のスキーマがあれば、そちらの出力の型にしますonError・ミドルウェア・notFoundの応答は型に入らず、error(unknown)に入ります
ハンドラーが c.json(body, status) / c.text(body, status) で status を書いて返すと、クライアントで status ごとに型が分かれます。endpoint({ responses: { 404: schema } }) に書いたスキーマも同じです。
// サーバー
"GET /users/:id": ({ id }, c) => {
const user = findUser(id);
if (!user) return c.json({ message: "not found" }, 404);
return user;
},
// クライアント
const res = await api("GET /users/:id", { params: { id: "1" } });
if (res.ok) res.data; // User(JSON にしたあとの形)
else if (res.status === 404) res.error; // { message: string }
else res.error; // unknown(書いていない status)- 2xx(
c.json(body, 201)など)は成功のdataに入ります。status を書かないc.json(body)は 200 として扱います(c.status()で決めた status は、型には残りません) c.json()/c.text()の戻り値はTypedResponseというResponseの型です。実行時はふつうのResponseで、そのままResponseとして使えますfetchを差し替えられます。client<Api>("http://localhost", { fetch: (req) => app.fetch(req) })とすれば、サーバーを立てずに呼べます
import { request, testClient } from "@senrijs/senri/testing";
// 型付きクライアントで、サーバーを立てずに app.fetch を呼ぶ
const api = testClient<Api>(app, { cookies: true });
await api("POST /login", { body: { user: "a", password: "x" } });
const me = await api("GET /me"); // ログインの Cookie が付く
expect(me.status).toBe(200);
// 表にないルートや、型付きでは送れないリクエストは request() で(Response が返る)
const res = await request(app, "POST /upload", { body: form });
expect(res.status).toBe(413);- 接続元は
127.0.0.1として渡します(getIp()・ipRestriction()・開発モードの localhost 判定が、本物のサーバーと同じに動きます)。{ ip }で変えられます - Cloudflare Workers のアプリは
{ env, ctx }を渡します(c.env・c.executionCtx)。このときは、Workers と同じく接続元は渡しません { cookies: true }で、前の応答のSet-Cookieを次のリクエストに付けます(名前ごとに 1 つ。domain と path は見ません){ headers }で、毎回付けるヘッダーを決められます
表から OpenAPI の文書(既定は 3.1)を作れます。
import { openAPI } from "@senrijs/senri/openapi";
export const routes = defineRoutes({
"GET /users/:id": endpoint(
{
params: z.object({ id: z.coerce.number() }),
response: userSchema, // 200 の本文
responses: { 404: notFoundSchema }, // ほかの status
openapi: { summary: "ユーザーを取る", tags: ["users"] },
},
({ id }) => findUser(id),
),
});
const doc = openAPI(routes, { info: { title: "My API", version: "1.0.0" } });
app.get("/openapi.json", () => doc);- パスとメソッドは表のキーから作ります(
:id→{id})。params・query・bodyのスキーマが、パラメーターとリクエストの本文になります。フォームで受けるルートはbodyType: "form"と書きます - レスポンスは、
response(200)とresponses(status ごと)に書いたものだけ入ります。ハンドラーの戻り値の型は、動いているときには分からないためです - スキーマは Standard JSON Schema で JSON Schema にします(Zod 4.2・ArkType 2.1.28 から。Valibot は
@valibot/to-json-schemaで包みます)。対応していないスキーマはtoJSONSchemaで変換を渡せます。どちらもなければ、空のスキーマにして警告します - 開発モードでは、ハンドラーの戻り値が
responseのスキーマに合わないと、ターミナルに警告します(応答は変えません。本番では確かめません) - 表にない
app.get()などのルートは入りません
- 末尾スラッシュと連続スラッシュは無視します。
/users、/users/、//usersはどれも同じです - パスはセグメントごとにパーセントデコードされます。
/こんにちはのようにそのまま書いたルートにマッチします - デコードできないパスと、
%2F(エンコードされた/)を含むパスは 400 です - 正規化・デコード済みのパスは
c.pathで読めます。パスで判定するミドルウェアは、req.urlではなくc.pathかapp.use("/admin", mw)を使ってください
最後のセグメントを * にすると、そのパスとその下のすべてに当たります。残りのパスは "*" で受け取れます。
app.get("/docs/*", ({ "*": page }) => `page: ${page}`);
app.get("/users/:id/files/*", ({ id, "*": path }) => `${id}: ${path}`);
app.get("/*", (_, c) => c.html(indexHtml)); // SPA の fallback(/ にも当たる)/docs/* へのリクエスト |
"*" の値 |
|---|---|
/docs、/docs/ |
"" |
/docs/a、/docs/a/、/docs//a |
"a" |
/docs/a/b |
"a/b" |
/docsx |
当たらない |
- 書けるのは最後のセグメント全体だけです。
/a/*/c、/*.js、/files*、/*nameは登録時のエラーになります - 優先順位は、登録順によらず 静的 → パラメーター → ワイルドカード です。
/a/b/cの枝で見つからなければ、戻って/a/*を試します - 405 と自動の OPTIONS には数えません。
GET /docs/*だけがあるパスに POST や OPTIONS を送ると 404 です。答えたいときは、app.post・app.options・app.allで登録してください。/docs/aに静的なルートもあるときの 405 のAllowには、そのルートのメソッドだけが入ります - 値はセグメントごとに1回だけデコードされています。もう一度デコードしないでください(
%252Fは%2Fのままです)。%2Fを含むパスはルートに届く前に 400 になるので、値の/は区切りだけです - 値をファイルのパスに使わないでください。
\・:・NUL は値に入ります(/docs/..%5C..%5Csecretの値は..\..\secret)。ファイルを配るなら、これらを確かめているserveStaticを使ってください - ミドルウェアの
app.use("/docs/*", mw)はapp.use("/docs", mw)と同じ意味です
import { getCookie, setCookie } from "@senrijs/senri/cookie";
import { getIp } from "@senrijs/senri/ip";
app.post("/search", async (_, c) => {
c.query("page"); // "2"(なければ undefined。c.query() で全部)
c.queries("tag"); // ["a", "b"]
await c.body(); // Content-Type に合わせて読む(JSON・フォーム・テキスト・それ以外は ArrayBuffer)
await c.bodyJson(); // Content-Type を見ずに JSON として読む(読めなければ 400)。c.bodyBytes() は ArrayBuffer
getCookie(c, "session"); // Cookie(getCookie(c) で全部)
setCookie(c, "seen", "1"); // deleteCookie(c, name) で消す
getIp(c); // 接続元の IP アドレス(分からなければ null)
return "ok";
});c.body()・c.bodyJson()・c.bodyBytes()は何度呼んでも同じ結果です(ミドルウェアとハンドラーの両方から読めます)。c.req.json()などはRequestのメソッドそのままなので、2回目はエラーです- 元のバイト列が要るとき(Webhook の署名など)は、先に
c.bodyBytes()を呼んでください。あとのc.body()・c.bodyJson()・スキーマはそのバイト列から読みます
本文を全部読むもの(c.body()・c.bodyJson()・c.bodyBytes()・ルートの body のスキーマ・c.req.json() / text() / formData() / arrayBuffer())は、既定で 1 MiB までです。超えたら 413 です。
const app = createApp({ maxBodySize: 10 * 1024 * 1024 }); // アプリ全体で 10 MiB に(Infinity で上限なし)
app.use("/import", bodyLimit({ maxSize: 50 * 1024 * 1024 })); // このルートだけ 50 MiB まで- 本文を読んだときだけ効きます。本文を読まないルートは、大きい本文が来ても変わりません
- Content-Length が上限より大きければ、中身を読まずに 413 にします(残りの本文は読み捨てます)。Content-Length のない本文(チャンク転送など)は、読みながら数えます
- ハンドラーが読み取りのエラーを握りつぶしても、413 になります
- ルートの
bodyLimit()(と、それを使うuploadLimit())とmultipart()は、この既定を自分の上限で置き換えます(重ねません)。大きい本文を受けるルートだけ上限を上げられます。表のルートならendpoint({ use: [bodyLimit({ maxSize })] }, handler)でも付けられます - Content-Length のない本文は、数えるためにストリームで包むので、読むのが遅くなります(小さい本文で数十 µs)。Content-Length のある本文は、包まないので速さは変わりません
c.req.bodyを自分でストリームとして読むときも、1 MiB を超えると 413 です(Content-Length あり・なしの両方)。大きい本文をそのまま流したいルート(保存先へ流すアップロードなど)には、bodyLimit({ maxSize })を付けて上限を上げてください。multipart()は自分の上限を使うので、付けなくてかまいません- Cookie と IP は、使わないアプリのバンドルに入らないよう、別の入口(
@senrijs/senri/cookie・@senrijs/senri/ip)にしています getIp(c)はランタイムが渡す接続元を使います。X-Forwarded-Forなどのヘッダーは偽装できるので読みません- プロキシの後ろでは
trustProxy()を使います。const clientIp = trustProxy({ hops: 1 })やtrustProxy({ proxies: ["10.0.0.0/8"] })で作った関数が、クライアントの IP を返します。X-Forwarded-Forの先頭は信じず、右から数えます。hopsは、プロキシを通らずにアプリへ届く環境では偽装できるので、その場合はproxiesを使ってください setCookie(c, name, value, options)の既定はPath=/・HttpOnly・SameSite=Laxです- 署名付き Cookie は
await setSignedCookie(c, name, value, secret, options)で付けて、await getSignedCookie(c, name, secret)で読みます。署名は HMAC-SHA256(Web Crypto)で、確かめるときは時間が一定の比べ方(crypto.subtle.verify)を使います。書き換えられていたらfalse、送られていなければundefinedです- 値はクライアントから読めます(暗号化ではなく、書き換えを見つけるだけです)。秘密にしたいものは入れないでください
- 秘密鍵は 32 バイト以上のランダムな文字列にして、コードに書かず環境変数や
c.envから読んでください。["新しい鍵", "古い鍵"]のように配列で渡すと、新しい鍵で署名し、どちらの鍵の署名も受け付けます(鍵の入れ替え) - 署名には Cookie の名前も入るので、ある Cookie の値を別の名前の Cookie に写しても通りません
maxAgeはブラウザに捨ててもらうだけなので、同じ値を後から送り直すことはできます。期限を守らせたいときは、値に期限を入れて確かめてください- Bun・Deno・Node.js・Cloudflare Workers・ブラウザ(Service Worker。
crypto.subtleは HTTPS か localhost でだけ使えます)で動きます
import { contextStorage, getContext } from "@senrijs/senri/context-storage";
app.use(contextStorage()); // ほかのミドルウェアより先に
// c を引数で渡さなくても、いま処理しているリクエストの c が取れる(await のあとでも)
function currentUser() {
return getContext().req.headers.get("x-user");
}
app.get("/me", () => currentUser());AsyncLocalStorage(node:async_hooks)を使います。Bun・Deno・Node.js はそのまま動きます- Cloudflare Workers では、wrangler の設定に
nodejs_als(またはnodejs_compat)の互換性フラグを付けてください。 古い compatibility date では、付けないとNo such module "node:async_hooks"で起動しません。wrangler を使わずに自分でまとめるときは、node:*をまとめずに残してください - ブラウザ(Service Worker)では使えません。 ブラウザには
node:async_hooksがないので、この入口を読み込めません。cを引数で渡してください - 後ろのミドルウェア、ハンドラー、
contextStorage()より内側で起きたエラーのonError、app.notFound、ストリームの中から取れます。contextStorage()より前のミドルウェアや、リクエストの外(起動時など)では、getContext()は例外(code: "no_context")、tryGetContext()はundefinedです - ハンドラーで始めたタイマーは、レスポンスのあとでもそのリクエストの
cが見えます(AsyncLocalStorageの性質)。そこでは使い続けないでください
import { upgradeWebSocket } from "@senrijs/senri/websocket";
app.get(
"/chat",
upgradeWebSocket((c) => ({
onOpen(ws) { ws.send(`hello ${c.query("name")}`); },
onMessage(data, ws) { ws.send(data); }, // data: 文字は string、バイナリは Uint8Array
onClose(code, reason, ws) {},
onError(error, ws) {}, // ほかのハンドラーが投げたものも、ここに届く
})),
);ルートの書き方はどのランタイムでも同じです。ランタイムごとに要るものは、次のとおりです。
| ランタイム | 要るもの | 1 つのメッセージの上限 |
|---|---|---|
| Bun | @senrijs/senri/serve の serve() なら何も要りません。Bun.serve を自分で呼ぶときは websocket を渡します: Bun.serve({ fetch: app.fetch, websocket }) |
16 MiB(Bun の既定) |
| Deno | 何も要りません | Deno の既定 |
| Node.js | ws パッケージを入れて、serve() に渡します(下の例) |
ws の maxPayload(既定は 100 MiB なので、必ず付けてください) |
| Cloudflare Workers | 何も要りません | 1 MiB(Workers の上限) |
| ブラウザ(Service Worker) | 使えません(501) |
// Node.js: Senri は WebSocket のフレームを自分では読まず、実績のある ws に任せます(Senri の依存は増えません)
import { WebSocketServer } from "ws";
import { serve } from "@senrijs/senri/serve"; // @senrijs/senri/node の serve() でも同じ
serve(app, { webSocketServer: new WebSocketServer({ noServer: true, maxPayload: 1024 * 1024 }) });- よそのサイトのページからの接続は、既定で 403 にします(CSWSH 対策)。
OriginのホストがHostと同じときだけ通し、ほかはupgradeWebSocket(create, { origin: ["https://app.example.com"] })で足します。Originのない接続(ブラウザ以外)は通します。csrf()と同じ考え方です - ミドルウェアは、ふつうのリクエストと同じに動きます。認証のミドルウェアが 401 を返せば、upgrade しません
Upgrade: websocketのないリクエストは 426 です- Node.js で
webSocketServerを渡していないと、WebSocket のルートは 500 になります(開発モードでは渡し方を出します)。開発モードで、渡したWebSocketServerのmaxPayloadがwsの既定(100 MiB)のままなら、起動時に注意を出します - サブプロトコル(
Sec-WebSocket-Protocol)の取り決めと、圧縮(permessage-deflate)の設定は、まだありません。Node.js の圧縮はwsの設定どおりです
ルートにスキーマを渡すと、ハンドラーを呼ぶ前に確かめます。Standard Schema に対応したライブラリ(Zod・Valibot・ArkType など)のスキーマが、そのまま使えます。
import { z } from "zod";
app.post(
"/users/:id",
{
params: z.object({ id: z.coerce.number() }),
body: z.object({ name: z.string().min(1) }),
},
({ id }, c) => {
const { name } = c.valid("body"); // { name: string }
return { id, name }; // id: number
},
);params・query・bodyを渡せます。paramsが通れば、ハンドラーの第1引数が変換後の値になります- 通らなければ 400 です。本番の本文は
400 Bad Requestだけで、開発モード(devtools())では、どこが違うかを一覧にします。スキーマの書き間違いも、開発モードなら登録した時点で知らせます - 自分の形で返したいときは、
app.onErrorでValidationErrorを受けます(err.targetとerr.issues)
app.use(async (c, next) => {
const res = await next(); // 下流(後ろのミドルウェアとハンドラー)を動かす
c.header("x-powered-by", "senri");
return res;
});
// /admin とその下だけで動く
app.use("/admin", (c, next) => {
if (c.req.headers.get("authorization") !== "secret") {
c.status(401);
return "ログインしてね"; // 値を返したら、そこで終わり
}
return next();
});app.use("/admin/*", mw)はapp.use("/admin", mw)と同じ意味です(/admin自体にも動きます)。/a/*/cや/*.jsのような、ほかの場所の*は登録時のエラーになります- ルートはミドルウェアより先にマッチするので、
next()の前からc.route("/users/:id"のようなパターン)とc.paramsが読めます c.header()で設定したヘッダーは、最後に1回だけレスポンスに足されます。Responseを直接返したときも、エラーのときも効きます。ただし、Content-TypeとLocationは、レスポンス自身にあればそちらが優先です- ミドルウェアからハンドラーへ値を渡すには
c.set/c.getを使います。型はcreateApp<{ user: User }>()で決めます
import { basicAuth, bearerAuth, bodyLimit, cache, compress, cors, csrf, etag, health, ipRestriction, languageDetector, logger, methodOverride, prettyJSON, rateLimit, requestId, secureHeaders, timeout, trailingSlash, uploadLimit } from "@senrijs/senri";
import { serveStatic } from "@senrijs/senri/static";
app.use(health({ ready: () => db.isConnected() })); // /healthz と /readyz
app.use(logger()); // 色付きで1行ずつ。{ format: "json" } で pino 形式
app.use(secureHeaders()); // X-Content-Type-Options など
app.use(cors({ origin: ["https://example.com"] }));
app.use(csrf()); // よそのサイトからの POST などを 403 に(トークンは使わない)
app.use(bodyLimit({ maxSize: 1024 * 1024 })); // 超えたら 413
app.use(serveStatic({ root: "./public" })); // Bun・Deno・Node.js で静的ファイルを配る
app.use(requestId()); // c.get("requestId") と X-Request-Id
app.use(timeout(5000)); // 5 秒で終わらなければ 504
app.use("/admin", basicAuth({ username: "admin", password: env.ADMIN_PASSWORD }));
app.use("/api", bearerAuth({ token: env.API_TOKEN }));
app.use(compress()); // gzip / deflate(1KB より小さい本文はそのまま)
app.use(etag()); // ETag を付けて、変わっていなければ 304
app.use(rateLimit({ windowMs: 60_000, limit: 100 })); // 超えたら 429 と Retry-After
app.use("/admin", ipRestriction({ allow: ["192.0.2.0/24"], deny: ["192.0.2.13"] }));
app.use(trailingSlash()); // /a/ → /a に 301
app.use("/assets", cache({ cacheControl: "public, max-age=3600" }));
app.use(languageDetector({ supportedLanguages: ["ja", "en"], fallbackLanguage: "en" })); // c.get("language")
app.use(prettyJSON()); // ?pretty で JSON を整形
app.use("/photos", uploadLimit({ maxTotalSize: 20 * 1024 * 1024, types: ["image/png"] }));requestId(): 受け取ったX-Request-Idは既定で使いません。信頼できるプロキシの後ろではtrustIncoming: trueにしてください(128 文字までのA-Z a-z 0-9 . _ = + / -だけを受け付け、それ以外は作り直します)timeout(): 時間切れでも処理そのものは止まりません。同期のループ中はタイマーも動きません。c.req.signalは切断だけを表すので、外部への呼び出しを止めるにはAbortSignal.timeout()と組み合わせてくださいcsrf(): GET・HEAD・OPTIONS 以外で、ブラウザが付けるSec-Fetch-Siteを見て、よそのオリジンからなら 403 にします。Sec-Fetch-Siteのない古いブラウザでは、OriginのホストをHostと比べます(スキームは比べないので、TLS を終えるプロキシの後ろでも動きます)。どちらのヘッダーもないリクエストは、ブラウザからではない(curl やサーバーどうし)ので通します。ほかの自分のサイトからも受けるときは、app.use(csrf({ origin: ["https://admin.example.com"] }))のように、そのパスにかかる 1 つのcsrf()に渡してください(app.use(csrf())のあとにapp.use("/api", csrf({ origin }))を足しても、先のcsrf()が 403 で止めるので届きません)。GET と HEAD は確かめないので、状態を変える処理を置かないでください。プロキシがHostを書き換えるときも、originに正しいオリジンを入れてくださいbasicAuth()/bearerAuth(): 失敗すると 401 とWWW-Authenticateを返します。固定の値の代わりにverifyUser/verifyTokenで検証することもできます(trueを返したときだけ通します)。cors()と一緒に使うときはcors()を先に登録してくださいcompress():etag()と一緒に使うときはcompress()を先に登録してください。少しずつ流すストリームは、途中で止まって見えないように圧縮しませんetag(): GET の 2xx に弱い ETag を付けます。ハンドラーは毎回動きます。ストリームの本文と HEAD には付けませんipRestriction():denyを先に見ます。拒否は 403 です。IP が分からないときも 403 にします(テストではallowUnknown: true)。プロキシの後ろではip: trustProxy({ hops: 1 })のように渡してくださいrateLimit(): 固定ウィンドウで、既定のキーは IP です(IPv6 は /64 ごと)。IP が分からないリクエストは制限せず、最初の 1 回だけ警告します。既定の保存先はプロセスのメモリなので、Workers では isolate ごとの制限になり、全体の制限にはなりません。storeで Redis などに差し替えられますmethodOverride(app): HTML のフォームから PUT / PATCH / DELETE を送れるようにします。ルートはミドルウェアより先に決まるので、ミドルウェアではなくapp.fetchを包みます(serve(methodOverride(app))、Workers ではexport default methodOverride(app))。上書きできるのは POST だけです。multipart/form-dataのフォームは読まないので、その場合はX-HTTP-Method-Overrideヘッダーを使ってください。使うと Node では全リクエストが、RequestとResponseを作らない道を外れますtrailingSlash():/aと/a/は同じルートなので、正規の形にそろえたいとき(SEO)に使います。GET / HEAD で、ルートに一致したパスだけをリダイレクトしますcache(): GET / HEAD の 2xx と 304 にCache-ControlとVaryを付けるだけで、保存はブラウザや CDN に任せます。etag()より先に登録してください。setCookie()の Cookie はミドルウェアから見えないので、個人のページがあるパスにpublicを付けないでくださいlanguageDetector(): クエリ(lang)、Cookie(language)、Accept-Languageの順に見ます。c.get("language")は必ずsupportedLanguagesのどれかです。Cookie には書き込みませんprettyJSON():compress()とetag()のあとに登録してください。1 MiB を超える本文とストリームは整形しませんuploadLimit(): multipart のファイルの大きさ(maxTotalSizeは必須、maxFileSize)、数(maxFiles)、種類(types、extensions)を確かめます。超えたら 413、種類が違えば 415 です。PNG、JPEG、GIF、WebP、PDF は中身の先頭のバイトも確かめます。読んだ結果はc.body()で受け取れて、ルートのスキーマも検証のあとに動きます。c.body()は全部メモリに読むので、使うメモリはmaxTotalSizeまでです。送られたファイル名(file.name)は../../etc/passwdのようなものかもしれないので、保存先に使わないでください(crypto.randomUUID()などで自分で決めるか、safeFileName()を通してください)health():/healthzは応答できれば 200。/readyzはready()が true なら 200、false・例外・止まり始めたあとは 503logger(): 色は既定でオンです。ファイルや CI に流すときはcolor: falseにしてくださいsecureHeaders(): Content-Security-Policy と Cross-Origin-Embedder-Policy は既定でオフです(アプリによって壊れやすいので)serveStatic(): ドットファイルは既定で配りません。root の外(シンボリックリンクを含む)には出ません。prefix: "/static/*"はprefix: "/static"と同じ意味です
@senrijs/senri/jwt で、JWT の署名と確認ができます。暗号は Web Crypto だけで、Bun・Deno・Node.js・Cloudflare Workers・ブラウザで動きます。
import { jwt, signJwt, verifyJwt, type JwtVariables } from "@senrijs/senri/jwt";
const app = createApp<JwtVariables>();
app.post("/login", async () => ({ token: await signJwt({ sub: "42" }, env.JWT_SECRET, { alg: "HS256", expiresIn: 3600 }) }));
app.use("/api", jwt({ keys: env.JWT_SECRET, algorithms: ["HS256"] })); // Authorization: Bearer <token>(cookie: "名前" で Cookie から)
app.get("/api/me", (_, c) => ({ payload: c.get("jwtPayload") })); // c.get() は JwtPayload | undefined なので、そのままは返せないalgorithmsは必須です。 トークンのalgが、この中にあるときだけ確かめます。noneは受け付けません- 対応するアルゴリズム: HS256 / HS384 / HS512、RS256 / RS384 / RS512、PS256 / PS384 / PS512、ES256 / ES384、EdDSA と Ed25519(RFC 9864。どちらも Ed25519 の署名)。ES512 にはまだ対応していません
- 鍵: 文字列は HMAC の秘密鍵です(HS256 は 32 バイト以上、HS384 は 48、HS512 は 64。短いと TypeError)。ほかのアルゴリズムには、PEM(
PUBLIC KEY/PRIVATE KEY)、JWK、CryptoKeyを渡します。PEM の公開鍵が HMAC の秘密鍵として使われることはありません(アルゴリズムの取り違えの攻撃を防ぐため) - 鍵の入れ替え:
keys: [{ kid: "2026-11", key: newKey }, { kid: "2026-10", key: oldKey }]のように配列で渡します。signJwtはkidをヘッダーに入れ、verifyJwtはトークンのkidと同じ鍵(とkidのない鍵)だけを試します。JWKS のkeysは、そのまま渡せます exp・nbfがあれば確かめます(clockToleranceで時計のずれを許す)。issuer・audience・subject・maxAgeも指定できます。期限を必ず付けたいときは、signJwtのexpiresInを使ってください- だめなトークンは
JwtError(401 のHttpError)で、WWW-Authenticate: Bearer error="invalid_token"が付きます。err.reasonで理由(expired・signatureなど)が分かります - 外の JWKS の URL から鍵を取ってくる機能と、暗号化(JWE)はありません
import { HttpError } from "@senrijs/senri";
app.get("/secret", () => {
throw new HttpError(403, "見せられません"); // message はそのままクライアントに返る
});
app.onError((err, c) => ({ error: "something went wrong" }));
app.notFound((c) => `ありません: ${c.path}`);ルートはあるけれど中身がないときは、c.notFound() で app.notFound のハンドラー(なければ既定のもの)に回せます。ミドルウェアからも呼べます。
app.get("/items/:id", ({ id }, c) => {
const item = items.get(id);
if (!item) return c.notFound();
return item;
});return c.notFound()と書いてください。 例外で止まるのでc.notFound();だけでも以降は動きませんが、(_, c) =>のようにcの型を明示していないと、TypeScript は「止まる」と扱いません(itemがundefinedのままになり、最後に書くと戻り値が型エラーになります)new HttpError(404)とほぼ同じ動きです。違うのは行き先で、onErrorではなくapp.notFoundのハンドラーに回ります- 外側のミドルウェアの
await next()は投げずに、404 のレスポンスを返します。res.statusで判定してください - 同じ関数の
try/catchには捕まります。if (err instanceof HttpError) throw errで投げ直してください
- 外側のミドルウェアの
c.header()で設定したヘッダー(Set-Cookie・CORS など)は 404 にも付きます。ロガーとダッシュボードには 404 として記録されますapp.notFoundのハンドラーの中で呼ぶと、既定の 404 になります。onErrorの中で呼ぶと、ほかのエラーを投げたときと同じく、固定の 500 になりますapp.route()でつないだアプリから呼んでも、親のハンドラーが使われます- 開発モードの 404 に「もしかして」が出るのは、ルートがなかったときだけです
エラーを application/problem+json で返したいときは、@senrijs/senri/problem を使います。選んだときだけ変わり、既定のエラーの形(テキスト)はそのままです。
import { ProblemError, problem, problemDetails } from "@senrijs/senri/problem";
const problems = problemDetails(); // problemDetails({ validationErrors: true }) で、バリデーションのどこが違うかも返す
app.onError(problems.onError);
app.notFound(problems.notFound);
app.post("/transfer", () => {
throw new ProblemError(403, {
type: "https://example.com/probs/out-of-credit",
title: "You do not have enough credit.",
detail: "Your current balance is 30, but that costs 50.",
extensions: { balance: 30 },
});
});
app.get("/legacy", (_, c) => problem(c, { status: 410, detail: "Use /v2 instead." })); // 投げずに返すtypeを省くとabout:blankになり、titleは status の名前("Not Found"など)になりますProblemError以外のHttpError(ルーターの 405、basicAuth()の 401、rateLimit()の 429 など)は、messageが status だけ("405 Method Not Allowed")ならdetailを付けず、それ以外ならdetailにします。Allow・WWW-Authenticate・Retry-Afterなどのヘッダーは残りますHttpErrorでないエラーは、既定と同じく中身を出さず、titleだけの 500 にします- バリデーションのエラーの中身(
errors)は、スキーマの作りが外から見えるので、既定では出しません ProblemErrorはHttpErrorなので、problemDetails()を使わないアプリでは、detail(なければtitle)をテキストで返すふつうのエラーになります- ほかの
app.onErrorと同じく、開発モードのエラーページや 404 ページも置き換わります。開発中は使わず、本番だけで設定することもできます
import { createApp } from "@senrijs/senri";
import { devtools } from "@senrijs/senri/dev";
const app = createApp({ dev: devtools() });開発用の機能は、すべて @senrijs/senri/dev にあります。本体(@senrijs/senri)は開発用のコードを一切 import しないので、devtools() を渡さなければ、どのバンドラーでも開発用のコードは入りません。devtools() を渡したときだけ、次のものが動きます。渡さなければ、固定の文言(500 Internal Server Error など)だけを返し、計測も記録もしません。
- 500 の本文にエラーメッセージ、404 に「もしかして: GET /hello ?」、405 にどのメソッドならあるか、バリデーションの 400 に違うところの一覧、登録時のエラーに詳しい説明
- エラーページと 404 ページ: ブラウザから開いたとき(
Acceptにtext/htmlがあるとき)だけ。エラーが起きた行の前後のコード、ヒント、スタックトレース、ミドルウェアを通った順番と時間。エラーの場所は VS Code・Cursor・WebStorm・Zed で開けます - ダッシュボード(
/_senri): 直近 200 件のリクエストをリアルタイムで。玉ねぎタイムライン(ミドルウェアごとの自分の時間と下流込みの時間)、ルートとミドルウェアの一覧。本番では、同じ玉ねぎを OpenTelemetry のトレースで見られます Server-Timingヘッダー: 層ごとの時間が、ブラウザの開発者ツールの「タイミング」に出ます- 書き間違いの警告: 最初のリクエストのときに、どのルートにも当たらないパス指定のミドルウェア(
app.use("/admni", ...))と、ほかのフレームワークの書き方に見えるパス(/a?、/[id]、/{id})を、コンソールとダッシュボードで知らせます。同じ警告は1回だけです。ルートなしで自分で返すミドルウェアなら、無視して構いません
開発用の画面とメッセージは、日本語と英語に対応しています。
| 対象 | 言語の決め方 |
|---|---|
| エラーページ・404 ページ・ダッシュボード・開発モードのテキストのレスポンス | リクエストの Accept-Language |
| ターミナルの警告・案内、登録時のエラーの説明 | 環境変数 LC_ALL → LC_MESSAGES → LANG → OS の言語 |
- 決められないとき(
Accept-Languageがない curl、知らない言語、LANG=Cなど)は英語です devtools({ lang: "ja" })で、画面もターミナルも固定できます。serve()の案内はserve(app, { lang: "ja" })で固定できます- Windows の Bun は OS の言語を読めず英語になるので、日本語にしたいときは
langかLANGを指定してください(LANG=ja_JP.UTF-8など) - Deno で環境変数を読む許可(
--allow-env=LANGなど)がないときは、環境変数を飛ばして OS の言語を見ます - ダッシュボードの記録の、エラーの説明はリクエストのときの言語で残ります。本番でも出るエラーメッセージは翻訳しません
本番での扱いは、2通りあります。本番のビルドから外すのが確実です。
- 本番のビルドから
devtools()を外す(devを渡さない): 開発用のコードがバンドルに入らず、サイズが最小になります。依存は増えません(同じパッケージの別の入口なので) dev: devtools()を残してNODE_ENV=productionにする:devtools()は何もしないので、本番に開発ページは出ません。ただし、1つのファイルにまとめるバンドラー(Workers の wrangler など)では、コードが入ったままなのでサイズは減りません
どのリクエストに開発用の出力をするかは、NODE_ENV で決まります。
NODE_ENV |
開発用の出力 |
|---|---|
production |
しない(devtools() は何もしない) |
development / test |
全部のリクエスト |
未設定・それ以外(staging など) |
localhost へのリクエストだけ |
- 「localhost へのリクエスト」は、リクエストの URL のホスト名が
localhost(127.0.0.1・[::1]・*.localhostを含む)で、かつ接続元がループバック(同じ PC)のときです。Node.js・Bun・Deno では、URL のホスト名はHostヘッダーから作られ、だれでも付けられるので、接続元も見ます(接続元はapp.fetchの2つ目の引数から取ります。ダッシュボードと同じです) - それ以外のリクエストには、本番と同じ固定の文言だけを返し、エラーページ・ルートの一覧・
Server-Timingは出しません。そうしたリクエストが初めて来たときに、1回だけその旨をログに出します - Docker の中で動かしてホストのブラウザから開くとき、同じ LAN の別の機器(スマートフォンなど)から開くとき、
localhost以外のホスト名で開くときは、NODE_ENV=developmentを付けてください。bun testはNODE_ENV=testを入れるので、テストでは全部に出ます - 同じ PC のリバースプロキシの裏では、プロキシが
Host: localhostをそのまま転送すると、localhost へのリクエストに見えてしまいます。本番ではNODE_ENV=productionにするか、devtools()を外してください
Cloudflare Workers とブラウザ(Service Worker)では NODE_ENV が読めないので、いつも localhost へのリクエストだけです。ここでは URL をプラットフォームが決めるので、URL のホスト名だけを見ます。
- Workers では、本番の Worker に
localhostのリクエストは届かない(Cloudflare は登録されたドメインのリクエストしか渡さない)ので、wrangler dev(localhost:8787)のときだけ有効になります - ブラウザでは、開発中のサイト(
localhost)のときだけ有効になります - それでも、本番のビルドからは外すのが確実です。消し忘れても漏れないようにするための、念のための仕組みです
Deno では、NODE_ENV を読む許可(--allow-env=NODE_ENV)がないと本番かどうか分からないので、devtools() は無効になり、その旨を1行出します。
0.1 の createApp({ dev: true }) は、0.2 からエラーになります(CHANGELOG に移行方法があります)。
ダッシュボードの記録とセキュリティについて:
- 記録はメモリ上だけで、再起動すると消えます。
/_senri自体へのリクエストと、リクエストやレスポンスのボディは記録しません authorization・cookie・set-cookieや、名前にtoken・secret・session・api-keyなどを含むヘッダーとクエリは***に伏せます- 同じ PC(localhost)からしか開けません。 接続元がループバックで、かつ
Hostもlocalhostなどのときだけです。それ以外は/_senriがないものとして扱います(ふつうの 404) - 接続元は
app.fetchの2つ目の引数から取ります。fetch: (req) => app.fetch(req)のように包むと渡らないので、(req, info) => app.fetch(req, info)としてください - Docker などのコンテナの中で動かすと、接続元が localhost に見えないので、ダッシュボードは開けません
import * as api from "@opentelemetry/api";
import { otel } from "@senrijs/senri/otel";
app.use(otel({ api, middlewareSpans: true })); // いちばん先に登録するmiddlewareSpans: true の 1 つで、開発モードの玉ねぎタイムラインが、そのまま本番のトレースになります。 ミドルウェアごと(middleware <名前>)とハンドラー(handler GET /users/:id)の span が、動いた順に入れ子で並びます。どの層で時間がかかったか、どの層で例外が起きたか(その span がエラーになります)を、Jaeger や Grafana Tempo などで見られます。見え方の例です(時間は例です)。
GET /users/:id ████████████████████ 12.3 ms
└ middleware logger ███████████████████ 12.1 ms
└ middleware auth ██████████████ 9.0 ms
└ handler GET /users/:id ███████████ 7.2 ms
- Senri は OpenTelemetry に依存しません。使っている
@opentelemetry/apiを渡してください。送り先(エクスポーター)や SDK の設定は、いつもどおり OpenTelemetry の側で行います - リクエストごとの server span: 名前はルートのパターン(
GET /users/:id。ルートがなければGET)。属性は HTTP の semantic conventions(http.request.method・http.route・http.response.status_code・url.path・url.scheme・server.address・user_agent.original)。受け取ったtraceparentのトレースを続けます - 5xx と、ミドルウェアやハンドラーの例外は、span をエラーにして例外を記録します。4xx はエラーにしません
- context manager(Node.js などの
AsyncLocalStorage)があれば、ハンドラーの中で作った span は Senri の server span の子になります middlewareSpansは既定でオフです(層ごとに span を作るぶん、送るデータが増えるため)。otel()より前に登録したミドルウェアは、子 span になりません- Bun・Deno・Node.js・Cloudflare Workers・ブラウザで動きます。
tracerを省くとapi.trace.getTracer("@senrijs/senri")を使います
import { metrics, metricsHandler } from "@senrijs/senri/metrics";
app.use(metrics()); // いちばん先に、1 回だけ
app.use("/metrics", ipRestriction({ allow: ["10.0.0.0/8"] })); // /metrics は守る(ルートや流量が見えるので)
app.get("/metrics", metricsHandler()); // Prometheus のテキスト形式| メトリクス | 種類 | ラベル |
|---|---|---|
http_server_request_duration_seconds |
histogram(既定のバケットは 5 ms〜10 s。metrics({ buckets }) で変えられる) |
method・route・status |
http_server_active_requests |
gauge(処理中の数) | method |
- ラベルの数が増えすぎないよう、
routeはパスではなくルートのパターンです(/users/42ではなく/users/:id)。ルートがなかったもの(404 など)はunmatched、標準でないメソッドは_OTHERにまとめます - 時間は、
metrics()に入ってからレスポンスを返すまでです(ストリームの本文は、まだ送っている途中のことがあります)。例外はonErrorが返した status(500 など)で数えます - 記録はプロセスのメモリです。Cloudflare Workers では isolate ごとに別々になるので、全体の数にはなりません
- 今は HTTP のメトリクスだけです。自分のカウンターなどを足す仕組みはありません
Hono 4.13.13・Elysia 1.4.30 と、同じルート(12 個)・同じリクエストで比べました。どれも本番モード、ミドルウェアなし、ハンドラーはテキストを返すだけです。手順とコードは bench/ にあり、だれでも同じものを動かせます。
計測した環境: Intel N100(4 コア)、Windows 11、Bun 1.4.3。ほかのアプリも動いているふだん使いの PC で、数字は回によって 1〜2 割ほどぶれます。
ネットワークを通さず、Request を渡してから Response の本文を読み終えるまで。bun run fetch(mitata 1.0.34)。
| リクエスト | Senri | Hono | Elysia |
|---|---|---|---|
静的(/user) |
1.63 µs | 0.90 µs | 0.58 µs |
| 静的・長い | 1.57 µs | 1.41 µs | 0.81 µs |
| パラメーター1つ | 3.00 µs | 1.60 µs | 0.90 µs |
| パラメーター3つ | 3.12 µs | 1.95 µs | 1.24 µs |
| 404 | 4.97 µs | 3.56 µs | 1.01 µs |
この計測では、Senri は3つの中でいちばん遅く、Hono の 1.1〜1.9 倍の時間がかかっています。理由の一部は分かっています。
- Senri は、どのランタイムでも同じになるよう、テキストの
Content-Typeを自分で付けます。Hono と Elysia はnew Response(text)でランタイムに任せます - Elysia は登録したルートからコードを生成して最適化します。Senri は Cloudflare Workers でも動くよう、
new Function/evalを使いません
3 つとも同じ Bun.serve({ fetch }) で動かし、oha 1.16.0 で負荷をかけました(oha -z 10s -c 64、交互に 3 回ずつ測った中央値)。ベンチは今は wrk で測る形に変えたので、ベンチ用の VM で測り直した結果に置き換える予定です。
| リクエスト | Senri | Hono | Elysia |
|---|---|---|---|
静的(/user) |
21,703 | 17,167 | 14,447 |
| パラメーター1つ | 16,390 | 17,461 | 21,516 |
| パラメーター3つ | 19,426 | 23,692 | 12,186 |
| 404 | 22,349 | 23,030 | 24,761 |
負荷をかける側も同じ PC で動いているので、サーバーそのものの処理が大半を占めます。この条件では 3 つとも同じくらいの範囲に入り、どれが速いとは言い切れません。順位は回によって入れ替わります。
examples/ に、Bun・Deno・Node.js・Cloudflare Workers(workerd)で同じアプリを動かす例があります。
bun run dev # Bun(保存すると再起動)
cd examples/deno && deno task start # Deno
node examples/node/index.ts # Node.js- これからの予定は ROADMAP.ja.md にあります
- 開発のしかたは CONTRIBUTING.md、変更点は CHANGELOG.md にあります
- 0.2.x から 0.3.0 に上げるときに書き換えるところは、0.3.0 への移行(English)にあります
MIT © 2026 ibuki-hum4
Senri のロゴ(.github/assets/ の画像)は、MIT ライセンスの対象外です。