エントリ種別リファレンス

Wippyで利用可能なすべてのエントリ種別の完全なリファレンス。

エントリはnamespace:name形式で相互参照します。レジストリはこれらの参照に基づいて依存関係を自動的に接続し、リソースが正しい順序で初期化されることを保証します。

Luaランタイム

種別	説明
`function.lua`	Lua関数エントリポイント
`process.lua`	長時間実行Luaプロセス
`workflow.lua`	Temporalワークフロー（決定論的）
`library.lua`	共有Luaライブラリ
`module.lua`	Luaモジュールインターフェース
`function.lua.bc`	プリコンパイル済み関数バイトコード
`library.lua.bc`	プリコンパイル済みライブラリバイトコード
`process.lua.bc`	プリコンパイル済みプロセスバイトコード
`workflow.lua.bc`	プリコンパイル済みワークフローバイトコード

- name: handler
  kind: function.lua
  source: file://handler.lua
  method: main
  modules:
    - http
    - json
  imports:
    utils: app.lib:helpers  # 別のエントリをモジュールとしてインポート

importsを使用して他のLuaエントリを参照します。コード内でrequire("alias_name")を通じて利用可能になります。

HTTPサービス

種別	説明
`http.service`	HTTPサーバー（ポートをバインド）
`http.router`	ルートプレフィックスとミドルウェア
`http.endpoint`	HTTPエンドポイント（メソッド + パス）
`http.static`	静的ファイル配信

# HTTPサーバー
- name: gateway
  kind: http.service
  addr: ":8080"
  lifecycle:
    auto_start: true

# ミドルウェア付きルーター
- name: api
  kind: http.router
  meta:
    server: gateway
  prefix: /api
  middleware:
    - cors
    - rate_limit

# エンドポイント
- name: users_list
  kind: http.endpoint
  meta:
    router: app:api
  method: GET
  path: /users
  func: list_handler

Lua API: HTTPモジュールを参照

local http = require("http")
local req = http.request()
local resp = http.response()

resp:status(200):json({users = get_users()})

データベース

種別	説明
`db.sql.sqlite`	SQLiteデータベース
`db.sql.postgres`	PostgreSQLデータベース
`db.sql.mysql`	MySQLデータベース

SQLite

- name: database
  kind: db.sql.sqlite
  file: "./data/app.db"
  lifecycle:
    auto_start: true

# テスト用インメモリ
- name: testdb
  kind: db.sql.sqlite
  file: ":memory:"

PostgreSQL

- name: database
  kind: db.sql.postgres
  host: localhost
  port: 5432
  database: dbname
  username: user
  password: pass
  options:
    sslmode: disable
  pool:
    max_open: 25
    max_idle: 5
    max_lifetime: "30m"
  lifecycle:
    auto_start: true

MySQL

- name: database
  kind: db.sql.mysql
  host: localhost
  port: 3306
  database: dbname
  username: user
  password: pass
  options:
    parseTime: "true"
  lifecycle:
    auto_start: true

*_env サフィックスのバリアント、TLSオプション、接続プールの調整についてはDatabaseを参照してください。

Lua API: SQLモジュールを参照

local sql = require("sql")
local db, err = sql.get("app:database")

local rows, err = db:query("SELECT * FROM users WHERE id = ?", user_id)
db:execute("INSERT INTO logs (msg) VALUES (?)", message)

キーバリューストア

種別	説明
`store.memory`	インメモリキーバリューストア
`store.sql`	SQLバックエンドキーバリューストア
`store.kv.raft`	クラスタレプリケート、強整合性 KV（共有 Raft）
`store.kv.crdt`	クラスタレプリケート、最終的整合性 KV（ゴシップ/CRDT）

# メモリストア
- name: cache
  kind: store.memory
  lifecycle:
    auto_start: true

# SQLバックエンドストア
- name: persistent_store
  kind: store.sql
  database: app:database
  table: kv_store
  lifecycle:
    auto_start: true

# クラスタレプリケートストア（クラスタリングが必要）
- name: deployments
  kind: store.kv.raft
  namespace: deploy

store.kv.* 種別はクラスタリングが有効である必要があります。整合性のトレードオフについてはストアを参照。

Lua API: ストアモジュールを参照

local store = require("store")
local s, err = store.get("app:cache")

