poem-web/poem

This system is the Poem web framework for Rust, providing a high-performance HTTP server built on Hyper 1.x with comprehensive support for routing, middleware, and session management. It extends core functionality through specialized libraries for generating OpenAPI v3 documentation, implementing gRPC services, and building Model Context Protocol (MCP) servers. The framework also includes integrations for deploying to serverless environments like AWS Lambda and Cloudflare Workers, along with built-in capabilities for TLS, internationalization, and distributed tracing.

63 changes.

The project underwent a major architectural overhaul with the release of Poem 3.0, migrating the core HTTP implementation to Hyper 1.x and introducing new abstractions for routing, listeners, and middleware. Concurrently, the poem-openapi crate was updated to version 5, adding full OpenAPI v3 support, new authentication extractors, and expanded type handling. This period also saw a significant expansion of example applications covering gRPC, GraphQL, file uploads, and various security patterns.

31 changes.

This period focused on expanding the framework's capabilities with the initial release of poem-grpc, including code generation, streaming support, and JSON codecs. It also introduced internationalization support via Fluent and added automatic TLS certificate management through ACME. The work was heavily supported by a comprehensive suite of new examples demonstrating these features alongside OpenAPI enhancements and testing utilities.

11 changes.

This period focused on introducing the poem-mcpserver crate to support the Model Context Protocol, including foundational protocol types, procedural macros for tools and prompts, and transport implementations for stdio and streamable HTTP. It also expanded the framework's deployment options by adding the poem-worker crate for Cloudflare Workers support, accompanied by comprehensive examples and integration tests for both features.

The \poem\ crate now includes a built-in ACME (Automatic Certificate Management Environment) module in \poem/src/listener/acme\, enabling automatic TLS certificate issuance and renewal via Let's Encrypt. This feature introduces \AutoCertListener\ and \AutoCertBuilder\ to configure domains, contact emails, and cache paths, while supporting both HTTP-01 and TLS-ALPN-01 challenge types. The implementation handles account creation, certificate ordering, and background renewal, with optional file-system caching to respect rate limits.

poem/src/listener/acme · high confidence

A new example application in examples/poem/csrf demonstrates how to protect a login form against Cross-Site Request Forgery attacks using Poem's Csrf middleware. The example serves a login page that includes a hidden CSRF token and validates the token on the POST endpoint, returning an unauthorized error if the token is missing or invalid, and listens on 0.0.0.0:3000.

examples/poem/csrf · high confidence

The \poem-worker\ crate now provides a new integration layer that allows Poem applications to run on Cloudflare Workers. This adds a request/response adapter (\req.rs\, \body.rs\) to translate between Poem and \worker-rs\ types, a server entry point (\server.rs\) that bridges the Cloudflare fetch event to the Poem app, and extractor types (\cloudflare.rs\, \context.rs\, \env.rs\) that expose Cloudflare-specific properties (like CF headers, environment variables, and bindings) as Poem request extractors.

poem-worker · high confidence

Introduces a new example application demonstrating OpenAPI documentation and GitHub OAuth2 authentication using the Poem framework. The example exposes a Swagger UI and an API endpoint that retrieves GitHub repositories, requiring Bearer token authentication via the GitHub OAuth2 authorization code flow. To handle CORS restrictions imposed by GitHub's token endpoint, the application includes a local proxy route at /proxy that forwards requests to GitHub.

examples/openapi/auth-github · high confidence

The \poem-grpc\ library now supports a JSON codec (\JsonCodec\ and \JsonI64ToStringCodec\) alongside the existing Protobuf codec, allowing gRPC services to exchange messages using \application/grpc+json\. The \JsonI64ToStringCodec\ specifically serializes 64-bit integers as strings to prevent precision loss in JavaScript clients, while the standard \JsonCodec\ handles JSON serialization directly. This is implemented via new \i64string\_serializer.rs\ and \i64string\_deserializer.rs\ modules that wrap the underlying \serde\_json\ serializers.

poem-grpc/src/codec · high confidence

Users can now view their API documentation using the OpenAPI Explorer interface. This change introduces a new UI module in \poem-openapi/src/ui\ that generates the necessary HTML and includes the OpenAPI Explorer JavaScript library (v0.10.442) to render the specification.

poem-openapi/src/ui · high confidence

Introduces a new example demonstrating how to implement a uniform API response structure using the \poem\_openapi\ crate. The example defines a generic \ResponseObject\ wrapper that standardizes responses with a status code, message, and optional data payload, and shows how to apply this pattern across different API endpoints while handling bad request errors uniformly.

(repo-wide) · high confidence

The \poem-openapi/src/validation\ module now includes implementations for standard OpenAPI validation constraints, allowing users to enforce limits on input data. This adds support for \minLength\ and \maxLength\ on strings, \minimum\ and \maximum\ (including exclusive bounds) on numeric types, \minItems\ and \maxItems\ on arrays, \minProperties\ and \maxProperties\ on maps, \pattern\ matching for strings, \multipleOf\ checks for numbers, and \uniqueItems\ validation for arrays. These validators integrate with the schema registry to expose the corresponding metadata in the generated OpenAPI specification.

poem-openapi/src/validation · high confidence

A new example application has been added at examples/poem/lambda-hello-world demonstrating how to run a Poem web service on AWS Lambda. The example uses the poem-lambda crate to handle requests, defines a simple route at /prod/hello/:name, and initializes the tracing subscriber for logging.

examples/poem/lambda-hello-world · high confidence

New example applications have been added to demonstrate using \poem-openapi\ with the \poem\ web framework. The \poem-extractor\ example shows how to inject custom data (via \Data\<&i32\>\) into API handlers, while the \poem-middleware\ example illustrates applying custom middleware (such as setting headers) to API endpoints. Both examples configure the server to listen on \0.0.0.0:3000\ and expose a Swagger UI at the root path.

examples/openapi/poem-extractor · high confidence

