Cloudflare WorkersにNode.js HTTPサーバーを導入

このコンテンツは自動機械翻訳サービスによる翻訳版であり、皆さまの便宜のために提供しています。原本の英語版と異なる誤り、省略、解釈の微妙な違いが含まれる場合があります。ご不明な点がある場合は、英語版原本をご確認ください。

node:httpクライアントとサーバーAPIのサポートを追加することで、Cloudflare Workers上でNode.jsアプリケーションをより簡単に実行できるようになります。この大幅な追加により、使い慣れたNode.js HTTPインターフェースがエッジで使用され、既存のExpress.js、Koa、およびその他のNode.jsアプリケーションを、ゼロコールドスタート、自動スケーリング、そしてユーザーの遅延の大幅な低減を実現します。そのすべてをコードベースを書き換えることもありません。レガシーアプリケーションを最新のサーバーレスプラットフォームに移行する場合も、既存のAPIを使用して新しいアプリケーションを構築する場合も、既存の開発パターンやフレームワークを維持しながら、Workersのグローバルネットワークを活用することができます。

Cloudflare Workersは、直接TCP接続が利用できない独自のサーバーレス環境で動作します。その代わり、すべてのネットワーキングオペレーションは、Workersランタイム自体の外にある特殊サービスによって完全に管理されます。Open Egress Router（OER）やPingoraなどのシステムで、接続プーリング、接続をウォーム、エグレスIPの管理、複雑なネットワークの詳細をすべて処理します。つまり、開発者がTLSネゴシエーション、接続管理、ネットワーク最適化について心配する必要は、すべて自動的に処理されるということです。

この完全管理されたアプローチは、実際には特定のNode.js APIをサポートできない理由です。これらのネットワークの決定は、パフォーマンスとセキュリティのためにシステムレベルで処理されます。この点が、Workersを従来のNode.js環境とは異なる点にしていますが、サーバーレスコンピューティングにも適しています。複雑化せずにエンタープライズグレードのネットワークを手に入れることができます。

この根本的な違いにより、既存のNode.jsコードパターンと互換性を維持しながら、エッジでHTTP APIがどのように動作するかを再考する必要がありました。

当社のソリューション：Workersがすでに優れているWeb標準技術の上に構築することで、コア`node:http` APIを実装しました。仕組みは次のとおりです。

node:httpクライアント実装には、ご存じの重要なAPIが含まれます。

• http.get() - シンプルなGETリクエストの場合

• http.request() - HTTPリクエストを完全に制御するために

これらのAPIの実装は、Workersがネイティブに使用する標準fetch() APIの上に構築されており、Node.jsの互換性を維持しながら優れたパフォーマンスを提供します。

import http from 'node:http';

export default {
  async fetch(request) {
    // Use familiar Node.js HTTP client APIs
    const { promise, resolve, reject } = Promise.withResolvers();

    const req = http.get('https://api.example.com/data', (res) => {
      let data = '';
      res.on('data', chunk => data += chunk);
      res.on('end', () => {
        resolve(new Response(data, {
          headers: { 'Content-Type': 'application/json' }
        }));
      });
    });

    req.on('error', reject);

    return promise;
  }
};

• Standard HTTPメソッド（GET、POST、PUT、DELETEなど）

• リクエストヘッダーとレスポンスヘッダー

• リクエスト本文とレスポンス本文

• ストリーミング応答

• Basic認証

• エージェントAPIは提供されていますが、ノーオペレーションとして動作します。

• トレーラー、初期のヒント、および1xxレスポンスはサポートされません。

• TLS固有のオプションはサポートされません（TLSはWorkersによって自動的に処理されます）。

サーバー側の実装で、特に興味深いことがわかります。Workersは特定のポートでリッスンする従来のTCPサーバーを作成できないため、Node.jsスタイルのサーバーをWorkersのリクエスト処理モデルに接続するブリッジシステムを作成しました。

HTTPサーバーを作成してlisten(port)を呼び出すと、TCPソケットを開く代わりに、サーバーはWorker内の内部テーブルに登録されます。この内部テーブルは、http.createServerと識別子としてポート番号を使って、着信フェッチリクエストの実行や次に、2つの方法のいずれかを使用して、Workerの受信リクエストをNode.jsスタイルサーバーにブリッジします。