s:set("user:123", user_data, 3600)  -- TTL（秒）
local data = s:get("user:123")

キュー

種別	説明
`queue.driver.memory`	インメモリキュードライバ
`queue.driver.amqp`	AMQP (RabbitMQ) ドライバ
`queue.driver.sqs`	AWS SQS ドライバ
`queue.queue`	キュー宣言
`queue.consumer`	キューコンシューマ

# ドライバ
- name: queue_driver
  kind: queue.driver.memory
  lifecycle:
    auto_start: true

# キュー
- name: jobs
  kind: queue.queue
  driver: queue_driver

# コンシューマ
- name: job_consumer
  kind: queue.consumer
  queue: app:jobs
  func: job_handler
  concurrency: 4
  prefetch: 10
  lifecycle:
    auto_start: true

Lua API: キューモジュールを参照

local queue = require("queue")

-- メッセージを公開
queue.publish("app:jobs", {task = "process", id = 123})

-- コンシューマハンドラ内で現在のメッセージにアクセス
local msg = queue.message()
local data = msg:body_json()

コンシューマのfuncは各メッセージに対して呼び出されます。ハンドラ内でqueue.message()を使用して現在のメッセージにアクセスします。

プロセス管理

種別	説明
`process.host`	プロセス実行ホスト
`process.service`	監督されたプロセス（process.luaをラップ）
`terminal.host`	ターミナル/CLIホスト

# プロセスホスト（プロセスが実行される場所）
- name: processes
  kind: process.host
  host:
    workers: 32             # ワーカーgoroutine（デフォルト: NumCPU）
    queue_size: 1024        # グローバルキュー容量
    local_queue_size: 256   # ワーカーごとのキュー
  lifecycle:
    auto_start: true

# プロセス定義
- name: worker_process
  kind: process.lua
  source: file://worker.lua
  method: main

# 監督されたプロセスサービス
- name: worker
  kind: process.service
  process: app:worker_process
  host: app:processes
  input: ["arg1", "arg2"]
  lifecycle:
    auto_start: true
    restart:
      max_attempts: 10

- name: terminal
  kind: terminal.host
  lifecycle:
    auto_start: true

プロセスを自動再起動付きの監督されたサービスとして実行する必要がある場合はprocess.serviceを使用します。processフィールドはprocess.luaエントリを参照します。

Temporal（ワークフロー）

種別	説明
`temporal.client`	Temporalクライアント接続
`temporal.worker`	Temporalワーカー

- name: temporal_client
  kind: temporal.client
  address: "localhost:7233"
  namespace: "default"
  auth:
    type: none  # none, api_key, mtls
  lifecycle:
    auto_start: true

- name: temporal_worker
  kind: temporal.worker
  client: temporal_client
  task_queue: "main-queue"
  lifecycle:
    auto_start: true

クラウドストレージ

種別	説明
`config.aws`	AWS設定
`cloudstorage.s3`	S3バケットアクセス

- name: aws
  kind: config.aws
  region: "us-east-1"
  access_key_id_env: "AWS_ACCESS_KEY_ID"
  secret_access_key_env: "AWS_SECRET_ACCESS_KEY"

- name: uploads
  kind: cloudstorage.s3
  config: app:aws
  bucket: "my-uploads"
  endpoint: ""  # オプション、S3互換サービス用

Lua API: クラウドストレージモジュールを参照

local cloudstorage = require("cloudstorage")
local storage, err = cloudstorage.get("app:uploads")

storage:upload_object("files/doc.pdf", file_content)
local url = storage:presigned_get_url("files/doc.pdf", {expires = "1h"})

MinIOやDigitalOcean SpacesなどのS3互換サービスに接続するにはendpointを使用します。

ファイルシステム

種別	説明
`fs.directory`	ディレクトリアクセス
`fs.embed`	読み取り専用組み込みファイルシステム

- name: data_dir
  kind: fs.directory
  directory: "./data"
  auto_init: true   # 存在しない場合は作成
  mode: "0755"      # パーミッション

Lua API: ファイルシステムモジュールを参照

local fs = require("fs")
local filesystem, err = fs.get("app:data_dir")

local file = filesystem:open("output.txt", "w")
file:write("Hello, World!")
file:close()

環境変数

