本文へ移動
Senri

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.x0.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 つの上限が重なるのではなく、置き換わります)。

前(0.2.x)
app.post("/import", async (_, c) => {
    const rows = await c.req.json();   // 何 MiB でも読めた
    return { count: rows.length };
});
後(0.3.0)
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 に書けます。

後(0.3.0)— 表のルート
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 }) を付けてください。

前(0.2.x)
app.put("/files/:name", async ({ name }, c) => {
    await saveStream(name, c.req.body!);   // 保存先へ流す(例)
    return new Response(null, { status: 201 });
});
後(0.3.0)
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 を書きます。

前(0.2.x)
for await (const part of multipart(c, { maxFileSize: 50 * 1024 * 1024 })) {
    // 50 MiB のファイルを何個でも受け取れた
}
後(0.3.0)
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 とルートごとの上限です)。

前(0.2.x)— 128 MiB を超えるアップロードのために上げていた
serve(app, { maxRequestBodySize: 1024 * 1024 * 1024 });
後(0.3.0)
serve(app);   // 書かなくても、Bun で 128 MiB で切られない

サーバー全体の上限が要るときは、今までどおり serve(app, { maxRequestBodySize }) を書きます。こちらは、超えたら接続を閉じます。

公開をやめたもの

意図せず公開していたものを、入口から外しました。import するとエラーになるので、代わりのものに書き換えます。

外したもの入口代わり
parseCookies(header)@senrijs/senri/cookiegetCookie(c)(全部)・getCookie(c, name)(1 つ)
serializeCookie(name, value, options)@senrijs/senri/cookiesetCookie(c, name, value, options)
deletionCookie(name, options)@senrijs/senri/cookiedeleteCookie(c, name, options)
resolvePort()・DEFAULT_PORT・PortSource@senrijs/senri/serveserve() がポートを決める(port → 環境変数 PORT → 3927)。決まった番号は server.port
isLocalUrl(url)@senrijs/senri/devなし(new URL(url).hostname を自分で見る)
前(0.2.x)
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";
});
後(0.3.0)
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() で付けていた属性と同じになるか、確かめてください。

ポート

前(0.2.x)
import { resolvePort, serve } from "@senrijs/senri/serve";

const { port } = resolvePort(undefined);
serve(app, { port });
console.log(`http://localhost:${port}`);
後(0.3.0)
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

前(0.2.x)
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() を使うことです。どちらもパスからパラメーターの型が付きます。

後(0.3.0)
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() の型引数

前(0.2.x)
app.routes<"GET /hello">({ "GET /hello": () => "hi" });
後(0.3.0)
app.routes({ "GET /hello": () => "hi" });   // 型引数は書かない

型付きクライアントの結果

c.json(body, status) や endpoint({ responses }) で書いた status ごとに、error の型が付くようになりました。ok: true の結果の status は 2xx の型(SuccessStatus)になります。

前(0.2.x)
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;   // unknown
後(0.3.0)
import 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 にあります。

このページの内容