このアプローチは、Node.js HTTPサーバーを他のWorker機能と統合できる柔軟性を提供し、デフォルトのエントリーポイントにfetch、 scheduled 、queueなど複数のハンドラーを持つことができます。

import { handleAsNodeRequest } from 'cloudflare:node';
import { createServer } from 'node:http';

// Create a traditional Node.js HTTP server
const server = createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('Hello from Node.js HTTP server!');
});

// Register the server (doesn't actually bind to port 8080)
server.listen(8080);

// Bridge from Workers fetch handler to Node.js server
export default {
  async fetch(request) {
    // You can add custom logic here before forwarding
    if (request.url.includes('/admin')) {
      return new Response('Admin access', { status: 403 });
    }

    // Forward to the Node.js server
    return handleAsNodeRequest(8080, request);
  },
  async queue(batch, env, ctx) {
    for (const msg of batch.messages) {
      msg.retry();
    }
  },
  async scheduled(controller, env, ctx) {
    ctx.waitUntil(doSomeTaskOnSchedule(controller));
  },
};

このアプローチは、次のことを必要とする場合に最適です。

• KV、Durable Objects、またはR2など他のWorkers機能と統合

• 一部のルートをNode.jsサーバーに委任する一方で、

• カスタムミドルウェアやリクエスト処理を適用する

追加機能や複雑性なしにNode.js HTTPサーバーを統合したい場合には、`httpServerHandler` 関数を使用できます。この関数は、統合を自動的に処理します。このソリューションは、Workers固有の機能を必要としないアプリケーションに最適です。

import { httpServerHandler } from 'cloudflare:node';
import { createServer } from 'node:http';

// Create your Node.js HTTP server
const server = createServer((req, res) => {
  if (req.url === '/') {
    res.writeHead(200, { 'Content-Type': 'text/html' });
    res.end('<h1>Welcome to my Node.js app on Workers!</h1>');
  } else if (req.url === '/api/status') {
    res.writeHead(200, { 'Content-Type': 'application/json' });
    res.end(JSON.stringify({ status: 'ok', timestamp: Date.now() }));
  } else {
    res.writeHead(404, { 'Content-Type': 'text/plain' });
    res.end('Not Found');
  }
});

server.listen(8080);

// Export the server as a Workers handler
export default httpServerHandler({ port: 8080 });
// Or you can simply pass the http.Server instance directly:
// export default httpServerHandler(server);

これらのHTTP APIが、Workers上でExpress.jsのような人気のNode.jsフレームワークを実行することを可能にします。これらのフレームワークのミドルウェアのいずれかが期待通りに機能しない場合は、Cloudflare Workersリポジトリに問題を開いてください。

import { httpServerHandler } from 'cloudflare:node';
import express from 'express';

const app = express();

app.get('/', (req, res) => {
  res.json({ message: 'Express.js running on Cloudflare Workers!' });
});

app.get('/api/users/:id', (req, res) => {
  res.json({
    id: req.params.id,
    name: 'User ' + req.params.id
  });
});

app.listen(3000);
export default httpServerHandler({ port: 3000 });
// Or you can simply pass the http.Server instance directly:
// export default httpServerHandler(app.listen(3000));

Express.jsに加えて、Koa.jsもサポートされています：

import Koa from 'koa';
import { httpServerHandler } from 'cloudflare:node';

const app = new Koa()

app.use(async ctx => {
  ctx.body = 'Hello World';
});

app.listen(8080);

export default httpServerHandler({ port: 8080 });

node:httpとnode:httpsのAPIは、Node.jsとの互換性が有効になっているWorkersで利用可能です。nodejs_compat互換性フラグを使用して、互換性の日付が2025年8月15日までに指定されています。

node:httpサポートの追加により、新しいアプリケーションの構築でも、既存のアプリケーションの移行でも、Cloudflare WorkersをエッジでJavaScriptを実行するための最高のプラットフォームにするという当社の目標に近づきます。

試されますか？WorkerでNode.jsの互換性を有効化し、エッジで使い慣れたHTTP APIの可能性を模索し始めましょう。