種別	説明
`env.storage.memory`	インメモリ環境変数ストレージ
`env.storage.file`	ファイルベース環境変数ストレージ
`env.storage.os`	OS環境変数
`env.storage.static`	読み取り専用の静的キーバリューストレージ
`env.storage.router`	環境変数ルーター（複数ストレージ）
`env.variable`	環境変数

- name: os_env
  kind: env.storage.os

- name: file_env
  kind: env.storage.file
  file_path: ".env"
  auto_create: true

- name: defaults
  kind: env.storage.static
  values:
    PUBLIC_API_HOST: "https://api.example.com"
    APP_ENV: "production"

- name: app_env
  kind: env.storage.router
  storages:
    - app:os_env
    - app:file_env
    - app:defaults

Lua API: Envモジュールを参照

local env = require("env")

local api_key = env.get("API_KEY")
env.set("CACHE_TTL", "3600")

ルーターはストレージを順番に試行します。読み取りは最初のマッチが勝ちます。書き込みは最初の書き込み可能なストレージに送られます。

テンプレート

種別	説明
`template.jet`	個別のJetテンプレート
`template.set`	テンプレートセット設定

# エンジン設定付きテンプレートセット
- name: templates
  kind: template.set
  engine:
    development_mode: false
    extensions:
      - ".jet"
      - ".html.jet"

# 個別テンプレート
- name: email_template
  kind: template.jet
  source: file://templates/email.jet
  set: app:templates

Lua API: テンプレートモジュールを参照

local templates = require("templates")
local set, err = templates.get("app:templates")

local html = set:render("email", {
    user = "Alice",
    message = "Welcome!"
})

セキュリティ

種別	説明
`security.policy`	条件付きセキュリティポリシー
`security.policy.expr`	式ベースのポリシー
`security.token_store`	トークンストレージ

# 条件ベースのポリシー
- name: admin_policy
  kind: security.policy
  policy:
    actions: "*"
    resources: "*"
    effect: allow
    conditions:
      - field: "actor.meta.role"
        operator: eq
        value: "admin"

# 式ベースのポリシー
- name: owner_policy
  kind: security.policy.expr
  policy:
    actions: "*"
    resources: "*"
    effect: allow
    expression: 'actor.id == meta.owner_id || actor.meta.role == "admin"'

Lua API: セキュリティモジュールを参照

local security = require("security")

-- アクション前に権限をチェック
if security.can("delete", "users", {user_id = id}) then
    delete_user(id)
end

-- 現在のアクターを取得
local actor = security.actor()

ポリシーは順番に評価されます。最初にマッチしたポリシーがアクセスを決定します。より具体的なポリシーを一般的なポリシーの前に配置してください。

コントラクト（依存性注入）

種別	説明
`contract.definition`	メソッド仕様を持つインターフェース
`contract.binding`	コントラクトメソッドを関数実装にマップ

# コントラクトインターフェースを定義
- name: greeter
  kind: contract.definition
  methods:
    - name: greet
      description: 挨拶メッセージを返す
    - name: greet_with_name
      description: パーソナライズされた挨拶を返す
      input_schemas:
        - format: "application/schema+json"
          definition: {"type": "string"}
      output_schemas:
        - format: "application/schema+json"
          definition: {"type": "string"}

# 実装関数
- name: greeter_greet
  kind: function.lua
  source: file://greeter_greet.lua
  method: main

- name: greeter_greet_name
  kind: function.lua
  source: file://greeter_greet_name.lua
  method: main

# コントラクトメソッドを実装にバインド
- name: greeter_impl
  kind: contract.binding
  contracts:
    - contract: app:greeter
      default: true
      methods:
        greet: app:greeter_greet
        greet_with_name: app:greeter_greet_name

Luaからの使用：

local contract = require("contract")

-- IDでバインディングを開く
local greeter, err = contract.open("app:greeter_impl")

-- メソッドを呼び出す
local result = greeter:greet()
local personalized = greeter:greet_with_name("Alice")

-- インスタンスがコントラクトを実装しているかチェック
local is_greeter = contract.is(greeter, "app:greeter")

Lua API: コントラクトモジュールを参照

1つのバインディングをdefault: trueとしてマークすると、バインディングIDを指定せずにコントラクトを開くときに使用されます（context_requiredフィールドが設定されていない場合のみ動作）。

