HTTPサーバー

HTTPサーバー

HTTPサーバー（http.service）はポートをリッスンし、ルーター、エンドポイント、静的ファイルハンドラをホストします。

設定

- name: gateway
  kind: http.service
  addr: ":8080"
  timeouts:
    read: "5s"
    write: "30s"
    idle: "60s"
  host:
    buffer_size: 1024
    worker_count: 4
  lifecycle:
    auto_start: true
    security:
      actor:
        id: "http-gateway"
      policies:
        - app:http_policy

フィールド	型	デフォルト	説明
addr	string	必須	リッスンアドレス（:8080、0.0.0.0:443）
timeouts.read	duration	-	リクエスト読み取りタイムアウト
timeouts.write	duration	-	レスポンス書き込みタイムアウト
timeouts.idle	duration	-	Keep-alive接続タイムアウト
host.buffer_size	int	1024	メッセージリレーのバッファサイズ
host.worker_count	int	NumCPU	メッセージリレーのワーカー数
network	Registry ID	-	ネットワークオーバーレイ（例: Tailscale、I2P）経由でリスナーをバインド
tls	object	-	TLS終端（TLSを参照）

タイムアウト

リソース枯渇を防ぐためにタイムアウトを設定します：

timeouts:
  read: "10s"    # リクエストヘッダ読み取りの最大時間
  write: "60s"   # レスポンス書き込みの最大時間
  idle: "120s"   # Keep-aliveタイムアウト

• read - API向けは短め（5-10秒）、アップロードは長め
• write - 想定されるレスポンス生成時間に合わせる
• idle - 接続再利用とリソース使用のバランス

Duration形式: 30s、1m、2h15m。無効化には0を使用。

Host設定

hostセクションは、WebSocketリレーなどのコンポーネントが使用するサーバー内部のメッセージリレーを設定します：

host:
  buffer_size: 2048
  worker_count: 8

フィールド	デフォルト	説明
buffer_size	1024	ワーカーごとのメッセージキュー容量
worker_count	NumCPU	メッセージ処理の並列goroutine数

高スループットのWebSocketアプリケーションではこれらの値を増やしてください。メッセージリレーはHTTPコンポーネントとプロセス間の非同期配信を処理します。

セキュリティ

HTTPサーバーにはlifecycle設定を通じてデフォルトのセキュリティコンテキストを適用できます：

lifecycle:
  auto_start: true
  security:
    actor:
      id: "gateway-service"
    policies:
      - app:http_access_policy

これにより、すべてのリクエストに対するベースラインのアクターとポリシーが設定されます。認証されたリクエストでは、token_authミドルウェアが検証済みトークンに基づいてアクターを上書きし、ユーザーごとのセキュリティポリシーを可能にします。

Lifecycle

サーバーはsupervisorによって管理されます：

lifecycle:
  auto_start: true
  start_timeout: 30s
  stop_timeout: 60s
  depends_on:
    - app:database

フィールド	説明
auto_start	アプリケーション起動時に開始
start_timeout	サーバー起動待機の最大時間
stop_timeout	グレースフルシャットダウンの最大時間
depends_on	これらのエントリが準備完了後に開始

コンポーネントの接続

ルーターと静的ハンドラはメタデータ経由でサーバーを参照します：

entries:
  - name: gateway
    kind: http.service
    addr: ":8080"

  - name: api
    kind: http.router
    meta:
      server: gateway
    prefix: /api

  - name: static
    kind: http.static
    meta:
      server: gateway
    path: /
    fs: app:public

複数のサーバー

異なる目的のために別々のサーバーを実行します：

entries:
  # パブリックAPI
  - name: public
    kind: http.service
    addr: ":8080"
    lifecycle:
      auto_start: true

  # 管理用（localhostのみ）
  - name: admin
    kind: http.service
    addr: "127.0.0.1:9090"
    lifecycle:
      auto_start: true

TLS

サーバーは直接TLS終端を行えます。tls.modeをmanual（自身の証明書を提供）またはauto（オーバーレイネットワークドライバが証明書を提供、例: network.tailscale）に設定します。通常のclearnetリスナーはautoをサポートしません。プレーンHTTPで実行するにはtlsを省略するかmodeを空のままにします。

autoモードではサーバーはcert/key/cert_env/key_envを指定してはいけません — ネットワークドライバが提供します。

手動証明書

certとkeyをインライン/ファイルから読み込むか、環境変数経由で提供します（両方は不可）：

- name: api
  kind: http.service
  addr: ":443"
  tls:
    mode: manual
    cert: file://./certs/server.pem
    key:  file://./certs/server.key

- name: api
  kind: http.service
  addr: ":443"
  tls:
    mode: manual
    cert_env: TLS_SERVER_CERT
    key_env:  TLS_SERVER_KEY

フィールド	説明
mode	""（オフ）、auto、またはmanual
cert / key	PEMコンテンツ（通常file://経由で読み込み）
cert_env / key_env	env registry経由で解決される環境変数名

Mutual TLS (mTLS)

mode: manualではサーバーはさらにクライアント証明書を検証できます：

tls:
  mode: manual
  cert_env: TLS_SERVER_CERT
  key_env:  TLS_SERVER_KEY
  client_ca: file://./certs/clients-ca.pem
  client_auth: require_and_verify

フィールド	説明
client_auth	request、require_any、verify_if_given、require_and_verify
client_ca	信頼するクライアントCAのPEMバンドル
client_ca_env	CAバンドルを保持する環境変数（client_caと相互排他）

verify_if_givenとrequire_and_verifyはCAが必要です。requestとrequire_anyはCA検証なしで任意のクライアント証明書を受け入れます。

関連項目

• ルーティング - ルーターとエンドポイント
• 静的ファイル - 静的ファイル配信
• ミドルウェア - 利用可能なミドルウェア
• セキュリティ - セキュリティポリシー
• WebSocketリレー - WebSocketメッセージング