Crate webx

Expand description

Umbrella crate for the rust-webx framework (package rust-webx, imported as webx).

Re-exports the whole framework so applications need a single dependency:

[dependencies]
rust-webx = "0.7"

use webx::*;

The dependency name is rust-webx; the import name is webx. The same applies to the sub-crates (rust-webx-core → webx_core, rust-webx-host → webx_host, rust-webx-macros → webx_macros, rust-webx-spa → webx_spa, rust-webx-openapi → webx_openapi).

Re-exports§

pub use rust_dix;
pub use rust_dix_macros;
pub use hyper;
pub use inventory;
pub use serde;
pub use serde_json;
pub use tokio;

Modules§

assets: Files compiled into the executable by #[webx::main(embed)], read by path.
binding: Request model binding — the runtime half of #[derive(WebxRequestMeta)].
spa: Static file hosting, including files compiled into the executable.

Macros§

register_handlersDeprecated

Structs§

AppOptions: Standard application options loaded from appsettings.json.
AppSection: Top-level application section.
AuthorizeRule: One #[authorize] declaration on an endpoint.
AuthorizerSet: A set of IDynamicAuthorizer instances collected from the DI container.
ByteRange: An inclusive byte range, as requested by a Range header.
CompressionConfig: Compression configuration.
CompressionMiddleware: Middleware that compresses response bodies with gzip when the client supports it (via Accept-Encoding: gzip) and the response exceeds min_size bytes.
ControllerEndpoint: Endpoint for controller-based methods.
CorsConfig: CORS configuration loaded from appsettings.json.
CorsMiddleware: Built-in CORS middleware.
CorsSection: CORS (Cross-Origin Resource Sharing) section.
CultureSection: Culture / localization section.
CurrentUser: The standard identity a request can carry.
DispatchRuntime: Provider + handler registry for one host instance.
DistributedCacheEntryOptions
EndpointCatalog: Every endpoint declared by a route macro.
EndpointDescriptor: One endpoint’s language-neutral metadata.
EndpointInfo: One endpoint with its name and description resolved for a culture.
FieldError
FileBody: A file response — the rust-webx counterpart of ASP.NET Core’s File(...) / PhysicalFile(...) / Results.File(...).
FormField: One text part of a multipart form.
FormFile: One file part of a multipart/form-data request.
FormFileBuilder: Incrementally builds a FormFile while a multipart part streams in.
HandlerCache: Runtime registry of compiled handler registrations.
HandlerEntry: A single compiled handler entry in the registry.
HandlerRegistration: Handler registration collected at compile time. Each #[handler] annotation submits one of these to inventory.
HealthCheckEntry: A single health check entry in a registry snapshot.
HealthCheckRegistry
HealthStatus
Host
HostAppBuilder
HostBuilder
HttpContext: Concrete implementation of IHttpContext wrapping a hyper request and response.
HttpRequest: Concrete implementation of IHttpRequest.
HttpResponse: Concrete implementation of IHttpResponse.
HttpStatus: Common HTTP status codes.
JwtAuth: JWT-based authentication handler.
JwtClaims: Claims extracted from a JWT token.
JwtSection: JWT authentication section.
LocalizationOptions: Resource files registered with the host.
LocalizedString: The result of resolving a TextRef.
Mediator: Default implementation of IMediator.
MemoryCache
MetricsSection: HTTP request metrics (GET /metrics Prometheus text when enabled).
MiddlewarePipeline
MultipartForm: A parsed multipart/form-data body.
PagedRequest
PagedResponse
ParamMeta: Metadata about a request parameter for OpenAPI generation.
ProblemDetails
RateLimitMiddleware
RateLimitSection: Per-IP rate limiting (token bucket).
RateLimiter: Inner rate-limiting state shared behind a Mutex.
RequestContext: Scoped operator identity from JWT sub, set by the HTTP dispatch pipeline.
RequestEndpoint: Endpoint that wraps a boxed async handler.
RequestIdMiddleware: Generates a UUID v4 request ID on each request and injects it into the response.
RequestParamEntry: Optional query/path/body metadata for a request type, collected via #[derive(WebxRequestMeta)] on the request struct.
RequestTracing
ResourceAuthorization: Authorization policy that maps route patterns to allowed roles and permissions.
ResponseData: The HTTP response produced by an endpoint.
RouteDispatch: A dispatch function registered at compile time via the endpoint macros.
RouteEntry: A route entry registered at compile time via #[endpoint] (or its shortcuts #[get]/#[post]/…).
RouteMeta: Route metadata: method + path pattern.
Router: Matchit-based router.
SecurityHeadersMiddleware: Middleware that adds a standard set of security headers to every response.
Server: A fully built server that owns its runtime lifecycle.
ServerHandle: Handle for a running server, allowing programmatic graceful shutdown.
SpaMiddleware: SPA static file middleware.
StaticHtmlEndpoint: Endpoint that serves a static HTML payload.
StaticJsonEndpoint: Endpoint that serves a static JSON payload.
StringLocalizer: The framework’s default IStringLocalizer: static JSON resource tables.
TextRef: A reference to localized text.
TimingMiddleware: Records a request counter via the after hook.
TlsSection: TLS (Transport Layer Security) section.