A new example at examples/poem/catch-panic demonstrates how to use Poem's CatchPanic middleware to recover from panics in handlers. The example application binds to 0.0.0.0:3000, includes a handler that intentionally panics, and applies both Tracing and CatchPanic middleware to the route, illustrating how the framework handles unexpected errors gracefully.

examples/poem/catch-panic · high confidence

A new example project has been added at examples/poem/worker-hello-world that demonstrates how to build a Cloudflare Worker using the Poem web framework. The example includes a Rust source file defining a simple route and a wrangler configuration file, allowing users to deploy a basic HTTP service to the Cloudflare Workers platform.

examples/poem/worker-hello-world · high confidence

A new example demonstrates distributed tracing using the Poem web framework and OpenTelemetry, sending trace data via the OTLP protocol to a Jaeger instance. The example consists of a client and two servers (server1 and server2) that propagate trace context across HTTP requests, allowing users to visualize the full request chain in the Jaeger UI.

examples/poem/opentelemetry-jaeger · high confidence

A new example application has been added at examples/poem/redis-session that demonstrates how to implement server-side sessions using Redis. The example configures a Poem route to track a visit count via a session stored in Redis, using a cookie-based session configuration with secure mode disabled for HTTP access, and binds the server to 0.0.0.0:3000.

examples/poem/redis-session · high confidence

A new example application has been added at examples/openapi/sse that demonstrates how to implement Server-Sent Events using the Poem framework. The example exposes an /events endpoint that streams integer values every second and includes a Swagger UI interface accessible at the root path, with the server configured to listen on all network interfaces (0.0.0.0) on port 3000.

examples/openapi/sse · high confidence

The repository now includes a new example application in \examples/pem/tokio-metrics\ that demonstrates how to integrate the \TokioMetrics\ middleware with the Poem web framework. This example configures two distinct routes (\/a\ and \/b\) with separate metrics collectors and exposes their respective metrics at \/metrics/a\ and \/metrics/b\, allowing users to observe per-route performance data. The server is configured to listen on all interfaces (\0.0.0.0\) on port 3000.

examples/poem/tokio-metrics · high confidence

A new example application has been added at examples/poem/async-graphql/src/main.rs that demonstrates integrating async-graphql with the Poem web framework. The example sets up a GraphQL schema using the Star Wars demo data, exposes a GraphQL playground at the root path, and handles GraphQL requests via a dedicated handler. The server listens on 0.0.0.0:3000 and uses tracing for logging.

examples/poem/async-graphql/src, examples/poem/mongodb · high confidence

A new example application at examples/openapi/auth-basic demonstrates how to implement HTTP Basic Authentication in a Poem service. It defines a MyBasicAuthorization security scheme and an /basic endpoint that validates credentials (user: test, password: 123456), returning a 401 Unauthorized status for invalid attempts. The server listens on 0.0.0.0:3000 and exposes the Swagger UI at the root path.

examples/openapi/auth-basic · high confidence

A new example demonstrating how to implement custom error handling in a Poem application has been added. The example shows defining a custom error type that implements the \ResponseError\ trait to return a specific HTTP status code (BAD\_REQUEST) and message, and wiring it into a route handler.

examples/poem/custom-error · high confidence

The \examples/poem/embed-files\ directory now includes a runnable example that serves static HTML and images using the \rust-embed\ crate. The application binds to \0.0.0.0:3000\ and exposes the root path (\/\) via \EmbeddedFileEndpoint\ and the \/files\ directory via \EmbeddedFilesEndpoint\, allowing users to serve embedded assets directly from the binary without external file system dependencies.

examples/poem/embed-files · high confidence

A new example has been added in the \examples/poem/add-data\ directory that demonstrates how to use the \AddData\ middleware in the Poem web framework. The example shows how to share application state (specifically a thread-safe map of clients) across handlers using \Data\<&Arc\<AppState\>\>\, allowing routes to read and write shared data.

examples/poem/add-data · high confidence

The custom-payload example now demonstrates how to define and use a custom payload type (BCS) for API requests and responses. This includes a new \bcs\_payload.rs\ module implementing serialization/deserialization via the \bcs\ crate and integration with \poem\_openapi\, along with a \main.rs\ showing a simple echo endpoint using this custom type. The server now listens on \0.0.0.0\ to allow external access.

examples/openapi/custom-payload · high confidence

A new example demonstrates how to start a local HTTP server using the Poem framework and automatically open the default web browser to the served page. The example binds to 127.0.0.1 for security, iterates through ports 8080–8085 to find an available one, and uses \open::that\_detached\ to launch the browser without blocking the server process.

examples/poem/local-server-with-browser · high confidence

New example applications have been added to demonstrate gRPC integration with the poem framework. The \jsoncodec\ example shows how to implement a basic gRPC service that serializes requests and responses using JSON, while the \reflection\ example extends this by enabling gRPC reflection, allowing clients to discover service definitions and file descriptors at runtime. Both examples bind to 0.0.0.0:3000 and include tracing middleware for debugging.

examples/grpc/jsoncodec, examples/grpc/reflection · high confidence

The poem i18n example now supports internationalization using Fluent resource files for English (en-US), French (fr), and Chinese (zh-CN), allowing users to see localized text for 'hello-world' and 'welcome' messages. The example application listens on all network interfaces (0.0.0.0) on port 3000 instead of just localhost, making it accessible from outside the container or host machine.

examples/poem/i18n · high confidence

This change introduces internationalization support to the Poem framework using the Fluent translation format. It adds a \Locale\ extractor that parses the \Accept-Language\ header to negotiate and select the appropriate language bundle, and provides an \accept\_languages()\ method to access the prioritized list of user-preferred languages. Additionally, it introduces \I18NArgs\ for formatting messages with arguments, supporting conversion from \HashMap\ and tuples, and \I18NResources\ to load translation resources from file paths or inline FTL strings.

poem/src/i18n · high confidence

The examples/poem/middleware directory now includes a Rust application that demonstrates how to implement a custom logging middleware. The example defines a \Log\ middleware that prints the request URI and response status code to the console, and configures the server to listen on 0.0.0.0:3000.

