Description
Provides deterministic method-and-path routing above HTTP.Server.
Add
procedure Add
(Item : in out Router;
Method : String;
Pattern : String;
Handler : not null Handler_Access;
Name : String := "";
Policy : Route_Policy := Default_Route_Policy)
Register one exact method and path pattern.
Parameters
- Item
Router registry
- Method
Case-sensitive HTTP method token
- Pattern
Static, {name}, or final {*name} path pattern
- Handler
Application endpoint
- Name
Stable route name; empty derives Method and Pattern
- Policy
Route-local application policy
Add_Middleware
procedure Add_Middleware
(Item : in out Router;
Component : not null Middleware_Access;
Stage : Middleware_Stage := Request_Head;
Name : String := "")
Append global middleware. Global components wrap every matched route in registration order and are copied into mounted subrouter routes.
Parameters
- Item
Router registry
- Component
Around-handler component
- Stage
Body-admission boundary for the component
- Name
Optional stable diagnostic name for introspection
Add_Route_Middleware
procedure Add_Route_Middleware
(Item : in out Router;
Name : String;
Component : not null Middleware_Access;
Stage : Middleware_Stage := Request_Head;
Middleware_Name : String := "")
Append middleware to one route selected by its unique configured name. Route-local components run after router-global components.
Parameters
- Item
Router registry
- Name
Configured route name
- Component
Around-handler component
- Stage
Body-admission boundary for the component
- Middleware_Name
Optional stable diagnostic name
Allow_SSE
Allow_SSE : constant Upgrade_Policy :=
Flyology.HTTP.Server.Applications.Allow_SSE;
Permit an SSE lifecycle on the route.
Allow_WebSocket
Allow_WebSocket : constant Upgrade_Policy :=
Flyology.HTTP.Server.Applications.Allow_WebSocket;
Permit a WebSocket lifecycle on the route.
App_Context
type App_Context is limited private;
Application context shared by routed handlers.
Authentication_Policy
subtype Authentication_Policy is
Flyology.HTTP.Server.Applications.Authentication_Mode;
Authentication policy interpreted by authentication middleware.
Components
package Components is new
Flyology.HTTP.Server.Middleware (App_Context);
Typed middleware API used by this router instance. Applications may also instantiate Server.Middleware independently of routing.
Default_Route_Policy
Default_Route_Policy : constant Route_Policy := (others => <>);
Baseline route policy: reject bodies and preserve the server deadline.
Delete
procedure Delete
(Item : in out Router;
Pattern : String;
Handler : not null Handler_Access;
Name : String := "";
Policy : Route_Policy := Default_Route_Policy)
Register a DELETE route.
Parameters
- Item
Router registry
- Pattern
Route path pattern
- Handler
Application endpoint
- Name
Stable route name
- Policy
Route-local policy
Describe_Global_Middleware
function Describe_Global_Middleware
(Item : Router;
Index : Positive) return Middleware_Description
Copy one global middleware description.
Parameters
- Item
Router registry
- Index
One-based registration index
Return value
Owned middleware metadata
Raised exceptions
- Constraint_Error
Index is outside the configured range
Describe_Route
function Describe_Route
(Item : Router;
Index : Positive) return Route_Description
Copy one configured route description.
Parameters
- Item
Router registry
- Index
One-based registration index
Return value
Owned route metadata that may outlive the router
Raised exceptions
- Constraint_Error
Index is outside 1 .. Route_Count
Describe_Route_Middleware
function Describe_Route_Middleware
(Item : Router;
Route_Index : Positive;
Middleware_Index : Positive) return Middleware_Description
Copy one route-local or mounted middleware description.
Parameters
- Item
Router registry
- Route_Index
One-based route registration index
- Middleware_Index
One-based middleware index for that route
Return value
Owned middleware metadata
Raised exceptions
- Constraint_Error
Either index is outside its configured range
Dispatch
procedure Dispatch
(Item : in out Router;
Context : in out App_Context;
Connection : aliased in out Flyology.HTTP.Server.Connection;
Value : aliased in out Request;
Peer : Flyology.IO.Sockets.Endpoint;
Token : access Flyology.Cancellation.Token := null)
Match and invoke one already parsed request. Automatic 404, 405, HEAD fallback, slash handling, body policy, and deadline narrowing occur before the endpoint is called.
Parameters
- Item
Router registry
- Context
Typed shared application context
- Connection
Sole-writer HTTP connection
- Value
Parsed request head
- Peer
Connected peer address
- Token
Optional cancellation token
Get
procedure Get
(Item : in out Router;
Pattern : String;
Handler : not null Handler_Access;
Name : String := "";
Policy : Route_Policy := Default_Route_Policy)
Register a GET route. HEAD falls back to it when no exact HEAD exists.
Parameters
- Item
Router registry
- Pattern
Route path pattern
- Handler
Application endpoint
- Name
Stable route name
- Policy
Route-local policy
Global_Middleware_Count
function Global_Middleware_Count (Item : Router) return Natural
Return the number of global middleware registrations.
Parameters
- Item
Router registry
Return value
Global middleware count in registration order
Handler_Access
subtype Handler_Access is Components.Handler_Access;
Application endpoint invoked with the typed context and borrowed request exchange.
Head
procedure Head
(Item : in out Router;
Pattern : String;
Handler : not null Handler_Access;
Name : String := "";
Policy : Route_Policy := Default_Route_Policy)
Register an explicit HEAD route.
Parameters
- Item
Router registry
- Pattern
Route path pattern
- Handler
Application endpoint
- Name
Stable route name
- Policy
Route-local policy
Middleware_Access
subtype Middleware_Access is Components.Middleware_Access;
Around-handler component accepted by router middleware registration.
Middleware_Description
type Middleware_Description is record
Name : Ada.Strings.Unbounded.Unbounded_String;
Stage : Middleware_Stage;
end record;
Immutable copy of one middleware registration. An empty name means the application used the source-compatible unnamed registration form.
Record fields
- Name
Application-provided diagnostic name
- Stage
Body-admission boundary where the component runs
Middleware_Stage
type Middleware_Stage is (Request_Head, Application);
Middleware execution boundary relative to request-body admission.
Enumeration literals
- Request_Head
Run before body acceptance and 100 Continue
- Application
Run after the selected body policy is applied
Mount
procedure Mount
(Item : in out Router;
Prefix : String;
Source : Router;
Name_Prefix : String := "")
Copy routes from Source under Prefix. Capacity is checked before any route is copied. Prefix must be a static path without parameters.
Parameters
- Item
Destination router
- Prefix
Static mount path
- Source
Source subrouter
- Name_Prefix
Optional prefix for nonempty route names
No_Authentication
No_Authentication : constant Authentication_Policy :=
Flyology.HTTP.Server.Applications.No_Authentication;
Route does not request authentication.
No_Upgrade
No_Upgrade : constant Upgrade_Policy :=
Flyology.HTTP.Server.Applications.No_Upgrade;
Ordinary HTTP responses only.
Optional_Authentication
Optional_Authentication : constant Authentication_Policy :=
Flyology.HTTP.Server.Applications.Optional_Authentication;
Install a principal when valid credentials exist.
Options
procedure Options
(Item : in out Router;
Pattern : String;
Handler : not null Handler_Access;
Name : String := "";
Policy : Route_Policy := Default_Route_Policy)
Register an OPTIONS route.
Parameters
- Item
Router registry
- Pattern
Route path pattern
- Handler
Application endpoint
- Name
Stable route name
- Policy
Route-local policy
Patch
procedure Patch
(Item : in out Router;
Pattern : String;
Handler : not null Handler_Access;
Name : String := "";
Policy : Route_Policy := Default_Route_Policy)
Register a PATCH route.
Parameters
- Item
Router registry
- Pattern
Route path pattern
- Handler
Application endpoint
- Name
Stable route name
- Policy
Route-local policy
Post
procedure Post
(Item : in out Router;
Pattern : String;
Handler : not null Handler_Access;
Name : String := "";
Policy : Route_Policy := Default_Route_Policy)
Register a POST route.
Parameters
- Item
Router registry
- Pattern
Route path pattern
- Handler
Application endpoint
- Name
Stable route name
- Policy
Route-local policy
Put
procedure Put
(Item : in out Router;
Pattern : String;
Handler : not null Handler_Access;
Name : String := "";
Policy : Route_Policy := Default_Route_Policy)
Register a PUT route.
Parameters
- Item
Router registry
- Pattern
Route path pattern
- Handler
Application endpoint
- Name
Stable route name
- Policy
Route-local policy
Required_Authentication
Required_Authentication : constant Authentication_Policy :=
Flyology.HTTP.Server.Applications.Required_Authentication;
Reject requests without valid credentials.
Route_Count
function Route_Count (Item : Router) return Natural
Return the number of configured routes without allocating. Registration and introspection must not occur concurrently.
Parameters
- Item
Router registry
Return value
Number of routes in registration order
Route_Description
type Route_Description is record
Method : Ada.Strings.Unbounded.Unbounded_String;
Pattern : Ada.Strings.Unbounded.Unbounded_String;
Name : Ada.Strings.Unbounded.Unbounded_String;
Policy : Route_Policy;
Middleware_Count : Natural;
end record;
Immutable copy of one registered route's public configuration. Introspection is intended for diagnostics after setup; it is not part of request dispatch and adds no work to the routing hot path.
Record fields
- Method
Configured HTTP method
- Pattern
Configured path pattern
- Name
Stable route name
- Policy
Route-local application policy
- Middleware_Count
Route-local or mounted middleware count
Route_Error
Route_Error : exception;
Invalid route registration or decoded request path.
Route_Middleware_Count
function Route_Middleware_Count
(Item : Router;
Route_Index : Positive) return Natural
Return route-local and mounted middleware count for one route.
Parameters
- Item
Router registry
- Route_Index
One-based route registration index
Return value
Middleware count in execution order after global components
Raised exceptions
- Constraint_Error
Route_Index is outside the configured range
Route_Policy
type Route_Policy is record
Body_Handling :
Flyology.HTTP.Server.Applications.Request_Body_Policy :=
Flyology.HTTP.Server.Applications.Reject_Body;
Max_Body : Natural := Max_Request_Body;
Timeout : Duration := -1.0;
Concurrency : Natural := 0;
Rate_Per_Second : Natural := 0;
Authentication : Authentication_Policy := No_Authentication;
CORS_Policy : Natural := 0;
Upgrade : Upgrade_Policy := No_Upgrade;
end record;
Route-local policy consumed incrementally by optional toolkit layers. A zero concurrency or rate value means unlimited. CORS_Policy is an application-defined bounded registry slot interpreted by CORS middleware; zero means no CORS policy.
Record fields
- Body_Handling
Request body handling
- Max_Body
Maximum decoded body bytes
- Timeout
Deadline narrowing in seconds; negative preserves it
- Concurrency
Maximum active handlers; zero is unlimited
- Rate_Per_Second
Per-client admission rate; zero is unlimited
- Authentication
Route authentication requirement
- CORS_Policy
Bounded application CORS policy slot
- Upgrade
Permitted endpoint lifecycle
Router
type Router
(Capacity : Positive := 64;
Slashes : Trailing_Slash_Policy := Strict_Slashes)
is tagged limited private;
Bounded route registry. Registration is intended during application setup, before concurrent dispatch begins.
Record fields
- Capacity
Maximum registered routes
- Slashes
Explicit final-slash behavior
Serve
procedure Serve
(Item : in out Router;
Context : in out App_Context;
Connection : aliased in out Flyology.HTTP.Server.Connection;
Peer : Flyology.IO.Sockets.Endpoint;
Timeout : Duration := 30.0;
Max_Connection_Age : Duration := 300.0;
Max_Requests : Natural := 1_000;
Token : access Flyology.Cancellation.Token := null;
Header_Timeout : Duration := -1.0)
Read and route persistent requests until close or upgrade. This optional adapter leaves the lower-level Connection_Handlers package available.
Parameters
- Item
Router registry
- Context
Typed shared application context
- Connection
Sole-writer HTTP connection
- Peer
Connected peer address
- Timeout
Original per-request deadline interval
- Max_Connection_Age
Absolute lifetime bound for the connection; negative disables this additional bound
- Max_Requests
Requests before connection close; zero is unlimited
- Token
Optional cancellation token
- Header_Timeout
Absolute slow-header budget for each request; negative uses the remaining request/connection lifetime
Trailing_Slash_Policy
type Trailing_Slash_Policy is
(Strict_Slashes, Ignore_Slashes, Redirect_Slashes);
Trailing slash treatment.
Enumeration literals
- Strict_Slashes
Route pattern and target must agree
- Ignore_Slashes
A final slash does not affect matching
- Redirect_Slashes
Mismatches receive a permanent 308 redirect
Upgrade_Policy
subtype Upgrade_Policy is
Flyology.HTTP.Server.Applications.Upgrade_Mode;
Upgrade permission for higher-level endpoint adapters.