public:

drain_ticket() noexcept;

~drain_ticket();

drain_ticket(drain_ticket&&) noexcept;

drain_ticket& operator=(drain_ticket&&) noexcept;

// Blocking wait bounded by the drain's budget: ok with the

// observed result; would_deadlock when the calling thread runs

// work this drain counts (a handler of the same server waiting on

// its own drain); invalid_state on an empty (default-constructed

// or moved-from) ticket. request_stop()/stop() racing the wait

// drive it to completed -- the two-state result is the documented

// posture.

http::outcome wait(drain_result& out);

private:

friend class native_server;

friend struct ::httpserver::detail::drain_ticket_access;

class impl;

explicit drain_ticket(std::unique_ptr<impl> inner);

std::unique_ptr<impl> impl_;

public:

// Stores the configuration; no I/O, no threads. The options may be

// re-read (mutated copies re-validated) until listen().

explicit native_server(server_options options);

// stop() if still running.

~native_server();

native_server(const native_server&) = delete;

native_server& operator=(const native_server&) = delete;

// Registers one route (pattern and handler semantics per the

// route_registry contract). Fails invalid_state once listen() ran.

http::outcome route(const http::method& method, std::string_view pattern,

route_handler handler);

// TASK-118: the method-set and prefix-family registration forms

// (plan D1; admission and precedence per the route_registry

// contract). Both fail invalid_state once listen() ran.

http::outcome route(const http::method_set& methods,

std::string_view pattern, route_handler handler);

http::outcome route_prefix(const http::method_set& methods,

std::string_view pattern,

route_handler handler);

// Registers one bounded synchronous value-returning route: the

// handler receives the complete request head and the body buffered

// within body_cap, returns the response value, and writes no

// coroutine code (make_sync_route wraps it; DR-V3-003). body_cap

// must be at least 1 (a zero cap means "engine default" in the

// admission policy, so it is rejected here); an empty handler is

// invalid_argument; a duplicate (method, pattern) is invalid_state

// from the registry. Fails invalid_state once listen() ran. The

// bounded sync form is the restricted half of the route surface

// (PRD-V3N-REQ-021): no suspension, upgrade decision, admission

// control, or streaming -- unbounded uploads and duplex work need

// the coroutine route() form.

http::outcome route_sync(const http::method& method,

std::string_view pattern,

sync_route_handler handler,

std::uint64_t body_cap);

// Validates the whole configuration (REQ-016: the pre-listen gate;

// no I/O before it passes), binds every configured listener, and

// starts the accept loops. A typed failure binds nothing that was

// not already bound and leaves the server stopped; a partially

// bound listen failure is terminal for this server object.

http::outcome listen();

// Stop initiation (DR-V3-008): idempotent, non-blocking, safe from

// any thread including inside a handler.

void request_stop() noexcept;

// request_stop() plus closing the transport engine and joining the

// workers. Returns once every engine task finished.

void stop();

// Drain initiation (PRD-V3N-REQ-032): stop accepting new work,

// finish HTTP/1 responses and start WebSocket Close (1001, server drain),

// and fill @p out with a ticket whose wait() is bounded by

// @p budget. Nonblocking and handler-safe like request_stop(); it

// never waits. budget <= 0 is invalid_argument; before listen(),

// after a stop, or on a second drain it is invalid_state. One

// drain per server object. is_running() keeps its meaning (a

// drain is a run-down, not a stop); request_stop()/stop() during

// the drain drive the ticket to completed when before expiry.

// An expiry remains deadline_expired even after cancellation unwinds.

http::outcome begin_drain(std::chrono::milliseconds budget,

drain_ticket& out);

// True from a successful listen() until request_stop() (or the

// destructor) runs.

bool is_running() const noexcept;

// Borrowed, server-owned until destruction; nullptr in managed mode.

// Before listen and after stop the stable adapter is inactive.

readiness_driver* readiness() noexcept;

// TASK-118: the server-wide lifecycle hook bus (server/hooks.hpp

// for the phase contract). Registration is runtime-safe before and

// after listen(); the returned reference is valid for the server's

// lifetime.

hook_bus& hooks() const noexcept;

// TASK-119: the server-wide peer policy (server/peer_policy.hpp

// for the pattern vocabulary and truth table). Seeded from

// options().peer_policy() at listen(); mutable afterwards from any

// thread including inside handlers (every member synchronized,

// DR-V3-008). The returned reference is valid for the server's

// lifetime.

peer_policy& peer_policy() const noexcept;

// The resolved port of listener @p listener_index (0 for an

// ephemeral-port request reports the bound port; 0 before listen()

// or for an out-of-range index).

std::uint16_t get_bound_port(std::size_t listener_index) const noexcept;

private:

class impl;

std::unique_ptr<impl> impl_;