Statum/frontend-demo/server.php

<?php
/**
 * Statum frontend demo backend.
 *
 * Run from this directory with PHP's built-in server:
 *
 *     php -S localhost:8000 server.php
 *
 * Then open http://localhost:8000/ in your browser.
 *
 * This is a DEMO only: there is no real signing or encryption. Snapshots are
 * wrapped in trivial frames, and per-item action context is carried in the
 * action's `private` blob as plain base64. State lives in the PHP session so
 * that actions are stateful across requests.
 */

session_start();

// Static product catalog used by the demo.
$CATALOG = [
    ['id' => 1, 'name' => 'Widget',  'price' => 9.99,  'featured' => true,  'inStock' => true],
    ['id' => 2, 'name' => 'Gadget',  'price' => 19.99, 'featured' => false, 'inStock' => true],
    ['id' => 3, 'name' => 'Sprocket', 'price' => 4.50, 'featured' => false, 'inStock' => false],
    ['id' => 4, 'name' => 'Gizmo',   'price' => 29.99, 'featured' => true,  'inStock' => true],
];

$TYPES = ['counter', 'products', 'cart', 'user', 'notice'];

// ---------------------------------------------------------------------------
// Helpers
// ---------------------------------------------------------------------------

/** Send a JSON array of Statum directives and stop. */
function statum_respond(array $directives): void
{
    header('Content-Type: application/vnd.statum+json');
    header('Cache-Control: no-store');
    echo json_encode($directives, JSON_PRETTY_PRINT);
    exit;
}

/** Wrap a snapshot in a trivial (unsigned) frame. The signature is a SHA256
 *  hash of the content so that identical snapshots share a signature (used by
 *  the client as an idempotency key) while distinct ones do not. */
function frame(array $snapshot): array
{
    $content = json_encode($snapshot);
    return [
        'content' => $content,
        'signer' => 'demo',
        'signature' => base64_encode(hash('sha256', $content, true)),
    ];
}

/** Stable per-type slot key, kept in the session. */
function key_for(string $type): string
{
    if (!isset($_SESSION['keys'][$type])) {
        $_SESSION['keys'][$type] = 'k_' . $type;
    }
    return $_SESSION['keys'][$type];
}

/**
 * Build a snapshot for a type. Options:
 *  - `always`: transmit_after == as_at, so the client sends the base64 frame on
 *    every request (the always-send path).
 *  - `stale`: transmit_after is set 10s in the future (with a far-future
 *    invalid_after). The slot is fresh for 10s, after which the client must
 *    pre-flight via /_statum/slots before each request. Load the page, wait ~10s,
 *    then trigger an action to see the pre-flight request.
 */
function make_snapshot(string $type, string $scope, array $public, array $opts = []): array
{
    $now = time();
    $asAt = gmdate('Y-m-d\TH:i:s\Z', $now);
    if (!empty($opts['always'])) {
        $transmit = $asAt;
    } elseif (!empty($opts['stale'])) {
        $transmit = gmdate('Y-m-d\TH:i:s\Z', $now + 10);
    } else {
        $transmit = gmdate('Y-m-d\TH:i:s\Z', $now + 60);
    }
    return [
        'as_at' => $asAt,
        'slot' => ['key' => key_for($type), 'scope' => $scope, 'type' => $type],
        'transmit_after' => $transmit,
        'invalid_after' => gmdate('Y-m-d\TH:i:s\Z', $now + 600),
        'private' => $opts['private'] ?? '',
        'public' => $public,
    ];
}

function set_dir(array $snapshot): array
{
    return ['type' => 'set', 'snapshot_frame' => frame($snapshot)];
}

function clear_dir(string $key): array
{
    return ['type' => 'clear', 'key' => $key];
}

function product_by_id($id): ?array
{
    global $CATALOG;
    foreach ($CATALOG as $p) {
        if ((string)$p['id'] === (string)$id) return $p;
    }
    return null;
}

// ---------------------------------------------------------------------------
// Public-data builders
// ---------------------------------------------------------------------------

