0.3.0 への移行
0.2.x から 0.3.0 に上げるときに、書き換えるところ
0.3.0 には、壊れる変更が 3 つのまとまりで入っています。
| まとまり | 実行時の動き | 影響する人 |
|---|---|---|
| 本文の大きさの既定の上限 | 変わる | 1 MiB を超える本文を受けるルートがある人。multipart() で合計 100 MiB を超えて受ける人。Bun の 128 MiB の上限を頼りにしていた人 |
| 公開をやめたもの | 変わらない(import がエラーになる) | parseCookies などを直接 import している人 |
| 型の変更 | 変わらない(型だけ) | RouteTable を自分で書いている人。型付きクライアントの結果の型を書いている人 |
まず確かめること
実行時の動きが変わるのは、本文の上限だけです。1 MiB を超える本文(大きい JSON、ファイルのアップロード、c.req.body をそのまま流すルートなど)を受けるルートを探して、下の書き換えをしてください。ほかの 2 つは、型チェック(tsc)でエラーになる場所を直せば終わりです。
本文の大きさの既定の上限
| 変わること | 0.2.x | 0.3.0 |
|---|---|---|
本文を読むもの(c.body()・ルートの body のスキーマ・c.req.json() / text() / formData() / arrayBuffer()、c.req.body を自分でストリームとして読むとき)の上限 | なし | 1 MiB。超えたら 413 |
multipart() の maxTotalSize の既定 | なし | 100 MiB |
Bun の serve() の本文の上限 | 128 MiB(Bun.serve の既定) | なし(Node.js・Deno とそろえる) |
- 上限は、本文を読んだときだけかかります。本文を読まないルートは、大きい本文が来ても今までどおりです
- Content-Length が上限より大きければ、中身を読まずに 413 にします。Content-Length のない本文(チャンク転送など)は、読みながら数えて、超えたところで 413 にします
- ハンドラーが読み取りのエラーを
try/catchで握りつぶしても、応答は 413 になります
大きい本文を受けるルートに上限を付ける
ルートに bodyLimit({ maxSize }) を付けると、そのルートでは既定の 1 MiB の代わりに、その上限が使われます(2 つの上限が重なるのではなく、置き換わります)。
app.post("/import", async (_, c) => {
const rows = await c.req.json(); // 何 MiB でも読めた
return { count: rows.length };
});import { bodyLimit } from "@senrijs/senri";
app.use("/import", bodyLimit({ maxSize: 20 * 1024 * 1024 })); // このルートだけ 20 MiB まで
app.post("/import", async (_, c) => {
const rows = await c.req.json();
return { count: rows.length };
});defineRoutes() の表のルートなら、endpoint() の use に書けます。
import { bodyLimit, defineRoutes, endpoint } from "@senrijs/senri";
export const routes = defineRoutes({
"POST /import": endpoint({ use: [bodyLimit({ maxSize: 20 * 1024 * 1024 })] }, async (_, c) => {
const rows = await c.req.json();
return { count: rows.length };
}),
});uploadLimit() も中で bodyLimit() を使うので、uploadLimit({ maxTotalSize }) を付けたルートは、その maxTotalSize まで受け取れます。
c.req.body をストリームとして流すルート
c.req.body を自分で読んで、保存先などへそのまま流すルートにも、1 MiB の上限がかかります(Content-Length があってもなくても)。大きい本文を流すルートには、bodyLimit({ maxSize }) を付けてください。
app.put("/files/:name", async ({ name }, c) => {
await saveStream(name, c.req.body!); // 保存先へ流す(例)
return new Response(null, { status: 201 });
});import { bodyLimit } from "@senrijs/senri";
app.use("/files/:name", bodyLimit({ maxSize: 5 * 1024 * 1024 * 1024 })); // 5 GiB まで
app.put("/files/:name", async ({ name }, c) => {
await saveStream(name, c.req.body!);
return new Response(null, { status: 201 });
});bodyLimit()のmaxSizeは、有限の数で書きます。上限をまったく付けたくないときは、次のcreateApp({ maxBodySize: Infinity })を使いますmultipart()は自分の上限を使うので、bodyLimit()は要りません(下)
アプリ全体の上限を変える
アプリ全体で上限を変えるなら、createApp({ maxBodySize }) です。Infinity で、0.2.x と同じく上限なしになります。
const app = createApp({ maxBodySize: 10 * 1024 * 1024 }); // アプリ全体で 10 MiB まで
// const app = createApp({ maxBodySize: Infinity }); // 上限なし(0.2.x と同じ)Content-Length のない本文は、数えるためにストリームで包むので、読むのが少し遅くなります(小さい本文で数十 µs)。Content-Length のある本文は包まないので、速さは変わりません。気になる場合は maxBodySize: Infinity で外せます。
multipart() の合計の上限
multipart() の maxTotalSize(本文全体の上限)の既定が、上限なしから 100 MiB になりました。合計で 100 MiB を超えて受け取るなら、maxTotalSize を書きます。
for await (const part of multipart(c, { maxFileSize: 50 * 1024 * 1024 })) {
// 50 MiB のファイルを何個でも受け取れた
}for await (const part of multipart(c, { maxFileSize: 50 * 1024 * 1024, maxTotalSize: 500 * 1024 * 1024 })) {
// 合計 500 MiB まで
}maxTotalSizeを書かずにmaxFileSizeを 100 MiB より大きくしたときは、合計の上限もmaxFileSizeに合わせます(1 つのファイルが受け取れなくなることはありません)multipart()は、既定の 1 MiB の代わりに自分の上限を使います。bodyLimit()を付ける必要はありません
Bun の serve() の 128 MiB
Bun の serve() は、これまで Bun.serve の既定のまま、本文を 128 MiB で切っていました。0.3.0 では、Node.js・Deno とそろえて、サーバー全体の上限を付けません(守りは、既定の 1 MiB とルートごとの上限です)。
serve(app, { maxRequestBodySize: 1024 * 1024 * 1024 });serve(app); // 書かなくても、Bun で 128 MiB で切られないサーバー全体の上限が要るときは、今までどおり serve(app, { maxRequestBodySize }) を書きます。こちらは、超えたら接続を閉じます。
公開をやめたもの
意図せず公開していたものを、入口から外しました。import するとエラーになるので、代わりのものに書き換えます。
| 外したもの | 入口 | 代わり |
|---|---|---|
parseCookies(header) | @senrijs/senri/cookie | getCookie(c)(全部)・getCookie(c, name)(1 つ) |
serializeCookie(name, value, options) | @senrijs/senri/cookie | setCookie(c, name, value, options) |
deletionCookie(name, options) | @senrijs/senri/cookie | deleteCookie(c, name, options) |
resolvePort()・DEFAULT_PORT・PortSource | @senrijs/senri/serve | serve() がポートを決める(port → 環境変数 PORT → 3927)。決まった番号は server.port |
isLocalUrl(url) | @senrijs/senri/dev | なし(new URL(url).hostname を自分で見る) |
Cookie
import { deletionCookie, parseCookies, serializeCookie } from "@senrijs/senri/cookie";
app.get("/theme", (_, c) => {
const cookies = parseCookies(c.req.headers.get("cookie"));
c.header("set-cookie", serializeCookie("theme", "dark", { path: "/" }));
c.header("set-cookie", deletionCookie("old", { path: "/" }));
return cookies.theme ?? "light";
});import { deleteCookie, getCookie, setCookie } from "@senrijs/senri/cookie";
app.get("/theme", (_, c) => {
const theme = getCookie(c, "theme"); // 全部なら getCookie(c)
setCookie(c, "theme", "dark", { path: "/" });
deleteCookie(c, "old", { path: "/" });
return theme ?? "light";
});setCookie() の既定は Path=/・HttpOnly・SameSite=Lax です。serializeCookie() で付けていた属性と同じになるか、確かめてください。
ポート
import { resolvePort, serve } from "@senrijs/senri/serve";
const { port } = resolvePort(undefined);
serve(app, { port });
console.log(`http://localhost:${port}`);import { serve } from "@senrijs/senri/serve";
const server = await serve(app); // port → PORT → 3927 の順で決まる
console.log(server.url); // 番号だけなら server.port型の変更
実行時の動きは変わりません。型チェックでエラーになったところを直します。
| 変わること | 影響する人 |
|---|---|
RouteTable<K, V> が RouteTable<T, V> になる(キーの型ではなく、表の型を受け取る) | RouteTable<...> を自分で型注釈に書いている人 |
app.routes() の型引数の書き方が 1 つになる | app.routes<"GET /x">(...) のように型引数を書いている人 |
c.json() / c.text() の戻り値の型が TypedResponse(Response を受け継ぐ型)になる | ほぼいない。Response としてそのまま使えます |
型付きクライアントの結果の型が、status ごとに分かれる(ClientResultOf) | 結果の型を ClientResult<D> と書いている人。ok: true の status を 2xx 以外と比べている人 |
RouteTable
import type { RouteTable } from "@senrijs/senri";
const table: RouteTable<"GET /users/:id" | "POST /users"> = {
"GET /users/:id": ({ id }) => ({ id }),
"POST /users": () => "created",
};
app.routes(table);いちばん簡単なのは、app.routes() に表をその場で書くか、defineRoutes() を使うことです。どちらもパスからパラメーターの型が付きます。
import { defineRoutes } from "@senrijs/senri";
const table = defineRoutes({
"GET /users/:id": ({ id }) => ({ id }), // id の型はパスから
"POST /users": () => "created",
});
app.routes(table);型注釈がどうしても要るときは、RouteTable<typeof table> と表の型を渡します。
app.routes() の型引数
app.routes<"GET /hello">({ "GET /hello": () => "hi" });app.routes({ "GET /hello": () => "hi" }); // 型引数は書かない型付きクライアントの結果
c.json(body, status) や endpoint({ responses }) で書いた status ごとに、error の型が付くようになりました。ok: true の結果の status は 2xx の型(SuccessStatus)になります。
import type { ClientResult } from "@senrijs/senri/client";
const res: ClientResult<User> = await api("GET /users/:id", { params: { id: "1" } });
if (res.ok) res.data;
else res.error; // unknownimport type { ClientResultOf } from "@senrijs/senri/client";
const res: ClientResultOf<typeof routes, "GET /users/:id"> = await api("GET /users/:id", { params: { id: "1" } });
if (res.ok) res.data; // User
else if (res.status === 404) res.error; // c.json({ message }, 404) で返した型
else res.error; // unknown(書いていない status)型注釈を外して、api() の戻り値の型に任せるのがいちばん簡単です。ClientResult<D> は残してあるので、自分で使っている分にはそのまま使えます。
c.json() / c.text() の戻り値の型
TypedResponse<T, S, F> は Response を受け継ぐので、Response として扱っているコードはそのままです。ReturnType<typeof c.json> を Response と完全に一致するか比べる、というような型のテストだけ直してください。
変更点の一覧
細かい変更は CHANGELOG にあります。