examples/poem/middleware · high confidence

The examples/grpc directory now includes several new subdirectories (helloworld\_compressed, helloworld\_typename, jsoncodec, middleware, reflection, routeguide) that serve as reference implementations for the poem-grpc library. These examples demonstrate how to enable GZIP compression on clients and servers, generate and access protobuf type names and URLs, use a JSON codec with serde serialization, apply client and server middleware, and generate file descriptor sets for service reflection, alongside a standard RouteGuide example.

examples/grpc · high confidence

Added a new gRPC example using the poem-grpc library, featuring a server implementation that listens on 0.0.0.0:3000 and a client that connects to localhost:3000 to send a greeting request.

examples/grpc/helloworld · high confidence

Introduces the new \poem-lambda\ crate, enabling users to deploy Poem applications to AWS Lambda. The crate provides a \run\ function for handler execution, enforces safe Rust via \\#!\[forbid(unsafe\_code)\]\, and sets the Minimum Supported Rust Version (MSRV) to 1.85.0. The package includes Apache-2.0 and MIT license files and documentation.

poem-lambda · high confidence

This example demonstrates an MCP server using the Streamable HTTP transport that exposes both tools and prompts. It includes tools for analyzing code complexity, counting patterns, and tracking review counts, alongside prompts for code review, documentation generation, and debugging assistance, allowing users to interact with a development assistant via HTTP.

examples/mcpserver/prompts-streamable-http · high confidence

A new example application has been added at examples/poem/auth that demonstrates session-based authentication using the Poem framework. The example implements a login flow with a sign-in form, session management via cookies, and a protected index page that displays the logged-in username. It also includes a logout handler to clear the session. The server is configured to listen on 0.0.0.0:3000.

examples/poem/auth · high confidence

