Crate chipzen_bot

Expand description

§chipzen-bot

Build, test, and deploy poker bots for the Chipzen competition platform.

Implement the Bot trait, return Actions from Bot::decide, call run_bot — the SDK handles the WebSocket connection, the two-layer protocol handshake, ping/pong, request_id echoing, action_rejected retries, and reconnect.

use chipzen_bot::{Bot, Action, GameState, run_bot, RunBotOptions};

struct MyBot;

#[async_trait::async_trait]
impl Bot for MyBot {
    fn decide(&mut self, state: &GameState) -> Action {
        if state.valid_actions.iter().any(|a| a == "check") {
            Action::Check
        } else {
            Action::Fold
        }
    }
}

let url = std::env::var("CHIPZEN_WS_URL").unwrap();
let _match_end = run_bot(&url, MyBot, RunBotOptions::default()).await?;

To run a bot on the external-API remote-play path (your machine, the platform matches and dispatches you), use run_external_bot with a cz_extbot_ token — see its docs.

See the docs/protocol/ docs in the chipzen-sdk repo for the full two-layer protocol specification, and the IP-PROTECTION.md for what the starter Dockerfile does to your release binary.

Structs§

ActionHistoryEntry: One entry from state.action_history. Synthetic blind/ante entries (post_small_blind, post_big_blind, post_ante) appear here too — the server generates them; bots do not submit them.
Card: A standard playing card.
ChipzenConfig: Parsed contents of a chipzen.toml file.
ConformanceCheck: One conformance scenario’s verdict.
ConnectionConfig: Fully-resolved connection parameters ready for crate::run_external_bot.
GameState: Built from the server’s turn_request message. The parser in parse_game_state converts the wire-format snake_case to the owned-string fields below.
MatchResult: One per-match result collected during a session.
RetryPolicy: Backoff knobs applied to reconnect attempts.
RunBotOptions: Optional knobs for run_bot. Defaults match the platform’s expectations.
RunConformanceOptions: Optional knobs for run_conformance_checks.
RunExternalArgs: Parsed run-external flags, mirroring the Python CLI (--env/--token/--bot-id/--max-matches/--no-safe-mode).
RunExternalOptions: Options for run_external_bot. Mirrors the Python kwargs.
SessionContext: Opaque per-session bag the session loop threads through. Public so the conformance harness can construct one.

Enums§

Action: The action a bot returns from crate::Bot::decide.
ActionKind: The five action kinds a bot can take. Matches the wire action strings byte-for-byte.
ConformanceSeverity: Severity of a single conformance verdict. Same shape as chipzen_sdk::Severity; the CLI renders them uniformly.
EnvName: One of the three recognized Chipzen environments.
Error: Top-level error type for SDK operations. Variants describe the failure surface in terms users care about (connect failed, server dropped us mid-handshake, peer sent something unparseable) rather than transport internals.

Constants§

BOT_TOKEN_SUBPROTOCOL: Sentinel subprotocol that marks the cz_extbot_ token in the Sec-WebSocket-Protocol header (CZ issue 2932 moved the token off the query string, where it leaked into proxy access logs). Must match the value the platform’s api gateway expects.
CHIPZEN_ENV_VAR: Name of the environment variable consulted when env is not explicitly passed.
CONFIG_FILENAME: The config-file name searched for on the discovery path.
ENV_NAMES: Recognized environment names. Kept as a constant so error messages can list the valid values and the env-var path can validate at runtime.
SCENARIO_NAMES: The set of conformance scenario names registered with run_conformance_checks. Listed in the order they’re executed. Useful for downstream tooling that wants to enumerate scenarios without parsing CLI output.
SECTION_NAME: The TOML table the SDK reads its settings from.
SUPPORTED_PROTOCOL_VERSIONS: Protocol versions this client claims to support in the handshake.

Traits§

Bot: User-implementable poker bot.
MessageReader: Pull-based async iterator over inbound messages. Real impl wraps tokio_tungstenite::WebSocketStream; the conformance harness provides a scripted impl.
MessageWriter: Push-based async sender for outbound messages.

Functions§

bot_token_subprotocols: Build the Sec-WebSocket-Protocol offer that carries the bot token: [sentinel, token]. The sentinel marks “the next value is my bot token”; the api gateway extracts the token from this header (so it never appears in any access log / URL) and echoes the sentinel back on accept.
connect_to_chipzen: Resolve a ConnectionConfig for the external-API lobby.
default_retry_policy: The default RetryPolicy used when a run_* entry point is called without an explicit policy: 5 attempts, 500ms initial backoff doubling to a 30s cap.
default_user_agent: Default User-Agent header sent on the WebSocket handshake. A non-default UA also clears the platform’s Cloudflare bot-fight rule (chipzen-ai/chipzen-sdk#46).
discover_config_path: Return the first existing chipzen.toml on the search path, or None.
load_chipzen_config: Discover and parse a chipzen.toml from the search path.
parse_card: Parse a card from its 2-character wire form (e.g. "Ah"). Mirrors the Python and JavaScript helpers of the same name; equivalent to s.parse::<Card>().
parse_game_state: Parse a turn_request envelope into a GameState.
resolve_gateway_url: Resolve the matched.gateway_ws_url path against the lobby origin.
resolve_token: Return the token to use, honoring precedence:
resolve_url: Return the URL override to use, honoring precedence:
run_bot: Connect a bot to the Chipzen server and play until the match ends.
run_conformance_checks: Drive bot through every conformance scenario and return per-check verdicts. The bot instance is consumed (passed by value) — matches the production usage shape where run_bot also takes ownership.
run_external_bot: Run a bot on the Chipzen external-API remote-play path.
run_external_cli: The Rust equivalent of the chipzen run-external CLI: resolve config + env URL + token from args (and a discovered chipzen.toml), then run factory’s bot via run_external_bot.