function build_counter(): array
{
    $v = $_SESSION['counter'] ?? 0;
    return [
        'value' => $v,
        'high' => $v > 5,
        'increment' => ['uri' => '/api/counter/inc', 'method' => 'POST'],
        'decrement' => ['uri' => '/api/counter/dec', 'method' => 'POST'],
        'reset' => ['uri' => '/api/counter/reset', 'method' => 'POST'],
        'add' => ['uri' => '/api/counter/add', 'method' => 'POST'],
    ];
}

function build_products(): array
{
    global $CATALOG;
    $items = [];
    foreach ($CATALOG as $p) {
        $pid = (string)$p['id'];
        $items[] = [
            'id' => $pid,
            'name' => $p['name'],
            'price' => $p['price'],
            'featured' => $p['featured'],
            'inStock' => $p['inStock'],
            // Per-item context rides in `private`; the client echoes it back
            // via the X-Statum-Private header (no stm-data expression needed).
            'addToCartAction' => [
                'uri' => '/api/cart/add',
                'method' => 'POST',
                'private' => base64_encode('id=' . $pid),
            ],
        ];
    }
    return ['items' => $items];
}

function build_cart(): array
{
    $cart = $_SESSION['cart'] ?? [];
    $count = 0;
    $total = 0.0;
    $lines = [];
    foreach ($cart as $id => $qty) {
        $p = product_by_id($id);
        if (!$p) continue;
        $count += $qty;
        $total += $p['price'] * $qty;
        $lines[] = ['id' => (string)$id, 'name' => $p['name'], 'qty' => $qty, 'price' => $p['price']];
    }
    return [
        'count' => $count,
        'total' => round($total, 2),
        'empty' => $count === 0,
        'items' => $lines,
        'checkoutAction' => ['uri' => '/api/cart/checkout', 'method' => 'POST'],
        'clearAction' => ['uri' => '/api/cart/clear', 'method' => 'POST'],
    ];
}

function build_user(): array
{
    $role = $_SESSION['role'] ?? 'guest';
    $names = ['guest' => 'Guest', 'member' => 'Member Mike', 'admin' => 'Admin Alice'];
    return [
        'role' => $role,
        'name' => $names[$role] ?? 'Guest',
        'toggleAction' => ['uri' => '/api/user/toggle', 'method' => 'POST'],
        'resetAllAction' => ['uri' => '/api/reset-all', 'method' => 'POST'],
    ];
}

function build_notice(): array
{
    return [
        'html' => $_SESSION['notice'] ?? '<em>No notice set.</em>',
        'setAction' => ['uri' => '/api/notice/set', 'method' => 'POST'],
        'failAction' => ['uri' => '/api/notice/fail', 'method' => 'POST'],
    ];
}

/** Build the snapshot for a type with its demo scope/options. */
function snap(string $type): ?array
{
    switch ($type) {
        case 'counter':  return make_snapshot('counter', 'session', build_counter());
        case 'products': return make_snapshot('products', 'session', build_products());
        case 'cart':     return make_snapshot('cart', 'session', build_cart(), ['always' => true]);
        case 'user':     return make_snapshot('user', 'session', build_user(), ['stale' => true]);
        case 'notice':   return make_snapshot('notice', 'flow', build_notice());
    }
    return null;
}

function all_directives(): array
{
    global $TYPES;
    $dirs = [];
    foreach ($TYPES as $t) {
        $s = snap($t);
        if ($s) $dirs[] = set_dir($s);
    }
    return $dirs;
}

// ---------------------------------------------------------------------------
// Router
// ---------------------------------------------------------------------------

$method = $_SERVER['REQUEST_METHOD'];
$path = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);

// Static assets.
if ($path === '/statum.js') {
    header('Content-Type: application/javascript');
    readfile(__DIR__ . '/../js/statum.js');
    exit;
}

// The page itself.
if ($path === '/' || $path === '/index.html') {
    header('Content-Type: text/html; charset=utf-8');
    readfile(__DIR__ . '/index.html');
    exit;
}

// Landing page after a (post) checkout navigation.
if ($path === '/api/checkout-done') {
    header('Content-Type: text/html; charset=utf-8');
    $order = htmlspecialchars($_GET['order'] ?? 'UNKNOWN');
    echo "<!doctype html><meta charset=utf-8><title>Checkout</title>" .
         "<body style='font-family:sans-serif;padding:2rem'>" .
         "<h1>Order $order placed</h1><p>This page was reached via a statum <code>post</code> directive.</p>" .
         "<p><a href='/'>Back to the demo</a></p>";
    exit;
}

