Package lv.id.jc.dicechess.runtime

package lv.id.jc.dicechess.runtime
Transport runtime for DiceChess webhook bots.

A DiceChess bot is a small HTTP endpoint: the platform (play-api) delivers each turn as a signed HTTP request, and the bot answers with the moves it chooses. Everything in this package is the plumbing around that contract — HMAC-SHA256 signature verification (Signatures), the one-time ownership handshake and delivery orchestration (WebhookHandler), and (optionally) the HTTP server itself (CustomHandlerServer) — so a bot author supplies nothing but a move-choosing function.

The whole wiring for a bot's main method: 

Function<TurnContext, List<String>> strategy = ctx -> List.of("e2e4"); // your move logic
String secret = System.getenv("DICECHESS_WEBHOOK_SECRET");
WebhookHandler handler = new WebhookHandler(secret, strategy);
CustomHandlerServer.startFromEnvironment(handler);

Every public type here speaks only String, Long, java.util.List, and java.util.Map — no Gson type, and nothing library-specific, crosses the public boundary. A bot written in Kotlin or Scala calls this exactly like a Java bot would; the strategy itself is a plain java.util.function.Function, so a lambda, a method reference, or a Scala function converted via asJava all work unchanged.

Bots with no engine of their own

TurnContext.legalMoves carries every complete legal turn, already walked from the server's prefix tree — a strategy can pick straight from that list and never parse a DFEN or generate a move itself. The rare turn where the tree is too large to inline (the envelope carries null) falls back to GET /games/{id}/moves — a public, unauthenticated endpoint — if the WebhookHandler constructor that takes play-api's base URL was used; otherwise legalMoves is simply null on that turn, same as it always is when a strategy doesn't need it.

What is deliberately not here

DFEN parsing and independent move legality are still not this package's concern — it relays the server's own tree rather than recomputing one, so an engine-linked bot (like dicechess-bot-scala) is free to ignore legalMoves entirely and keep deriving moves from dfen itself. It also does not read or write an opening book itself; JsonFiles is a generic string-map loader a strategy can use for that, or for any similarly simple lookup table.

  • Class
    Description
    CustomHandlerServer
    A minimal HTTP server for the Azure Functions custom-handler model: one path, one WebhookHandler, no framework.
    JsonFiles
    Loads a JSON object of string keys to string values from a file — the shape an opening book, or any similarly simple lookup table, is exported as.
    Response
    An HTTP response for a webhook delivery: a status code and a JSON body, ready to write to whatever HTTP layer the caller is using.
    Signatures
    HMAC-SHA256 signing and verification for the DiceChess webhook delivery protocol.
    TurnContext
    What a strategy is told about the turn it must play — everything the webhook envelope's state carries that a move-choosing function plausibly needs, beyond the position itself.
    TurnContext.Clock
    The game clock as of this turn.
    WebhookHandler
    Orchestrates one webhook delivery: the ownership handshake, signature verification, and dispatch to the bot's move-choosing function.