Crate hyperlane_macros

Expand description

§Hyperlane Macros

A comprehensive collection of procedural macros for building HTTP servers with enhanced functionality. This crate provides attribute macros that simplify HTTP request handling, protocol validation, response management, and request data extraction.

§Features

HTTP Method Handlers: Macros for all standard HTTP methods (GET, POST, PUT, DELETE, etc.)
Protocol Validation: Support for HTTP versions, WebSocket, TLS, and HTTP/2 cleartext
Response Management: Status code setting, reason phrase customization, and response sending
Request Data Extraction: Body parsing, request header extraction, request query parameters, and route parameters
Filter Mechanisms: Unknown method, upgrade, and version filtering
Hook System: Pre and post execution hooks for request processing
Stream Management: Connection state handling for aborted and closed streams
Server Instance Creation: Automatic Server instance initialization with custom variable names

§Dependencies

To use this crate, add the following dependencies to your Cargo.toml:

[dependencies]
hyperlane-macros = "*"
hyperlane = "*"
serde = { version = "*", features = ["derive"] }

§Usage Guidelines

Most macros are designed to be used as attribute macros on async functions that accept a Context parameter. The hyperlane macro can be used on any async function to create a Server instance. Multiple macros can be combined on a single function to create complex request handling logic. When using hook macros (pre_hook, post_hook), avoid combining them with other macros on the same function to prevent unexpected behavior during macro expansion.

Attribute Macros§

aborted: Handles aborted request scenarios.
attribute: Extracts a specific attribute value into a variable.
attributes: Extracts all attributes into a HashMap variable.
closed: Handles closed connection scenarios.
connect: Restricts function execution to HTTP CONNECT requests only.
delete: Restricts function execution to HTTP DELETE requests only.
filter_unknown: Handles requests with any unknown characteristics.
filter_unknown_method: Handles requests with unknown or non-standard HTTP methods.
filter_unknown_upgrade: Handles requests with unknown or non-standard upgrade protocols.
filter_unknown_version: Handles requests with unknown or non-standard HTTP versions.
flush: Flushes the response stream after function execution.
get: Restricts function execution to HTTP GET requests only.
h2c: Restricts function execution to HTTP/2 Cleartext (h2c) requests only.
head: Restricts function execution to HTTP HEAD requests only.
host: Restricts function execution to requests with a specific host.
host_filter: Filters requests that have no host header.
http: Restricts function execution to standard HTTP requests only.
http0_9: Restricts function execution to HTTP/0.9 requests only.
http2: Restricts function execution to HTTP/2 requests only.
http3: Restricts function execution to HTTP/3 requests only.
http1_0: Restricts function execution to HTTP/1.0 requests only.
http1_1: Restricts function execution to HTTP/1.1 requests only.
http1_1_or_higher: Restricts function execution to HTTP/1.1 or higher protocol versions.
hyperlane: Creates a new Server instance with the specified variable name.
methods: Allows function to handle multiple HTTP methods.
options: Restricts function execution to HTTP OPTIONS requests only.
patch: Restricts function execution to HTTP PATCH requests only.
post: Restricts function execution to HTTP POST requests only.
post_hook: Executes a specified function after the main handler function.
pre_hook: Executes a specified function before the main handler function.
put: Restricts function execution to HTTP PUT requests only.
referer: Restricts function execution to requests with a specific referer.
referer_filter: Filters requests that have a specific referer header.
request_body: Extracts the raw request body into a specified variable.
request_body_json: Parses the request body as JSON into a specified variable and type.
request_cookie: Extracts a specific cookie value or all cookies into a variable.
request_cookies: Extracts all cookies as a raw string into a variable.
request_header: Extracts a specific HTTP request header into a variable.
request_headers: Extracts all HTTP request headers into a collection variable.
request_path: Extracts the HTTP request path into a variable.
request_query: Extracts a specific request query parameter into a variable.
request_querys: Extracts all request query parameters into a collection variable.
request_version: Extracts the HTTP request version into a variable.
response_body: Sets the HTTP response body.
response_header: Sets or replaces a specific HTTP response header.
response_reason_phrase: Sets the HTTP reason phrase for the response.
response_status_code: Sets the HTTP status code for the response.
response_version: Sets the HTTP response version.
route_param: Extracts a specific route parameter into a variable.
route_params: Extracts all route parameters into a collection variable.
send: Automatically sends the complete response after function execution.
send_body: Automatically sends only the response body after function execution.
send_once: Sends the complete response exactly once after function execution.
send_once_body: Sends only the response body exactly once after function execution.
tls: Restricts function execution to TLS-encrypted requests only.
trace: Restricts function execution to HTTP TRACE requests only.
ws: Restricts function execution to WebSocket upgrade requests only.