サーバーとランタイム
HTTP kernel は独自のサーバーを必要としません。同じコントローラーを持つ同じアプリが、Deepkit Framework サーバー、独自の Node.js サーバー、Express や Fastify の中、Bun、Deno、Cloudflare Workers の fetch ハンドラーの背後、そして AWS Lambda で動作します。
| エントリーポイント | 用途 |
|---|---|
FrameworkModule | 完全なアプリケーション:サーバー、ワーカー、HTTPS、圧縮、CLI、デバッガー |
kernel.handleRequestMaybeSync(req, res) | 独自の node:http / node:https サーバー |
kernel.createMiddleware() | Express、Connect、Fastify(@fastify/middie 使用)への Deepkit ルートのマウント |
kernel.fetch(request) | Bun.serve、Deno.serve、Cloudflare Workers、その他 Web 標準の Request/Response ハンドラーを持つすべての環境 |
createLambdaHandler(kernel) | API Gateway(HTTP API および REST API)、Function URL、Application Load Balancer の背後の AWS Lambda |
すべての例は次のアプリを使用します:
import { App } from '@deepkit/app'; import { http, HttpBody, HttpKernel, HttpModule } from '@deepkit/http'; import { MinLength } from '@deepkit/type'; class UserController { @http.GET('/hello') hello() { return { hello: 'world' }; } @http.POST('/user') create(body: HttpBody<{ name: string & MinLength<3> }>) { return { id: 1, name: body.name }; } } const app = new App({ controllers: [UserController], imports: [new HttpModule()], }); const kernel = app.get(HttpKernel);
Deepkit Framework サーバー
FrameworkModule を使用すると、サーバーはすでに組み込まれており、server:start で起動します。HTTPS、圧縮、複数のワーカープロセス、グレースフルシャットダウン、HTTP アクセスログ、デバッガーが含まれています。
import { FrameworkModule } from '@deepkit/framework'; new App({ controllers: [UserController], imports: [new FrameworkModule({ port: 8080, compression: 6, workers: 4, })], }).run();
ts-node app.ts server:start
独自の Node.js サーバー
リクエストオブジェクトを変換する必要がないように、Deepkit のリクエストクラスを createServer に渡します:
import { createServer } from 'http'; import { HttpRequest, HttpResponse } from '@deepkit/http'; createServer( { IncomingMessage: HttpRequest, ServerResponse: HttpResponse as any }, (req, res) => kernel.handleRequestMaybeSync(req, res), ).listen(8080);
handleRequestMaybeSync は、リクエストが非同期で処理される場合(例えば async コントローラーの場合)にのみ promise を返します。handleRequest は常に promise を返します。
Express、Fastify など
createMiddleware は Connect スタイルのミドルウェアを返します。fallThroughOnNotFound を使用すると、一致する Deepkit ルートがないリクエストは 404 で応答される代わりに次のミドルウェアに渡されます。
import express from 'express'; const server = express(); server.use(kernel.createMiddleware({ fallThroughOnNotFound: true })); server.get('/legacy', (req, res) => res.send('handled by express')); server.listen(8080);
Fetch ハンドラー
kernel.fetch(request) は Web 標準の Request を受け取り、Response を返します。同期ルートの場合、Response は promise なしで直接返されます。
Bun
Bun.serve({ port: 8080, fetch: request => kernel.fetch(request), });
Bun の node:http 互換レイヤーではなく Bun.serve を使用してください。リクエストあたりの CPU 時間が約半分になります。パフォーマンスを参照してください。
Deno
Deno.serve({ port: 8080 }, request => kernel.fetch(request));
Cloudflare Workers
Workers には nodejs_compat フラグが必要です:
# wrangler.toml compatibility_date = "2026-01-01" compatibility_flags = ["nodejs_compat"]
Workers では、コード生成(new Function)はワーカーの起動中にのみ許可され、リクエストの処理中には許可されません。Deepkit はルーター、バリデーター、シリアライザーを JavaScript にコンパイルするため、モジュールレベルで kernel.warmUp() を呼び出してください。これにより、リクエストに必要なものがすべて事前にコンパイルされます:
const kernel = app.get(HttpKernel); kernel.warmUp(); export default { fetch: (request: Request) => kernel.fetch(request), };
ファイルアップロード(ファイルを含む multipart/form-data)は Workers ではサポートされていません。アップロードされたファイルは一時ファイルに書き込まれますが、Workers にはファイルシステムがないためです。
AWS Lambda
createLambdaHandler は kernel を Lambda ハンドラーに変換します。API Gateway HTTP API および Function URL のイベント(ペイロード形式 2.0)と、REST API および Application Load Balancer のイベント(ペイロード形式 1.0)を読み取り、バイナリボディを base64 エンコードして返します。
import { createLambdaHandler } from '@deepkit/http'; const kernel = app.get(HttpKernel); // 最初の呼び出し時ではなく、Lambda の init フェーズ中にコンパイルする kernel.warmUp(); export const handler = createLambdaHandler(kernel);
アプリは Lambda インスタンスごとに一度作成され、その後そのインスタンスのすべての呼び出しを処理します。
Node.js サーバーとの違い
- リクエストボディは、ルートが呼び出される前に完全に読み込まれます。JSON ボディはテキストとして読み込まれます。
- レスポンスは終了した時点で送信されます。返されたストリームは収集され、1 つのボディとして送信されます。
- クライアントのアドレスは Web 標準の
Requestには含まれていません。request.getRemoteAddress()が必要な場合は、オプションとして渡してください。createLambdaHandlerはイベントからアドレスを取得します。
// Bun Bun.serve({ fetch: (request, server) => kernel.fetch(request, { remoteAddress: server.requestIP(request)?.address }), }); // Deno Deno.serve((request, info) => kernel.fetch(request, { remoteAddress: info.remoteAddr.hostname }));
HttpRequestとHttpResponseはその API(headers、setHeader、writeHead、readBody()など)を維持しているため、コントローラー、リスナー、ミドルウェアは変更なしで動作します。
warmUp()
Deepkit は、各ルートのパラメーター解析、バリデーション、シリアライズを最初に必要になった時点でコンパイルします。kernel.warmUp() はこれをすべてのルートに対して事前に行います:
- 起動時にのみコード生成を許可する Cloudflare Workers では必須
- 最初のリクエストの前に init フェーズが実行される Lambda やその他のサーバーレスプラットフォームでは推奨
- 長時間稼働するサーバーでは、ルートごとの最初のリクエストのレイテンシーを解消
サーバーなしでのテスト
どちらの方法でも、ネットワークを使わずに完全なリクエスト処理を実行します:
import { HttpRequest } from '@deepkit/http'; const response = await kernel.request(HttpRequest.POST('/user').json({ name: 'Peter' })); expect(response.json).toEqual({ id: 1, name: 'Peter' }); const fetched = await kernel.fetch(new Request('http://localhost/hello')); expect(await fetched.json()).toEqual({ hello: 'world' });