// --- Statum endpoints -------------------------------------------------------

if ($path === '/_statum/entrypoint') {
    statum_respond(all_directives());
}

if ($path === '/_statum/slots') {
    // Pre-flight target: refresh each type whose frame the client sent back.
    $body = json_decode(file_get_contents('php://input'), true);
    $dirs = [];
    if (is_array($body)) {
        foreach ($body as $fr) {
            $snap = json_decode($fr['content'] ?? 'null', true);
            $type = $snap['slot']['type'] ?? null;
            if ($type) {
                $s = snap($type);
                if ($s) $dirs[] = set_dir($s);
            }
        }
    }
    statum_respond($dirs);
}

// --- Actions ----------------------------------------------------------------

if ($path === '/api/counter/inc' && $method === 'POST') {
    $_SESSION['counter'] = ($_SESSION['counter'] ?? 0) + 1;
    statum_respond([set_dir(snap('counter'))]);
}

if ($path === '/api/counter/dec' && $method === 'POST') {
    $_SESSION['counter'] = ($_SESSION['counter'] ?? 0) - 1;
    statum_respond([set_dir(snap('counter'))]);
}

if ($path === '/api/counter/reset' && $method === 'POST') {
    $_SESSION['counter'] = 0;
    statum_respond([set_dir(snap('counter'))]);
}

if ($path === '/api/counter/add' && $method === 'POST') {
    $amount = intval($_POST['amount'] ?? 1);
    $_SESSION['counter'] = ($_SESSION['counter'] ?? 0) + $amount;
    statum_respond([set_dir(snap('counter'))]);
}

if ($path === '/api/cart/add' && $method === 'POST') {
    $priv = $_SERVER['HTTP_X_STATUM_PRIVATE'] ?? '';
    $raw = base64_decode($priv, true) ?: '';
    if (preg_match('/id=([0-9]+)/', $raw, $m)) {
        $id = $m[1];
        $_SESSION['cart'][$id] = ($_SESSION['cart'][$id] ?? 0) + 1;
    }
    statum_respond([set_dir(snap('cart'))]);
}

if ($path === '/api/cart/clear' && $method === 'POST') {
    $_SESSION['cart'] = [];
    statum_respond([set_dir(snap('cart'))]);
}

if ($path === '/api/cart/checkout' && $method === 'POST') {
    // A `post` directive performs a full-page navigating form POST last.
    statum_respond([['type' => 'post', 'uri' => '/api/checkout-done', 'data' => ['order' => 'ORD-' . strtoupper(bin2hex(random_bytes(3)))]]]);
}

if ($path === '/api/user/toggle' && $method === 'POST') {
    $order = ['guest', 'member', 'admin'];
    $cur = array_search($_SESSION['role'] ?? 'guest', $order);
    $_SESSION['role'] = $order[($cur + 1) % count($order)];
    statum_respond([set_dir(snap('user'))]);
}

if ($path === '/api/notice/set' && $method === 'POST') {
    $_SESSION['notice'] = '<div class="ok"><strong>Notice:</strong> updated at ' . date('H:i:s') . '</div>';
    statum_respond([set_dir(snap('notice'))]);
}

if ($path === '/api/notice/fail' && $method === 'POST') {
    statum_respond([['type' => 'error', 'message' => 'Intentional failure.', 'code' => 'DEMO_FAIL', 'data' => ['at' => date('c')]]]);
}

if ($path === '/api/reset-all' && $method === 'POST') {
    $dirs = [];
    foreach ($TYPES as $t) {
        if (isset($_SESSION['keys'][$t])) $dirs[] = clear_dir($_SESSION['keys'][$t]);
    }
    session_unset();
    $dirs[] = ['type' => 'navigate', 'uri' => '/'];
    statum_respond($dirs);
}

// Fallback 404.
http_response_code(404);
header('Content-Type: text/plain');
echo "404 Not Found: $path";