// ============================================================================
// LISTEN - Start listening on a port
// ============================================================================
~pub event listen {
    port: u16
}
| listening { server: *ServerHandle }
| failed { msg: []const u8 }

// ============================================================================
// ACCEPT - Accept connection and parse HTTP request
// ============================================================================
~pub event accept {
    server: *ServerHandle
}
| request { req: *Request, conn: *ConnHandle, server: *ServerHandle }
| failed { msg: []const u8, server: *ServerHandle }

// ============================================================================
// SEND - Send HTTP response and close connection
// ============================================================================
~pub event send {
    conn: *ConnHandle, status: u16, body: []const u8, content_type: ?[]const u8
}
| sent {}
| failed { msg: []const u8 }

// ============================================================================
// HANDLER - Abstract event for request handling
// ============================================================================
// Users implement this to handle requests. Default returns 404.
// 
// @retain: handler_event is referenced from serve proc's raw Zig code
// via @This().handler_event.handler(...) — invisible to the dead-stripper.
~[abstract|retain]pub event handler {
    req: *Request
}
| response { status: u16, body: []const u8, content_type: ?[]const u8 }

// ============================================================================
// SERVE - Main server flow (calls handler for each request)
// ============================================================================
~pub event serve {
    port: u16
}
| shutdown { reason: []const u8 }
| failed { msg: []const u8 }

// ============================================================================
// ROUTER - Pattern-branch router transform
// ============================================================================
// Transforms pattern branches into dispatch logic
// 
// Usage:
//   ~orisha:handler = orisha:router(req)
//   | [GET /] _ |> response { status: 200, body: "Hello", content_type: "text/plain" }
//   | [GET /users/:id] p |> response { status: 200, body: p.id, content_type: "text/plain" }
//   | [*] _ |> response { status: 404, body: "Not Found", content_type: "text/plain" }
~[comptime|transform]pub event router {
    invocation: *const Invocation,
    item: *const Item,
    program: *const Program,
    allocator: std.mem.Allocator
}
| transformed { program: *const Program }

// Data-only event: declares static files to embed at compile time
// - name: identifier for referencing via static_router
// - root: directory to embed (relative to .kz file)
// - fallback: optional file for SPA fallback (relative to root, e.g. "200.html")
~[comptime]pub event static {
    name: []const u8, root: []const u8, fallback: ?[]const u8
}

// ============================================================================
// STATIC ROUTER - Compile-time transform for static file dispatch
// ============================================================================
// Generates inline lookup code that:
//   1. Imports generated/<name>_routes.zig
//   2. Calls lookupWithEtag(method, path, if_none_match)
//   3. Returns pre-built response (or fallback, or 404)
// 
// Works as top-level handler or nested in a router catch-all:
//   ~orisha:handler = orisha:static_router(name: "site")
//   | [*] |> orisha:static_router(name: "site")
~[comptime|transform]pub event static_router {
    invocation: *const Invocation,
    item: *const Item,
    program: *const Program,
    allocator: std.mem.Allocator
}
| transformed { program: *const Program }