A curated list of examples for ntex, a framework for composable network services in Rust.
The examples are companions to the ntex guide: the guide explains the concepts, and the examples show them in complete, runnable applications. Each example README ends with links to the matching guide sections. For individual types and functions, see the API documentation.
New to ntex? Read the introduction and the chapters on services and pipelines first, then use the table below to pair each chapter with examples.
The examples' tests follow the guide's testing advice; see testing routes, test servers and testing I/O.
- Rust 1.97 or later
- Some examples need extra services or libraries (PostgreSQL and
libpq, MySQL, SQLite, OpenSSL); see the README in each example directory.
All examples are members of a single Cargo workspace and use ntex 4.
Run an example by package name from the repository root, or change into its
directory and use cargo run:
cargo run -p basics
# or
cd basics && cargo runSome examples read files relative to their own directory (certificates,
databases, static files), so their READMEs use the second form. Most examples listen on
http://127.0.0.1:8080/; check the example's README or main.rs for the
address. Examples with multiple binaries (for example the websocket server and
client) are started with cargo run --bin <name>.
To build or test the whole workspace:
cargo build
cargo testBuilding extras/todo and extras/simple-auth-server requires the
PostgreSQL client library (libpq).
Guide: Services and Service Pipelines.
| Example | Description |
|---|---|
| service/readiness | Readiness and backpressure: a concurrency limit and a gate that fails readiness |
Guide: Applications and Routing, Filters and Middleware, Application State.
| Example | Description |
|---|---|
| basics | Routing, path parameters, sessions, static files and error pages |
| error | Custom error domain rendered as uniform JSON responses |
| middleware | Writing middleware: body logging, redirects and the middleware life cycle |
| state/process | Process-wide and per-worker application state |
| state/state-accumulation | Per-connection state, including TLS connection info |
| state/web-state | web::App state in middleware, filters, handlers and errors |
| Example | Description |
|---|---|
| server/tokio | The basics example running on the Tokio runtime |
| server/run-in-thread | Running the server in a separate thread and stopping it |
| server/shutdown | Shutting down the server remotely or with a signal |
| server/unix-socket | Serving HTTP over a Unix domain socket |
| server/docker | Building and running an ntex application in Docker |
Guide: Extractors and Responders.
| Example | Description |
|---|---|
| extractors/json | JSON request and response handling |
| extractors/form | URL-encoded form handling |
| extractors/multipart | File uploads with multipart forms |
Guide: Application State and blocking work.
| Example | Description |
|---|---|
| db/async-db | Running blocking SQLite queries asynchronously |
| db/async-pg | PostgreSQL with tokio-postgres and deadpool |
| db/r2d2 | SQLite with an r2d2 connection pool |
| db/diesel | Diesel with SQLite |
| db/juniper | GraphQL with Juniper |
| db/graphql | GraphQL with Juniper and MySQL |
Guide: Extractors and Responders.
| Example | Description |
|---|---|
| templates/askama | Askama templates |
| templates/handlebars | Handlebars templates |
| templates/tera | Tera templates |
| templates/yarte | Yarte templates |
| Example | Description |
|---|---|
| tls/openssl | OpenSSL HTTPS client/server and mutual authentication |
| tls/rustls | rustls HTTPS client/server, providers and mutual authentication |
| tls/schannel | Windows TLS, store identities and explicit client authentication |
| tls/x509 | Portable identity loading, certificate inspection and peer authorization |
Start with the local certificate setup, and read Securing connections with TLS in the guide.
Guide: WebSocket Support.
| Example | Description |
|---|---|
| websockets/basic | WebSocket echo server and client, over plain TCP or TLS |
| websockets/lowlevel | WebSocket server and client using the low-level API |
| websockets/chat | Multi-room WebSocket chat server with a browser client |
| websockets/tcp-chat | Chat server with WebSocket and TCP clients |
Guide: Building gRPC Services and Clients.
| Example | Description |
|---|---|
| protocols/grpc-helloworld | A unary service and its generated client |
| protocols/grpc-custom-types | Replacing generated field types with your own Rust types |
| protocols/grpc-routing-client | A custom client transport that routes calls across backends |
| protocols/grpc-server | Streaming methods, errors, several services, limits and HTTP/2 configuration |
| protocols/grpc-tls | gRPC server and client over TLS with rustls |
Guide: HTTP/2 with ntex-h2.
| Example | Description |
|---|---|
| protocols/http2 | Standalone HTTP/2 server and client: per-stream state, flow control, backpressure and trailers |
Guide: MQTT with ntex-mqtt.
| Example | Description |
|---|---|
| protocols/mqtt | MQTT server and client over a binary WebSocket transport |
Guide: Testing state-aware function services and testing routes.
| Example | Description |
|---|---|
| tests/mockall | Testing a state-aware service with mockall |
| tests/shimforge | Testing a state-aware service with shimforge |
| Example | Description |
|---|---|
| extras/async-ex1 | Chaining async steps, including outgoing HTTP client requests |
| extras/async-ex2 | Nested resource registration through application configuration |
| extras/http-client | HTTPS requests with the ntex HTTP client |
| extras/http-proxy | HTTP proxy forwarding requests to another server |
| extras/json-error | Rendering errors as JSON responses |
| extras/jsonrpc | JSON-RPC over HTTP server |
| extras/server-sent-events | Server-sent events (EventSource) |
| extras/cookie-session | Cookie-based sessions |
| extras/cookie-auth | Cookie-based identity and authentication |
| extras/simple-auth-server | Registration and login with email invitations, Diesel and PostgreSQL |
| extras/todo | Todo application with Diesel, PostgreSQL and Tera templates |
This project is licensed under either of:
- Apache License, Version 2.0 (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)
at your option.