Enums§

AppMode: Controls how the framework behaves at startup and at runtime.
CacheError
Disposition: How a file response should be presented.
Error: Framework-wide error type.
FileSource: Where a file response’s bytes come from.
HttpMethod: HTTP methods supported by the framework.
ResponseBody: The body of an HTTP response.

Constants§

APIUI_HTML: The embedded HTML for the API docs UI.
SPOOL_FILE_PREFIX: Prefix given to every temporary file the framework writes for an upload.
STREAM_BUF_SIZE: Read/write buffer size used for streamed response bodies and spooled uploads.

Traits§

DistributedCacheExtensions
IAppOptions: Application options — binds to a section of appsettings.json.
IAuthenticationHandler: Authentication scheme interface.
IAuthorizationPolicy: Authorization policy that checks whether an authenticated user can access a given resource.
IClaims: Claims extracted from an authentication token (JWT, etc.).
IClaimsCarrier: Blanket trait that enables claims injection on request structs.
IClaimsExt: Extension trait that adds claims storage to an IHttpContext.
IDistributedCache
IDynamicAuthorizer: Dynamic authorizer interface — pluggable authorization for protected routes.
IEndpoint: An endpoint handler is the terminal component in the middleware pipeline.
IEndpointCatalog: Runtime endpoint metadata source.
IEventHandler: Handles a single IEventRequest, performing side effects.
IEventRequest: Marker trait for an event (notification) that does not produce a response.
IHost: The web host that binds to an address and starts serving HTTP requests.
IHostedService: Background service that is started when the host starts and stopped when the host performs a graceful shutdown.
IHttpContext: HTTP context encapsulating the request, response, and service provider for the duration of a single HTTP request.
IHttpRequest: HTTP request abstraction.
IHttpResponse: HTTP response abstraction.
IMediator: The mediator dispatches requests to their handlers and publishes events to all registered handlers.
IMiddleware: Middleware component in the HTTP request pipeline.
IPipelineBehavior: Pipeline behavior that wraps around request handling.
IRequest: Marker trait for a request (command or query) carrying a structured response TResponse.
IRequestHandler: Handles a single IRequest<R>, producing its associated response R.
IRouter: Router that matches incoming HTTP requests to registered endpoints.
IServiceCollectionExt: Extension methods for rust_dix::ServiceCollection to enable framework-level service registration patterns.
IStringLocalizer: Resolves resource keys for a culture.
RequestModel: A type that can be constructed from an HTTP request.
RequestUser: Convenience accessors for a request that carries a CurrentUser.
ScopeFactory: Factory trait for creating independent scopes. Injectable into singleton services that need on-demand scope creation (e.g., background workers). 工厂 trait：创建独立 scope。可注入 singleton 服务按需创建 scope。
SeekableReader: An async reader that can also seek.

Functions§