Two new example applications have been added to demonstrate ACME (Let's Encrypt) integration with the Poem web framework. The \acme-alpn-01\ example shows how to configure automatic TLS certificate management using the ALPN protocol, while the \acme-http-01\ example demonstrates the HTTP-01 challenge type, including the necessary setup to handle HTTP traffic on port 80 alongside HTTPS on port 443.

examples/poem/acme-alpn-01, examples/poem/acme-http-01 · high confidence

A new example application in \examples/poem/requestid\ demonstrates how to integrate the \RequestId\ middleware with the Poem web framework. The example configures the server to generate request IDs and reuse existing ones if provided via the \x-request-id\ header, ensuring these IDs are available for tracing and logging.

examples/poem/requestid · high confidence

The \poem-grpc\ crate now includes the \routeguide.proto\ definition and a corresponding \mod.rs\ module in \src/example\_generated\. This module exposes the generated Rust code for the standard RouteGuide gRPC service (including \GetFeature\, \ListFeatures\, \RecordRoute\, and \RouteChat\), providing a reference implementation for users to understand how the macro-generated code integrates with the library.

_poem-grpc/src/example\generated · high confidence

The repository now includes a new example in \examples/poem/async-graphql/src/starwars\ that demonstrates a GraphQL API built with the \async-graphql\ library and the \Poem\ web framework. This example implements a Star Wars-themed schema featuring queries for heroes, humans, and droids, along with support for character relationships and episode filtering, providing a reference implementation for users integrating these technologies.

examples/poem/async-graphql/src/starwars · high confidence

A new Rust example demonstrates how to implement optional authentication using the \poem\ and \poem\_openapi\ libraries. The example defines an \OptionalSessionAuthorization\ security scheme that allows endpoints to accept either a valid session cookie or anonymous access, enabling personalized responses for logged-in users while still serving anonymous requests.

examples/openapi/auth-optional-apikey · high confidence

The repository now includes an example demonstrating how to manage ACME certificates manually using the expanded certificate generation process. This example shows how to issue certificates, handle HTTP-01 challenges, and resolve server certificates for a Poem-based application, enabling users to share or send certificates between servers.

examples/poem/acme-expanded-http-01 · high confidence

The \examples/openapi/content-type-accept\ example now illustrates how to handle \Content-Type\ and \Accept\ headers by introducing a custom BCS (Binary Canonical Serialization) payload type. Users can see how to define a \Bcs\<T\>\ payload that serializes and deserializes data using the \bcs\ crate, and how to implement content negotiation in API responses to return either JSON or BCS based on the client's \Accept\ header. The example also shows binding the server to \0.0.0.0\ for external accessibility.

examples/openapi/content-type-accept · high confidence

The \poem-openapi\ library now natively supports a wider range of Rust types in API schemas and serialization. This includes fixed-size arrays (\\[T; N\]\), primitive types like \bool\ and \char\, and standard collections such as \HashMap\, \BTreeMap\, \HashSet\, and \BTreeSet\. It also adds support for external ecosystem types including \bson::oid::ObjectId\, \rust\_decimal::Decimal\, \chrono\ date/time types, \geo\_types\ GeoJSON geometries, and \camino\ UTF-8 paths, ensuring these types are correctly registered in the OpenAPI registry and parsed from/to JSON, parameters, and multipart fields.

poem-openapi/src/types/external · high confidence

Users can now handle multipart form data more effectively with the new \Upload\ and \JsonField\ types. The \Upload\ struct exposes file metadata (name, content type, size) and provides methods to consume the file content as a vector, string, or async reader. The \JsonField\ type allows parsing JSON data from multipart fields, enabling structured JSON payloads within multipart requests.

poem-openapi/src/types/multipart · high confidence

The \poem-mcpserver/src/protocol\ module now provides the foundational data structures for the Model Context Protocol (MCP). This includes definitions for JSON-RPC request handling (supporting single and batch requests), the initialize handshake with server and client capabilities, and the core protocol domains: tools (with input/output schemas and UI metadata), prompts (with argument definitions and message roles), and resources (including templates and read/list operations). The content types have been extended to support text, images, and resource links.

poem-mcpserver/src/protocol · high confidence

Introduces the \poem-grpc\ crate, providing a complete gRPC implementation for the Poem web framework. This includes a gRPC client with configurable endpoints, TLS settings, and compression support (gzip, deflate, brotli, zstd), as well as a server-side implementation supporting unary, client-streaming, server-streaming, and bidirectional streaming RPCs. The library also adds a standard health-check service for monitoring service status and a server reflection service for dynamic discovery of service definitions and file descriptors.

poem-grpc/src · high confidence

The \poem-grpc\ crate is introduced, providing gRPC support for the Poem web framework. This release includes the core library and build tools, along with standard \health.proto\ and \reflection.proto\ definitions to enable service health checks and server-side reflection. The crate requires Rust 1.85.0 or later and is licensed under Apache-2.0/MIT.

poem-grpc · high confidence

This change introduces the \poem-mcpserver\ crate, providing a new implementation of the Model Context Protocol (MCP) server for the Poem web framework. It adds support for defining and exposing MCP tools, prompts, and resources through builder methods on the \McpServer\ struct. The crate includes transport implementations for standard I/O (\stdio\) and streamable HTTP (with configurable session timeouts and SSE support), along with content types for text, images, and JSON responses.

poem-mcpserver/src · high confidence

This entry introduces the \poem-openapi-derive\ crate, providing the procedural macros that power the \poem-openapi\ library. It adds derive macros for \Object\, \Enum\, \Union\, \ApiRequest\, \ApiResponse\, \ResponseContent\, \Multipart\, \Tags\, \OAuthScopes\, \SecurityScheme\, and \NewType\, along with attribute macros \OpenApi\ and \Webhook\. These macros enable automatic OpenAPI schema generation, request/response parsing, and route registration for the Poem web framework.

poem-openapi-derive/src · high confidence

The \poem\ web framework now includes a dedicated Server-Sent Events implementation in \poem::web::sse\. Users can construct SSE responses using \SSE::new()\ with an event stream, optionally setting a \keep\_alive\ interval to send periodic comments that prevent connection timeouts. The response automatically sets the \text/event-stream\ content type, includes \Cache-Control: no-cache\, and adds the \X-Accel-Buffering: no\ header to ensure compatibility with reverse proxies like Nginx that might otherwise buffer the stream.

poem/src/web/sse · high confidence

Adds a new WebSocket implementation to the \poem\ web framework, providing a \WebSocket\ extractor that validates upgrade requests and supports setting known protocols for \Sec-WebSocket-Protocol\ negotiation. Users can now configure the underlying stream via \WebSocketConfig\ and access the configuration after connection. The feature includes a \Message\ type for handling text, binary, ping, pong, and close frames, along with a \WebSocketStream\ for async communication. The implementation also accepts both "websocket" and "WebSocket" casing for the upgrade header to improve browser compatibility.

poem/src/web/websocket · high confidence

This change adds new authentication extractor implementations for API Key, Basic, and Bearer schemes within the \poem-openapi\ crate. Users can now utilize the \ApiKey\, \Basic\, and \Bearer\ structs to extract credentials from requests, supporting API keys in query parameters, headers, and cookies (when the \cookie\ feature is enabled), as well as standard HTTP Basic and Bearer authentication headers. The module also defines the corresponding \ApiKeyAuthorization\, \BasicAuthorization\, and \BearerAuthorization\ traits, along with a \CheckerReturn\ enum to facilitate flexible error handling in security schema checkers.

poem-openapi/src/auth · high confidence

The poem-grpc-build crate now generates Rust client and server code from .proto files. Users can configure the generator via the Config API (e.g., setting output directory, codecs, and map/bytes field types). The generated client supports unary, client-streaming, server-streaming, and bidirectional-streaming RPCs, and allows applying client middlewares and setting send/accept compression encodings. The generated server implements the service trait, exposes an endpoint via IntoEndpoint, enforces HTTP/2, and allows applying server middlewares and setting send/accept compression encodings.

poem-grpc-build/src · high confidence

A new \poem-lambda\ crate has been added to enable running Poem applications on AWS Lambda. This library provides a \run\ function that starts the Lambda runtime and bridges AWS Lambda requests to Poem endpoints, including a \Context\ extractor that allows handlers to access Lambda execution context details such as the request ID.

poem-lambda/src · high confidence

The \poem-mcpserver-macros\ crate is added, providing \\#\[Tools\]\ and \\#\[Prompts\]\ procedural attributes to simplify implementing Model Context Protocol (MCP) capabilities. The \\#\[Tools\]\ macro automatically generates the \Tools\ trait implementation for an \impl\ block, deriving tool metadata, input schemas via \schemars\, and output schemas from return types, while also supporting optional UI resource URIs. The \\#\[Prompts\]\ macro similarly generates the \Prompts\ trait implementation, handling prompt descriptions, parameter validation (including required checks), and argument extraction from the MCP protocol.

poem-mcpserver-macros · high confidence

Adds a new session management subsystem to the Poem framework, providing two middleware implementations: \CookieSession\ for storing session data directly in a signed or encrypted client-side cookie, and \ServerSession\ for storing session data on the server with a session ID cookie. The server-side implementation supports pluggable back-ends via the \SessionStorage\ trait, with built-in \MemoryStorage\ (featuring automatic timeout cleanup) and \RedisStorage\ (for distributed sessions). The session configuration (\CookieConfig\) allows setting standard cookie attributes such as name, path, domain, secure, http\_only, same\_site, max\_age, and partitioned, and supports plain, signed, or private (encrypted) cookie security modes.

poem/src/session · high confidence

The \poem/src/route/internal\ module now contains the core data structures for path and domain routing. The new \radix\tree.rs\ implements a radix tree for matching HTTP request paths, supporting static segments, named parameters (e.g., \:id\), catch-all routes (\\\), and regex-constrained parameters (\\<regex\>\). The new \trie.rs\ implements a trie structure for matching host headers, supporting wildcard subdomains (\+.\) and full wildcards (\\*\). These internal components replace or supplement previous routing logic to provide more efficient and flexible route matching for both URL paths and domain names.

poem/src/route/internal · high confidence

Added two new Rust examples for the poem-openapi library: an API key authentication example demonstrating JWT-based login and header-based API key verification, and a generics example showing how to use generic types in OpenAPI object definitions. The authentication example includes a login endpoint that issues JWT tokens and a protected endpoint requiring a valid API key, while the generics example illustrates handling generic payloads for different types like i32 and String.

examples/openapi/auth-apikey · high confidence

Added two new examples in the MCP server directory: an 'apps-ui' example demonstrating how to expose a UI resource (a color picker) via the MCP Apps protocol, and a 'prompts' example showing how to define and serve prompts (code review, documentation, debugging) alongside tools in a server.

examples/mcpserver · high confidence

Added a new example application in \examples/openapi/todos\ that implements a RESTful Todo API using the Poem framework and SQLite. The application exposes endpoints for creating, retrieving, updating, and deleting todos, along with a Swagger UI for API exploration, and is configured to listen on all network interfaces (0.0.0.0) on port 3000.

examples/openapi/todos · high confidence

A new example application in examples/openapi/union demonstrates the Union type discriminator feature, exposing a POST /put endpoint that accepts and returns a polymorphic object. The example server now listens on 0.0.0.0:3000 instead of localhost, making it accessible from outside the container or host, and exposes the OpenAPI specification in both JSON (/spec) and YAML (/spec\_yaml) formats.

examples/openapi/union · high confidence

Added a new example application in \examples/openapi/auth-multiple\ that demonstrates how to implement multiple authentication schemes (Basic and ApiKey) within a single OpenAPI service using the Poem framework. The example includes a login endpoint that issues JWT tokens and a protected endpoint that validates both Basic credentials and API keys, serving the Swagger UI at the root path.

examples/openapi/auth-multiple · high confidence

Added a new example application that demonstrates how to use the \OperationId\ extension in OpenAPI responses. The example exposes a simple API with a \/hello\ endpoint and includes middleware that logs the operation ID alongside the request URI and response status for each request.

examples/openapi/log-with-operation-id · high confidence

Added three new documentation examples in the \examples/openapi\ directory: \combined-apis\ demonstrates how to merge multiple OpenAPI specifications into a single service endpoint; \content-type-accept\ illustrates handling HTTP Content-Type and Accept headers for mixed data formats (e.g., JSON request, XML response); and \custom-payload\ shows how to implement custom payload wrapper types using BCS serialization. Additionally, the \todos\ example was updated with a \.gitignore\ file to exclude SQLite database files and build artifacts.

examples/openapi · high confidence

Added a new example application in \examples/openapi/upload\ that demonstrates file upload and retrieval capabilities using the \poem\ and \poem-openapi\ frameworks. The application exposes two endpoints: a POST \/api/files\ endpoint for uploading files with metadata (name, description, content type) and a GET \/api/files/:id\ endpoint for retrieving stored files as attachments. It utilizes an in-memory store protected by a mutex to manage file state and serves the Swagger UI at the root path. The server is configured to listen on \0.0.0.0:3000\ to allow external access.

examples/openapi/upload · high confidence

Added two new example applications demonstrating Server-Sent Events (SSE) and Tower middleware integration within the Poem framework. The SSE example shows how to stream periodic events to a browser client, while the Tower layer example demonstrates applying rate limiting via Tower's compatibility layer. Both examples now listen on 0.0.0.0 instead of 127.0.0.1, making them accessible from outside the container or local machine.

examples/poem/sse, examples/poem/tower-layer · high confidence

Added two new example applications demonstrating the Poem web framework: a 'hello-world' example that serves a simple text route with tracing middleware, and a 'json' example that handles POST requests with JSON payloads. Both examples bind to 0.0.0.0:3000 and use the modern handler syntax.

examples/poem/hello-world · high confidence

Added a new example in \examples/openapi/combined-apis\ that demonstrates combining multiple API definitions (Api1, Api2, Api3) into a single service using \OpenApiService::new\ with a tuple. The example configures Swagger UI, sets the server address to \0.0.0.0:3000\, and uses \tracing\_subscriber\ for logging.

examples/openapi/combined-apis · high confidence

Added a new example application in \examples/pem/cookie-session\ that demonstrates how to implement user sessions using \CookieSession\ middleware. The example shows a simple counter endpoint that persists state across requests via cookies, configured to run on all interfaces (0.0.0.0) at port 3000.

examples/poem/cookie-session · high confidence

The endpoint module now includes new composition methods for chaining request processing: \before\ (pre-process request), \after\ (post-process result), \and\_then\ (chain on success), and \around\ (wrap with full request/response access). It also adds error handling extensions \catch\_error\ (typed error catch), \catch\_all\_error\ (generic error catch), \inspect\_err\ (typed inspection), and \inspect\_all\_err\ (generic inspection). Additionally, new integration endpoints are provided: \EmbeddedFileEndpoint\ and \EmbeddedFilesEndpoint\ for serving files from \rust-embed\ bundles, a \PrometheusExporter\ endpoint for metrics, and a \TowerCompatExt\ trait to convert Tower services into Poem endpoints.

poem/src/endpoint · high confidence

Added a new example application that shows how to handle 404 Not Found errors in a Poem web server. The example registers a custom error handler using \catch\_error\ to intercept \NotFoundError\ exceptions and return a custom response with the text "haha" and a 404 status code, instead of the default error page. It also demonstrates basic route setup with a parameterized path and server binding to all interfaces on port 3000.

examples/poem/handling-404 · high confidence

Added a new example application in \examples/poem/upload\ that demonstrates how to handle multipart file uploads using the Poem framework. The example provides a simple HTML form for selecting files and a handler that processes the uploaded data, listening on all network interfaces (0.0.0.0) at port 3000.

examples/poem/upload · high confidence

The examples/grpc/middleware directory now provides a working example of gRPC middleware implementation using the poem-grpc 2 library. This includes a server that listens on 0.0.0.0:3000 and a client that connects to it, demonstrating how to apply custom middleware (ClientMiddleware and ServerMiddleware) to log request paths. The example uses the new poem-grpc ClientConfig API for client construction.

examples/grpc/middleware, examples/openapi/hello-world · high confidence

The middleware module now includes several new capabilities: \AddData\ allows injecting arbitrary data into request extensions; \CatchPanic\ intercepts panics and converts them into configurable error responses; \CookieJarManager\ provides signed and private cookie support with a configurable key; \Csrf\ adds Cross-Site Request Forgery protection with AES256-encrypted tokens and configurable cookie attributes; \ForceHttps\ redirects HTTP requests to HTTPS with optional port and filter configuration; \NormalizePath\ standardizes request paths by trimming, merging, or adding trailing slashes; \PropagateHeader\ copies specified request headers to the response; and \RequestId\ generates or reuses unique request IDs for tracing. These additions expand the framework's built-in middleware toolkit for common security, routing, and observability patterns.

poem/src/middleware · high confidence

The \poem/src/route\ module now exposes dedicated routing objects that allow matching requests based on criteria beyond the URL path. \RouteDomain\ enables routing based on the \Host\ header using wildcard patterns, \RouteMethod\ routes based on the HTTP method (returning \MethodNotAllowedError\ for unsupported methods instead of \NotFoundError\), and \RouteScheme\ routes based on the request scheme (HTTP/HTTPS) with a configurable fallback. These components integrate with the existing \Route\ object to provide more granular control over request dispatching.

poem/src/route · high confidence

The \poem-openapi\ payload module now includes several new types to handle diverse HTTP content scenarios. Users can use \Attachment\ to serve files with configurable \Content-Disposition\ headers (inline or attachment) and filenames, and \Base64\ to handle binary data encoded as Base64 strings. New \Html\ and \Form\ payloads allow serving HTML content and parsing URL-encoded form data, respectively. Additionally, \EventStream\ supports Server-Sent Events (SSE) with configurable keep-alive intervals and custom event conversion functions. These types integrate with the existing \Binary\, \Json\, \PlainText\, \Xml\, and \Yaml\ payloads to provide a comprehensive set of tools for request parsing and response generation.

poem-openapi/src/payload · high confidence

The \poem::web\ module now includes new extractors to simplify accessing common request data. Developers can use \Accept\ to parse and sort MIME types from the \Accept\ header, \RemoteAddr\ and \LocalAddr\ to access the peer and server socket addresses, and \CsrfToken\ and \CsrfVerifier\ to handle CSRF protection when the middleware is enabled. These types implement \FromRequest\, allowing them to be used directly in handler arguments.

poem/src/web · high confidence

Added a new example in \examples/mcpserver/resources\ that demonstrates how to implement the MCP Resources protocol. The example server exposes static resources for application settings and status, as well as a URI template to dynamically read environment variables, and includes a static README resource served via the UI.

examples/mcpserver/resources · high confidence

A new example server at examples/mcpserver/counter-streamable-http demonstrates the streamable-HTTP transport for the Model Context Protocol, running on port 8000 with CORS support, while the original stdio-based example remains at examples/mcpserver/counter. Both examples expose the same counter tools (increment, decrement, get\_value), giving users a choice between local stdio communication and network-based HTTP communication for interacting with MCP servers.

examples/mcpserver/counter · high confidence

Added a new \poem::test\ module providing a \TestClient\ for sending requests to endpoints, a \TestRequestBuilder\ for constructing requests with query parameters, headers, and bodies (including JSON, YAML, XML, form, and multipart data), and a \TestResponse\ with assertion helpers for status codes, headers, and body content (text, bytes, JSON, XML, YAML).

poem/src/test · high confidence

The \poem-openapi/src/types\ module introduces several new type wrappers and parsing capabilities to enhance OpenAPI schema generation. A new \Any\<T\>\ type allows generic JSON/XML values to be handled flexibly, while \Base64\<T\>\ and \Binary\<T\>\ provide dedicated support for encoding and decoding binary data in API payloads. The \MaybeUndefined\<T\>\ type enables precise handling of optional fields by distinguishing between undefined, null, and present values, which is critical for partial updates. Additionally, new string types like \Email\ and \Hostname\ are added with built-in validation, and the \ParseError\ type is refined to provide more detailed error messages. These changes collectively improve the library's ability to generate accurate OpenAPI schemas for complex data structures and handle diverse input formats.

poem-openapi/src/types · high confidence

Users can now use \Duration\, \Timestamp\, \Struct\, and \Value\ types from the \prost\_wkt\_types\ crate directly in their OpenAPI schemas. This change adds type implementations that allow these protobuf well-known types to be parsed from and serialized to JSON, enabling seamless integration of these standard types in API definitions.

_poem-openapi/src/types/external/prost\_wkt\types · high confidence

The \\#\[handler\]\ macro now supports functions with generic type parameters, automatically generating a struct with PhantomData fields and a manual \Default\ implementation so that generic handlers can be instantiated without requiring the \Default\ trait on the generic types themselves. This change also preserves function documentation attributes in the generated code.

poem-derive/src · high confidence

Added a new example in \examples/poem/tls-reload\ that demonstrates how to reload TLS certificates at runtime using the Poem framework. The example includes a Rustls-based server configuration that periodically loads certificate and key files (\cert.pem\ and \key.pem\) from the filesystem, allowing for seamless certificate rotation without restarting the application. The server listens on \0.0.0.0:3000\ and serves a simple "hello world" response.

examples/poem/tls-reload · high confidence

The \src\ directory has removed the foundational HTTP server implementation, including the \Body\, \Endpoint\, \Error\, \Request\, \Response\, \Route\, and \Server\ modules. This deletion eliminates the framework's ability to define handlers, manage routing, process HTTP requests and responses, and serve traffic, effectively stripping the library of its core web-serving functionality.

src · high confidence

The \src/web/path/mod.rs\ file, which provided the \Path\<T\>\ extractor for deserializing route parameters, has been removed from the codebase. This change eliminates the ability to automatically extract and deserialize path parameters into typed structs via the \FromRequest\ trait in this specific module location.

src/web/path · high confidence

The hello\_world example has been removed from the examples directory. This file previously demonstrated a basic server setup using the poem crate, including route definition and server startup, but is no longer included in the project.

examples · high confidence

The users-crud example now serves a complete REST API for managing users (create, read, update, delete) with an integrated Swagger UI. The server is configured to listen on all network interfaces (0.0.0.0) instead of just localhost, allowing external access, and uses the synchronous Server::new method for startup.

examples/openapi/users-crud · high confidence

The graceful-shutdown example now listens on 0.0.0.0:3000 instead of 127.0.0.1, making the server accessible from outside the host. It also demonstrates a configurable shutdown timeout by passing a 5-second Duration to Server::run\_with\_graceful\_shutdown, ensuring the server waits up to that duration for in-flight requests to complete before exiting.

examples/poem/graceful-shutdown · high confidence

The \poem-openapi\ parameter module has been restructured into dedicated files (\cookie.rs\, \header.rs\, \path.rs\, \query.rs\) and re-exported via \mod.rs\. This change introduces support for the \ignore\_case\ option in \ExtractParamOptions\, allowing cookie, header, and query parameters to be matched case-insensitively. Additionally, the \Query\ extractor now supports the \explode\ attribute; when disabled (default), multiple query values are parsed from a single comma-separated string, while enabling it allows parsing multiple distinct values. The module also adds \CookiePrivate\ and \CookieSigned\ extractors for handling encrypted and signed cookies respectively.

poem-openapi/src/param · high confidence

The OpenAPI registry implementation has been restructured to improve generated specification quality and add webhook support. A new \clean\_unused\ module automatically removes schema definitions that are not referenced by any API operation or webhook, resulting in smaller, cleaner OpenAPI documents. Additionally, the registry now supports the \webhooks\ field in the OpenAPI 3.0.0 specification, allowing users to define and serialize webhook endpoints alongside standard API paths.

poem-openapi/src/registry · high confidence

The \Path\ extractor in \poem/src/web/path\ has been refactored to use a new \PathDeserializer\ that directly deserializes URL path segments into types implementing \serde::Deserialize\. This change replaces the previous internal \Params\ wrapper with a simple tuple of \(String, String)\ pairs, allowing path parameters to be extracted into structs, tuples, or single values via standard Serde deserialization logic. Users can now define handler arguments like \Path(Params { user\_id, team\_id })\ where \Params\ is a struct with fields matching the path segment names, or use tuples like \Path((user\_id, team\_id))\ for positional extraction.

poem/src/web/path · high confidence

This release introduces a major architectural overhaul of the framework, migrating the underlying HTTP implementation from Hyper 0.14 to Hyper 1.x. This shift necessitates a complete redesign of the core types: \Request\ and \Response\ are now distinct structs wrapping \http\_body\_util::Body\ and \BoxBody\, replacing the previous opaque body handling. The \Server\ API has been simplified; \Server::new\ is no longer asynchronous and returns the server instance directly, while \Server::run\ is now a synchronous method that returns a future, and graceful shutdown is handled via \run\_with\_graceful\_shutdown\ which accepts a signal future and an optional timeout. New abstractions include the \Addr\ enum for unified network address handling (supporting TCP and Unix sockets) and a refactored \Error\ type that supports \anyhow\ and \eyre\ integration via features. These changes represent a breaking update to the framework's foundation, requiring users to adapt to the new Hyper 1.x body model and server lifecycle.

poem/src · high confidence

The \src/web\ module has been removed, eliminating the previous \FromRequest\ and \IntoResponse\ traits along with their associated extractor types (\Data\, \Json\, \Path\). This change removes the legacy mechanism for extracting request data and generating responses, requiring users to adopt the new extraction and response handling patterns introduced in the broader framework update.

src/web · high confidence

The Route Guide example has been rewritten to use the \poem-grpc\ framework instead of the previous implementation. This new version includes a Rust-based service implementation (\main.rs\) and data loading logic (\data.rs\) that serves route guide features from a JSON database. Additionally, the server now binds to \0.0.0.0:3000\ instead of \127.0.0.1\, making the service accessible from external networks rather than just localhost.

examples/grpc/routeguide · high confidence

The \StaticFileResponse\ type now implements the \ApiResponse\ trait, ensuring that static file serving endpoints are correctly documented in the generated OpenAPI schema. This change adds metadata for standard headers (ETag, Last-Modified, Content-Type) and explicitly defines response status codes (200, 304, 400, 404, 412, 416, 500) so that API consumers see accurate documentation for static file interactions.

poem-openapi/src/response · high confidence

The static-files example now uses the renamed \StaticFilesEndpoint\ to serve files from the \./poem/static-files/files\ directory, enabling directory listing via \show\_files\_listing()\. The example also listens on \0.0.0.0:3000\ instead of \127.0.0.1\ and initializes tracing via \tracing\_subscriber\. New static assets, including HTML pages and files with non-ASCII names, have been added to the served directory.

examples/poem/static-files · high confidence

The TLS example in examples/poem/tls has been updated to use the Rustls crate for TLS configuration instead of native-tls, and the server now binds to 0.0.0.0 instead of 127.0.0.1, making it accessible from external networks. The example also includes a new combined-listeners example demonstrating how to bind multiple TCP listeners.

examples/poem/tls · high confidence

The Tonic example has been moved from the active examples directory to the disabled folder, indicating it is currently non-functional or experimental. Within the example, the implementation now uses \tower::buffer::Buffer\ to wrap the Tonic service, replacing the previous direct integration with Poem's compatibility layer. Additionally, the \\#\[tonic::async\_trait\]\ attribute has been removed from the \Greeter\ implementation, relying on native async traits instead. The server binding address has also been changed from \127.0.0.1\ to \0.0.0.0\ to allow external connections.

examples/disabled/tonic · medium confidence

The listener subsystem has been restructured around a new \Listener\ and \Acceptor\ trait hierarchy, replacing the previous \IntoAcceptor\ naming. This change introduces a \HandshakeStream\ wrapper to handle asynchronous TLS handshakes cleanly and enables TLS certificate rotation by accepting a \Stream\ of configuration updates (e.g., \RustlsConfig\, \NativeTlsConfig\, \OpensslTlsConfig\) rather than a single static config. The \TcpListener\ now automatically disables the Nagle algorithm (\tcp\_nodelay\) for improved latency, and \UnixListener\ gains support for setting socket permissions and ownership. Additionally, a \Combined\ listener allows combining two listeners into one, and acceptors can be dynamically boxed via \boxed()\.

poem/src/listener · high confidence

The test certificates and private keys in the listener's certificate directory have been regenerated, and a new shell script (build-a-pki.sh) has been added to automate the creation of this PKI structure. This ensures the local development and testing environment uses a consistent, freshly generated set of certificates for TLS operations.

poem/src/listener/certs · high confidence

The \poem-openapi\ crate has been updated to version 5.1.15, introducing support for \num::NonZero\ types, externally tagged unions, and deep linking in Swagger UI, while also fixing webhook nesting issues. This release also bumps the \derive\_more\ dependency to version 2.0 and updates the Minimum Supported Rust Version (MSRV) to 1.85.0. Additionally, Apache 2.0 and MIT license files have been added to the project.

poem-openapi · high confidence

The poem-openapi crate has been updated to version 5, introducing full OpenAPI v3 specification support and a redesigned macro-based API. This release adds new macros for defining API operations, request/response types, and security schemes, while removing older macros like OneOf in favor of Union and AnyOf. It introduces support for server variables, extra headers, and multiple UI documentation tools including Swagger UI, RapiDoc, Redoc, Scalar, and Stoplight Elements. The library now requires Poem 3.x and includes improved error handling with specific status codes for parameter and content-type errors.

poem-openapi/src · high confidence

Added comprehensive test suite for poem-openapi macros and types; Added integration tests for prompts, resources, and tools.

The examples directory and all Poem crates now use Cargo workspace inheritance for dependency versions, centralizing version management in the root Cargo.toml. This ensures that all examples and library crates consistently use the same versions of shared dependencies like tokio, serde, and tracing-subscriber, reducing the risk of version conflicts and simplifying dependency updates across the project.

(dependencies) · high confidence

The Poem web framework has been updated to version 3.1.12. This release bumps the \tokio-tungstenite\ dependency to 0.27, updates the \opentelemetry\ dependency, and upgrades \x509-parser\ to version 0.17.

poem · high confidence

The poem-derive, poem-grpc-build, and poem-openapi-derive crates now include explicit LICENSE-APACHE and LICENSE-MIT files. This clarifies the dual-licensing terms (Apache 2.0 or MIT) for users and distributors of these specific components, ensuring compliance with copyright and redistribution requirements.

poem-derive, poem-grpc-build, poem-openapi-derive · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 61 → 58 (-3.3)
• Rubric changed (rubric-2026.09.11 → rubric-2026.09.18) — scores are not directly comparable.

• Code Health 89 → 89 (+0.0)
• Architecture 100 → 92 (-8.5)
• Maturity 53 → 49 (-3.7)
• Readiness 56 → 57 (+1.0)
• Security 65 → 69 (+4.4)
• Accessibility 64 (new)
• Performance 100 (new)

• Documentation: no installation or build instructions (README.md)
• Documentation: no licence statement (README.md)
• Documentation: no usage examples (README.md)
• Most significant orphaned file (poem/src/route/router.rs)
• Off-boarding risk: anonymized user #1

• Ambiguous naming for body extraction. Same issue as Request. take_body vs into_body creates confusion about whether the response object remains valid or is consumed.
• Ambiguous naming for body extraction. take_body implies taking ownership and replacing the body with an empty/default state (common in Option-like patterns), while into_body implies consuming the request to extract the body. If both exist, it is unclear when to use which. Often, into_body is the standard for consuming Self, while take_body might be redundant or imply a different mutation strategy.
• Ambiguous naming for path parameters. path_params and params likely refer to the same concept (URL path parameters like /users/:id). Having two methods with slightly different names for the same data source is confusing. One might be a legacy alias or handle different parsing contexts, but the surface does not clarify this.
• Dependency hygiene PARTLY measured — Cargo dependencies read, no committed lock to grade for currency
• Inconsistent return type for header access. The signature shows str as the return type, but HTTP headers can be multi-valued. Returning a single str (likely the first value) is inconsistent with standard practices where multi-value headers are common. If this is intentional, it should be named header_value or header_first. If it returns a string representation of all values, it should be named header_values or similar. The name header is too generic for a method that likely discards data or picks an arbitrary value.
• Low cohesion: BoxIo (LCOM4 4) (poem/src/listener/mod.rs)
• Low cohesion: HandshakeStream (LCOM4 4) (poem/src/listener/handshake_stream.rs)
• Most significant orphaned file (poem/src/middleware/cors.rs)
• Off the main sequence: poem
• Off the main sequence: poem-grpc-build
• Off-boarding risk: anonymized user #1
• Semantic ambiguity between bytes and vec. In Rust, Vec<u8> and Bytes are distinct types with different memory ownership semantics. into_bytes likely returns Bytes (zero-copy optimized), while into_vec returns Vec<u8>. However, naming them similarly without clear distinction in the method name (e.g., into_bytes_vec) can confuse users expecting identical behavior or unsure of the underlying type.
• Split poem

• 2 commits — 1 feature/other, 1 fixes

• poem/src — 2 commits

• fix: fix(grpc): correct content-type for JsonCodec (#1191)
• change: feat(poem): allow customization of any HTTP2 parameters (#1093)

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

poem-web/poem was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.