実行

種別	説明
`exec.native`	ネイティブコマンド実行
`exec.docker`	Dockerコンテナ実行

- name: native_exec
  kind: exec.native
  default_work_dir: "/app"
  command_whitelist:
    - "ls"
    - "cat"

- name: docker_exec
  kind: exec.docker
  image: "python:3.11-slim"
  default_work_dir: "/workspace"
  auto_remove: true
  memory_limit: 536870912  # 512MB
  command_whitelist:
    - "python"

WASMランタイム

種別	説明
`function.wat`	WebAssembly関数（WATテキスト形式）
`function.wasm`	WebAssembly関数（バイナリ）
`process.wasm`	WebAssemblyプロセス

- name: sum
  kind: function.wasm
  source: file://sum.wasm
  transport: payload   # または wasi-http

WASM概要を参照。

ネットワーク

種別	説明
`network`	ベースネットワークオーバーレイ
`network.socks5`	SOCKS5プロキシオーバーレイ
`network.i2p`	I2Pネットワークオーバーレイ
`network.tailscale`	Tailscaleオーバーレイ

http.service からは network: 経由で、funcs/process からは network オプション経由で、http_client からは overlay_network オプション経由で参照されます。ネットワークを参照。

レジストリプリミティブ

種別	説明
`registry.entry`	エントリ記述子（内部）
`ns.definition`	名前空間定義
`ns.requirement`	名前空間要件宣言
`ns.dependency`	名前空間依存関係

これらはレジストリローダーが_index.yamlのフロントマターと依存関係宣言から生成します。通常、作者が直接定義することはありません — version:、namespace:、依存ブロックが解決された結果として現れます。

ライフサイクル設定

ほとんどのエントリはライフサイクル設定をサポートします：

- name: service
  kind: some.kind
  lifecycle:
    auto_start: true          # 自動起動
    start_timeout: 10s        # 最大起動時間
    stop_timeout: 10s         # 最大シャットダウン時間
    stable_threshold: 5s      # 安定とみなす時間
    depends_on:
      - app:database
    restart:                  # リトライポリシー
      initial_delay: 1s
      max_delay: 90s
      backoff_factor: 2.0
      max_attempts: 0         # 0 = 無限

エントリが正しい順序で起動することを保証するにはdepends_onを使用します。スーパーバイザは依存先のエントリを起動する前に、依存関係が安定するのを待ちます。

エントリ参照形式

エントリはnamespace:name形式で参照されます：

# 定義
namespace: app.users
entries:
  - name: handler
    kind: function.lua

# 別のエントリからの参照
func: app.users:handler

エントリの上書き {id=“overriding-entries”}

任意のエントリのフィールド（その kind を含む）は、ソース YAML を編集することなく、override: 設定セクションまたは -o CLI フラグを使って起動時に上書きできます。キーは namespace:entry:path 形式を使用します。

override:
  app:gateway:addr: ":9090"        # data field (a bare path targets data.*)
  app:worker:meta.priority: high    # meta field
  app:db:kind: db.sql.postgres      # the entry's typed kind
  app:db:data.kind: custom          # a payload field literally named "kind"

パス	対象
`kind`	エントリの型付き kind（空でない文字列である必要があります）
`data.<field>` または素の `<field>`	エントリの data ペイロード内のフィールド
`meta.<field>`	エントリのメタデータ内のフィールド

同じ上書きを CLI からも適用できます。

wippy run -o app:db:kind=db.sql.postgres -o app:gateway:addr=:9090

CLI（-o）の値は形状に応じて型変換されます（true/false は bool、数値は数値、それ以外は文字列）。override: セクションの値は YAML の型を保持します。エントリではなくグローバルな設定セクションを上書きするには、--set を使用します。

エントリ種別リファレンス

エントリ種別リファレンス

関連項目

Luaランタイム

HTTPサービス

データベース

SQLite

PostgreSQL

MySQL

キーバリューストア

キュー

プロセス管理

Temporal（ワークフロー）

クラウドストレージ

ファイルシステム

環境変数

テンプレート

セキュリティ

コントラクト（依存性注入）

実行

WASMランタイム

ネットワーク

レジストリプリミティブ

ライフサイクル設定

エントリ参照形式

エントリの上書き {id=“overriding-entries”}