app_base: 解析应用基准目录。优先级见模块文档。
bind_config: Bind a section of the config JSON to a deserializable type.
bind_root: Bind the entire config JSON to a type (for root-level deserialization).
build_pipeline_chain: Build a chain of pipeline behaviors wrapping a terminal handler.
build_resource_policy_from_routesDeprecated: Build a ResourceAuthorization policy from compile-time route metadata.
collect_authorizers: Result from collecting IDynamicAuthorizer instances from DI. None means no authorizers are registered (pass-through mode).
compress_gzip: Compress a byte buffer using gzip at the given compression level (0-9).
content_disposition_value: Build a Content-Disposition header value (RFC 6266).
dispatch_provider: Provider for HTTP dispatch and #[handler(inject)] factories.
duplicate_handlers: Request types with more than one #[handler] registration (last wins at runtime).
format_route_diagnostics: Human-readable route/handler diagnostic report (no tracing dependency).
framework_root: Resolve the Rust-Framework monorepo root for live sibling doc paths.
generate_openapi_spec: Generate an OpenAPI 3.0.3 specification from registered routes.
global_providerDeprecated: Deprecated shim: read the process-wide ServiceProvider fallback.
init_jwt_secret: Initialize the global JWT encoding secret from the configured secret. This is called automatically by .add_authentication() on the HostBuilder, but can also be called manually if needed.
is_mediator_active
jwt_middleware: Create a JWT authentication middleware from an authentication handler.
jwt_secret: Retrieve the global JWT encoding secret previously set via init_jwt_secret.
load_appsettings: Load the merged appsettings JSON (base + environment overlay + env overrides).
log_startup_diagnostics: Log route table and warn on orphan routes/handlers.
looks_like_app_base: 判断给定目录是否为「应用基准目录」（存在 appsettings.json）。
looks_like_framework_root: Returns true when dir looks like the Rust-Framework monorepo root (contains rust-webx and at least one other ecosystem crate).
orphan_handlers: Request types registered via #[handler] without a matching route.
orphan_route_details: Routes with inventory entries but no matching #[handler] (includes path/method).
orphan_routes: Request types with a route but no registered handler.
read_json_body: Helper: read JSON from the request body.
resource_auth_middleware: Create a resource-based authorization middleware.
route_snapshots: Collect all inventory routes and whether a matching #[handler] exists.
sanitize_file_name: Reduce a client-supplied filename to a safe basename.
set_global_providerDeprecated: Deprecated shim: set a process-wide ServiceProvider fallback.
set_spool_root: Point spooling at path.
should_scan_endpoints
spool_root: The directory used for spooled uploads.
write_json_response: Helper: build a JSON response by serializing a value and writing it.

Type Aliases§

BoxedNextFn: Type-erased continuation function for pipeline behaviors.
BoxedPipelineFuture: Boxed future returned by a pipeline behavior step.
HandlerFn: Boxed final handler function type.
HandlerRegistry: Preferred name for HandlerCache — emphasizes registry semantics over caching.
HealthCheckFn
Json: Type alias for JSON responses in controller methods.
Result: Shorthand for Result<T, Error>.
RouteDispatchFn: The signature every route dispatch function implements.

Attribute Macros§

async_trait
authorize: Declares authorization requirements on a route.
category: Declares an optional display grouping for the endpoint.
claims: Marks a request struct as carrying authentication claims.
delete: Shortcut: registers an IRequest impl at DELETE /path.
description: Declares an endpoint’s long description as a resource reference.
display: Declares an endpoint’s display name as a resource reference.
embed_assets: Include the OUT_DIR asset table (for integration tests that never run main).
endpoint: Full form: marks an IRequest impl with HTTP method and route path.
get: Shortcut: registers an IRequest impl at GET /path.
handler: Auto-registers an IRequestHandler implementation at compile time via inventory.
inject
main: Application entry — ASP.NET Core Main analogue (#[tokio::main]).
module
post: Shortcut: registers an IRequest impl at POST /path.
put: Shortcut: registers an IRequest impl at PUT /path.

Derive Macros§

Inject
WebxRequestMeta: Registers parameter metadata and the request binder from #[from*] fields.

Crate webx

Crate webx Copy item path

Re-exports§

Modules§

Macros§

Structs§

Enums§

Constants§

Traits§

Functions§

Type Aliases§

Attribute Macros§

Derive Macros§

Crate webx