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, header extraction, 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

§Dependencies

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

[dependencies]
hyperlane-macros = "1.1"
hyperlane = "1.0"
tokio = { version = "1.0", features = ["full"] }
serde = { version = "1.0", features = ["derive"] }

§Usage Guidelines

All macros are designed to be used as attribute macros on async functions that accept a Context parameter. 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.
body: Parses the request body into a specified variable and type.
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.
header: Extracts a specific HTTP header into a variable.
headers: Extracts all HTTP headers into a collection variable.
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.
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.
query: Extracts a specific query parameter into a variable.
querys: Extracts all query parameters into a collection variable.
reason_phrase: Sets the HTTP reason phrase for the response.
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.
status_code: Sets the HTTP status code for the response.
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.