本文へ移動
Senu English

操作を宣言する

約 5 分で読めます

操作は、名前・説明・権限・文字列パラメータを持つ読み取り専用の関数です。定数として一度だけ宣言し、到達させたい場所の一覧に載せます。

操作は何でできていますか

このページの例は、小さな在庫サービス examples/inventory.rs から取っています。最初の操作は品目を 1 つ調べます。

pub const GET_STOCK: Operation<Inventory, Level> = Operation {
    name: "get_stock",
    description: "Units in stock for one SKU of the caller's warehouse.",
    permission: VIEW_STOCK,
    params: &[Param::required(
        "sku",
        "The SKU: 1 to 16 characters of A-Z, 0-9 and '-'.",
    )],
    run: Run::Async(|inventory, caller, args| Box::pin(get_stock(inventory, caller, args))),
};

Senu はこのメタデータを、ルーターやツールの一覧を組み立てるときに検査します。不正な名前、空の説明、二重に宣言したパラメータは起動時のエラーになり、本番で初めて気づくことがありません。

関数はどう書きますか

関数は状態・呼び出し元・引数を受け取り、Serialize を実装した結果か OpError を返します。

#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct StockArgs {
    sku: String,
}

async fn get_stock(
    inventory: &Inventory,
    caller: &Principal,
    args: &Args,
) -> Result<Level, OpError> {
    let StockArgs { sku } = decode(args)?;
    let well_formed = (1..=16).contains(&sku.len())
        && sku
            .bytes()
            .all(|b| b.is_ascii_uppercase() || b.is_ascii_digit() || b == b'-');
    if !well_formed {
        return Err(INVALID_SKU);
    }
    let levels = inventory.levels(caller).await?;
    levels
        .into_iter()
        .find(|level| level.sku == sku)
        .ok_or(OpError::NotFound)
}

安全に保つ習慣が 3 つあります。

  1. decode で、#[serde(deny_unknown_fields)] を付けた構造体に読み込みます。欠けた項目や型の違う項目は invalid_request になります。
  2. テナントは引数からではなく、呼び出し元から読みます。caller.tenant() は、サーバーがリクエストを認証したときに決めた値です。
  3. 存在しないものにも、別のテナントのものにも、同じ OpError::NotFound を返します。他のテナントのデータを探る手がかりを与えません。

操作はどんなエラーを返せますか

エラーHTTPJSON と MCP のコード意味
OpError::Forbidden403forbidden呼び出し元に権限がありません。関数が走る前に Senu が返します。
OpError::InvalidRequest400invalid_request引数が宣言したパラメータに合いません。
OpError::Invalid { code, phrase }400あなたの codeinvalid_sku のような、操作独自の検証エラーです。
OpError::NotFound404not_foundこの呼び出し元に見えるものの中に、該当がありません。
OpError::Internal500internalバックエンドが失敗しました。原因は自分でログに残します。呼び出し元には詳細を見せません。

コードも文言も固定の文字列なので、エラーが入力や秘密を繰り返すことはありません。/api/ の下では本文が {"error": "<code>"} になります。HTML のルートは文言をプレーンテキストで返します。MCP ツールは isError つきの結果に同じ JSON を入れて返します。

非同期の操作はどう動きますか

Run::Async に、Box に入れた future を返す関数を渡します。つなぎのコードは、上の宣言にあるクロージャ |inventory, caller, args| Box::pin(get_stock(inventory, caller, args)) だけです。関数の中ではデータベースのクライアントを await するか、ブロックする処理をエグゼキューターの外へ移します。

    async fn levels(&self, caller: &Principal) -> Result<Vec<Level>, OpError> {
        let (items, tenant) = (Arc::clone(&self.0), caller.tenant().clone());
        let read = move || {
            items
                .iter()
                .filter(|item| item.tenant == tenant)
                .map(|item| item.level.clone())
                .collect()
        };
        tokio::task::spawn_blocking(read)
            .await
            .map_err(|_| OpError::Internal)
    }

Run::Sync の関数は非同期エグゼキューターの上でそのまま走ります。メモリ上のデータを扱う処理に限ってください。ブロックしうるなら非同期にします。

操作はどう公開しますか

Endpoints の表とツールの一覧に載せます。載せたものだけが到達可能になります。

pub fn endpoints() -> Endpoints<Inventory> {
    Endpoints::new()
        .api("/api/stock", &GET_STOCK)
        .api("/api/low-stock", &LIST_LOW_STOCK)
        .html("/low-stock", &LIST_LOW_STOCK, low_stock_page)
        .asset(
            "/assets/inventory.css",
            "text/css; charset=utf-8",
            STYLESHEET,
        )
}

pub fn tools() -> Vec<McpTool<Inventory>> {
    vec![mcp::tool(&GET_STOCK), mcp::tool(&LIST_LOW_STOCK)]
}

into_router(state) は表の全体を検査し、axum::Router か、パスを名指しするエラーを返します。パスは完全一致で、重複せず、/_senu/ の外になければなりません。/_senu/ は Senu の組み込みスタイルシートのために予約されています。

検査はどの順序で走りますか

いつも同じです。上限、メソッド、認証、権限、パラメータの枠、そしてあなたの関数の順です。権限が検証より先にあることには意味があります。権限のない呼び出し元は、どの入力が有効だったかを何も知ることができません。契約テストは、この順序をあなたのルートで確かめます。

次のページ: 呼び出し元を認証する。