Ntex

https://docs.rs/ntex/latest/
Admin
Ntex is a framework for composable network services in Rust, providing utilities for building...
Tokens:365,095
Snippets:2,984
Trust Score:9.7
Update:2 months ago
Show doc for...
Tokens:
Raw
### Example usage of server_with

Source: https://docs.rs/ntex/latest/ntex/web/test/fn.server_with.html

Demonstrates starting a test server with a specific port configuration and a simple handler.

```rust
use ntex::web::{self, test, App, HttpResponse};

async fn my_handler() -> HttpResponse {
    HttpResponse::Ok().into()
}

#[ntex::test]
async fn test_example() {
    let mut srv = test::server_with(test::config().h1().port(4000), ||
        App::new().service(web::resource("/").to(my_handler))
    );

    let req = srv.get("/");
    let response = req.send().await.unwrap();
    assert!(response.status().is_success());
}
```

--------------------------------

### Basic HTTP Request Usage

Source: https://docs.rs/ntex/latest/ntex/client/struct.Client.html

Example showing how to initialize a client and perform a GET request.

```rust
use ntex::client::Client;

#[ntex::main]
async fn main() {
    let mut client = Client::new().await;

    let res = client.get("http://www.rust-lang.org") // <- Create request builder
        .header("User-Agent", "ntex::web")
        .send()                             // <- Send http request
        .await;                             // <- send request and wait for response

     println!("Response: {:?}", res);
}
```

--------------------------------

### Configure a resource with a route

Source: https://docs.rs/ntex/latest/ntex/web/struct.Resource.html

Example of registering a resource for the root path with a GET handler.

```rust
use ntex::web::{self, App, HttpResponse};

fn main() {
    let app = App::new().service(
        web::resource("/")
            .route(web::get().to(|| async { HttpResponse::Ok() })));
}
```

--------------------------------

### Trim start matches example

Source: https://docs.rs/ntex/latest/ntex/util/struct.ByteString.html

Demonstrates trimming characters from the start of a string slice.

```rust
let x: &[_] = &['1', '2'];
assert_eq!("12foo1bar12".trim_start_matches(x), "foo1bar12");
```

--------------------------------

### run

Source: https://docs.rs/ntex/latest/src/ntex/web/server.rs.html

Starts the HTTP server and begins listening for incoming connections.

```APIDOC
## run

### Description
Starts listening for incoming connections. This method spawns multiple HTTP workers in separate threads and performs the accept loop for each bound address.
```

--------------------------------

### Start a WebSocket service with subprotocol negotiation

Source: https://docs.rs/ntex/latest/ntex/web/ws/fn.start.html

Demonstrates how to extract a supported subprotocol from the request and initiate a WebSocket service using the start function.

```rust
use ntex::web::{self, HttpRequest, HttpResponse};
use ntex::web::ws;

async fn handler(req: HttpRequest) -> Result<HttpResponse, web::Error> {
    // Note: convert to owned String since `req` will be moved
    let chosen: Option<String> = ws::subprotocols(&req)
        .find(|p| *p == "graphql-ws" || *p == "graphql-transport-ws")
        .map(String::from);

    ws::start(req, chosen, factory).await
}
```

--------------------------------

### start_with

Source: https://docs.rs/ntex/latest/ntex/web/ws/fn.start_with.html

Starts a websocket service with manual control logic and an optional subprotocol.

```APIDOC
## Function: start_with

### Description
Starts a websocket service handling raw `DispatchItem` messages requiring manual control/stop logic. If a subprotocol is provided, the `Sec-Websocket-Protocol` header is included in the response.

### Signature
`pub async fn start_with<T, F, P, Err>(req: HttpRequest, subprotocol: Option<P>, factory: F) -> Result<HttpResponse, Err>`

### Parameters
- **req** (HttpRequest) - The incoming HTTP request.
- **subprotocol** (Option<P>) - The chosen subprotocol to include in the response header.
- **factory** (F) - The service factory used to create the websocket service.

### Constraints
- **T**: Must implement `ServiceFactory<DispatchItem<Codec>, WsSink>`.
- **F**: Must implement `IntoServiceFactory<T, DispatchItem<Codec>, WsSink>`.
- **P**: Must implement `AsRef<str>`.
- **Err**: Must implement `From<T::InitError>` and `From<HandshakeError>`.
```

--------------------------------

### HttpServer::run

Source: https://docs.rs/ntex/latest/ntex/web/struct.HttpServer.html

Starts the HTTP server and begins processing requests.

```APIDOC
## HttpServer::run

### Description
Starts the server and runs the event loop to handle incoming HTTP requests.

### Signature
`pub async fn run(self) -> std::io::Result<()>`
```

--------------------------------

### Configure WebAppConfig

Source: https://docs.rs/ntex/latest/src/ntex/web/config.rs.html

Example of initializing and setting properties on a WebAppConfig instance.

```rust
let cfg = WebAppConfig::default()
    .set_host("www.example.org".to_string())
    .set_local_addr("127.0.0.1:8080".parse().unwrap())
    .set_pool_size(256);
assert_eq!(cfg.host(), "www.example.org");
assert_eq!(cfg.local_addr(), "127.0.0.1:8080".parse().unwrap());
assert_eq!(cfg.pool_size, 256);
```

--------------------------------

### Perform an HTTP GET request with ntex

Source: https://docs.rs/ntex/latest/ntex/client/index.html

Demonstrates initializing a client and executing a GET request with custom headers.

```rust
use ntex::client::Client;

#[ntex::main]
async fn main() {
   let mut client = Client::new().await;

   let response = client.get("http://www.rust-lang.org") // <- Create request builder
       .header("User-Agent", "ntex::web")
       .send()                                           // <- Send http request
       .await;

    println!("Response: {:?}", response);
}
```

--------------------------------

### start

Source: https://docs.rs/ntex/latest/src/ntex/web/ws.rs.html

Starts a websocket service handling Frame messages with automatic control/stop logic.

```APIDOC
## start<T, F, P, Err>(req: HttpRequest, subprotocol: Option<P>, factory: F) -> Result<HttpResponse, Err>

### Description
Initializes a WebSocket service that handles `Frame` messages. If a subprotocol is provided, it is included in the response headers.

### Parameters
- **req** (HttpRequest) - Required - The incoming HTTP request.
- **subprotocol** (Option<P>) - Optional - The subprotocol to negotiate.
- **factory** (F) - Required - The service factory for handling WebSocket frames.
```

--------------------------------

### Initiate Server Builder

Source: https://docs.rs/ntex/latest/ntex/server/fn.build.html

Use this function to start the server building process.

```rust
pub fn build() -> ServerBuilder
```

--------------------------------

### Server::builder

Source: https://docs.rs/ntex/latest/ntex/server/type.Server.html

Starts the streaming server building process.

```APIDOC
## pub fn builder() -> ServerBuilder

### Description
Start streaming server building process.
```

--------------------------------

### Testing an application with init_service

Source: https://docs.rs/ntex/latest/ntex/web/test/fn.init_service.html

Example demonstrating how to initialize an application service and execute a test request against it.

```rust
use ntex::service::Service;
use ntex::http::StatusCode;
use ntex::web::{self, test, App, HttpResponse};

#[ntex::test]
async fn test_init_service() {
    let mut app = test::init_service(
        App::new()
            .service(web::resource("/test").to(|| async { HttpResponse::Ok() }))
    ).await;

    // Create request object
    let req = test::TestRequest::with_uri("/test").to_request();

    // Execute application
    let resp = app.call(req).await.unwrap();
    assert_eq!(resp.status(), StatusCode::OK);
}
```

--------------------------------

### start_with

Source: https://docs.rs/ntex/latest/src/ntex/web/ws.rs.html

Starts a websocket service handling raw DispatchItem messages requiring manual control/stop logic.

```APIDOC
## start_with<T, F, P, Err>(req: HttpRequest, subprotocol: Option<P>, factory: F) -> Result<HttpResponse, Err>

### Description
Initializes a WebSocket service that handles raw `DispatchItem` messages, allowing for manual control over the connection lifecycle.

### Parameters
- **req** (HttpRequest) - Required - The incoming HTTP request.
- **subprotocol** (Option<P>) - Optional - The subprotocol to negotiate.
- **factory** (F) - Required - The service factory for handling raw dispatch items.
```

--------------------------------

### start

Source: https://docs.rs/ntex/latest/ntex/web/ws/index.html

Starts a WebSocket service that handles Frame messages with automatic control and stop logic, including the chosen subprotocol in the response.

```APIDOC
## start

### Description
Starts a websocket service handling Frame messages with automatic control/stop logic, including the chosen subprotocol in the response.
```

--------------------------------

### App::configure

Source: https://docs.rs/ntex/latest/src/ntex/web/app.rs.html

Runs external configuration logic to modularize application setup.

```APIDOC
## fn configure<F>(mut self, f: F) -> Self

### Description
Executes an external configuration function to register resources or services, allowing for modular application structure.

### Parameters
- **f** (F) - Required - A closure that accepts a mutable reference to a ServiceConfig.
```

--------------------------------

### Implement Configuration for WebAppConfig

Source: https://docs.rs/ntex/latest/ntex/service/cfg/trait.Configuration.html

Example implementation of the NAME constant for WebAppConfig.

```rust
const NAME: &str = "Web app configuration"
```

--------------------------------

### HttpServer Configuration and Initialization

Source: https://docs.rs/ntex/latest/src/ntex/web/server.rs.html

Methods for configuring the ntex HTTP server before starting it.

```APIDOC
## HttpServer::new

### Description
Creates a new instance of an HTTP server using the provided application factory.

### Signature
`pub fn new(factory: F) -> Self`

## HttpServer::workers

### Description
Sets the number of worker threads to start. Defaults to the number of available logical CPUs.

### Signature
`pub fn workers(mut self, num: usize) -> Self`

## HttpServer::backlog

### Description
Sets the maximum number of pending connections. Should be called before `bind()`.

### Signature
`pub fn backlog(mut self, backlog: i32) -> Self`

## HttpServer::maxconn

### Description
Sets the maximum per-worker number of concurrent connections. Defaults to 25k.

### Signature
`pub fn maxconn(mut self, num: usize) -> Self`

## HttpServer::server_hostname

### Description
Sets the server host name used for URL generation.

### Signature
`pub fn server_hostname<T: AsRef<str>>(self, val: T) -> Self`
```

--------------------------------

### Basic Response Configuration

Source: https://docs.rs/ntex/latest/src/ntex/http/response.rs.html

Examples of setting status codes, headers, and connection properties.

```rust
#[test]
    fn test_basic_builder() {
        let resp = Response::Ok().header("X-TEST", "value").finish();
        assert_eq!(resp.status(), StatusCode::OK);
    }

    #[test]
    fn test_upgrade() {
        let resp = Response::build(StatusCode::OK)
            .upgrade("websocket")
            .finish();
        assert!(resp.upgrade());
        assert_eq!(
            resp.headers().get(header::UPGRADE).unwrap(),
            HeaderValue::from_static("websocket")
        );
    }

    #[test]
    fn test_force_close() {
        let resp = Response::build(StatusCode::OK).force_close().finish();
        assert!(!resp.keep_alive());
    }
```

--------------------------------

### Start an ntex HttpServer

Source: https://docs.rs/ntex/latest/ntex/web/struct.HttpServer.html

Initializes and runs an HttpServer instance, binding it to a local address.

```rust
use ntex::web::{self, App, HttpResponse, HttpServer};

#[ntex::main]
async fn main() -> std::io::Result<()> {
    HttpServer::new(
        async || App::new().service(web::resource("/").to(|| async { HttpResponse::Ok() }))
    )
        .bind("127.0.0.1:0")?
        .run()
        .await
}
```

--------------------------------

### Run HttpServer

Source: https://docs.rs/ntex/latest/src/ntex/web/server.rs.html

Starts the server and its workers. Panics if no address can be bound or the system is not configured.

```rust
    /// Start listening for incoming connections.
    ///
    /// This method starts number of http workers in separate threads.
    /// For each address this method starts separate thread which does
    /// `accept()` in a loop.
    ///
    /// This methods panics if no socket address can be bound or an ntex system
    /// is not yet configured.
    ///
    /// ```rust,no_run
    /// use ntex::web::{self, App, HttpResponse, HttpServer};
    ///
    /// #[ntex::main]
    /// async fn main() -> std::io::Result<()> {
    ///     HttpServer::new(
    ///         async || App::new().service(web::resource("/").to(|| async { HttpResponse::Ok() }))
    ///     )
    ///         .bind("127.0.0.1:0")?
    ///         .run()
    ///         .await
    /// }
    /// ```
    pub fn run(self) -> Server {
        self.builder.run()
    }
```

--------------------------------

### Implement Configuration for HttpServiceConfig

Source: https://docs.rs/ntex/latest/ntex/service/cfg/trait.Configuration.html

Example implementation of the NAME constant for HttpServiceConfig.

```rust
const NAME: &str = "Http service configuration"
```

--------------------------------

### Implement Configuration for ServiceConfig

Source: https://docs.rs/ntex/latest/ntex/service/cfg/trait.Configuration.html

Example implementation of the NAME constant for ServiceConfig.

```rust
const NAME: &'static str = "Http/2 service configuration"
```

--------------------------------

### Implement Configuration for IoConfig

Source: https://docs.rs/ntex/latest/ntex/service/cfg/trait.Configuration.html

Example implementation of the NAME constant for IoConfig.

```rust
const NAME: &'static str = "IO Configuration"
```

--------------------------------

### Implement Middleware create method

Source: https://docs.rs/ntex/latest/ntex/service/trait.Middleware.html

Example implementation of the create method for a Timeout middleware.

```rust
    fn create(&self, service: S) -> Self::Service {
        Timeout {
            service,
            timeout: self.timeout,
        }
    }
}
```

--------------------------------

### Basic HTTP Client Usage

Source: https://docs.rs/ntex/latest/src/ntex/client/mod.rs.html

Demonstrates how to initialize an ntex client and perform a basic GET request.

```rust
use ntex::client::Client;

#[ntex::main]
async fn main() {
   let mut client = Client::new().await;

   let response = client.get("http://www.rust-lang.org") // <- Create request builder
       .header("User-Agent", "ntex::web")
       .send()                                           // <- Send http request
       .await;

    println!("Response: {:?}", response);
}
```

```rust
use ntex::client::Client;

#[ntex::main]
async fn main() {
    let mut client = Client::new().await;

    let res = client.get("http://www.rust-lang.org") // <- Create request builder
        .header("User-Agent", "ntex::web")
        .send()                             // <- Send http request
        .await;                             // <- send request and wait for response

     println!("Response: {:?}", res);
}
```

--------------------------------

### Basic HTTP Server Implementation

Source: https://docs.rs/ntex/latest/ntex/web/fn.server.html

A complete example demonstrating how to initialize and run an HTTP server using web::server.

```rust
use ntex::web;

#[ntex::main]
async fn main() -> std::io::Result<()> {
    web::server(
        async || web::App::new()
            .service(web::resource("/").to(|| async { web::HttpResponse::Ok() })))
        .bind("127.0.0.1:59090")?
        .run()
        .await
}
```

--------------------------------

### Parsing HTTP/1.0 GET Requests

Source: https://docs.rs/ntex/latest/src/ntex/http/h1/decoder.rs.html

Examples of parsing various GET request formats, including query parameters and error handling for unsupported features like chunked encoding.

```rust
    #[test]
    fn parse_h10_get() {
        let mut buf = BytesMut::from(
            "GET /test1 HTTP/1.0\r\n\
            \r\n\
            abc",
        );

        let reader = MessageDecoder::<Request>::default();
        let (req, _) = reader.decode(&mut buf).unwrap().unwrap();
        assert_eq!(req.version(), Version::HTTP_10);
        assert_eq!(*req.method(), Method::GET);
        assert_eq!(req.path(), "/test1");

        let mut buf = BytesMut::from(
            "GET /test2 HTTP/1.0\r\n\
            Test: 123\r\n\
            Content-Length: 0\r\n\
            \r\n",
        );

        let reader = MessageDecoder::<Request>::default();
        let (req, _) = reader.decode(&mut buf).unwrap().unwrap();
        assert_eq!(req.version(), Version::HTTP_10);
        assert_eq!(*req.method(), Method::GET);
        assert_eq!(req.path(), "/test2");

        let mut buf = BytesMut::from(
            "GET /test3?test=1 HTTP/1.0\r\n\
            Content-Length: 3\r\n\
            \r\n
            abc",
        );

        let reader = MessageDecoder::<Request>::default();
        let (req, _) = reader.decode(&mut buf).unwrap().unwrap();
        assert_eq!(req.version(), Version::HTTP_10);
        assert_eq!(*req.method(), Method::GET);
        assert_eq!(req.path(), "/test3");
        assert_eq!(req.uri().query(), Some("test=1"));

        // transfer-encoding is not supported for http1.0
        let mut buf = BytesMut::from(
            "GET /test3?test=1 HTTP/1.0\r\nTransfer-Encoding: chunked\r\n\r\n",
        );
        expect_parse_err!(&mut buf);
    }
```

--------------------------------

### Start a test server for integration testing

Source: https://docs.rs/ntex/latest/ntex/web/test/fn.server.html

Demonstrates initializing a test server with a basic App configuration and verifying a successful response.

```rust
use ntex::web::{self, test, App, HttpResponse};

async fn my_handler() -> Result<HttpResponse, std::io::Error> {
    Ok(HttpResponse::Ok().into())
}

#[ntex::test]
async fn test_example() {
    let mut srv = test::server(
        || App::new().service(
                web::resource("/").to(my_handler))
    );

    let req = srv.get("/");
    let response = req.send().await.unwrap();
    assert!(response.status().is_success());
}
```

--------------------------------

### #[get]

Source: https://docs.rs/ntex/latest/ntex/web/attr.get.html

The get attribute macro is used to define a route handler that responds to HTTP GET requests. It supports path definition, custom guards, and error renderers.

```APIDOC
## #[get]

### Description
Creates a route handler with a GET method guard.

### Syntax
#[get("path"[, attributes])]

### Attributes
- **path** (string) - Mandatory. Raw literal string with the path for which to register the handler.
- **guard** (string) - Optional. Registers a function as a guard using `ntex::web::guard::fn_guard`.
- **error** (string) - Optional. Registers a handler for a different error renderer.
```

--------------------------------

### Create a WebServiceAdapter

Source: https://docs.rs/ntex/latest/ntex/web/dev/struct.WebServiceAdapter.html

Demonstrates how to initialize a service adapter for a specific path with a header guard.

```rust
use ntex::web::{self, guard, App, HttpResponse, Error, DefaultError};

async fn my_service(req: web::WebRequest<DefaultError>) -> Result<web::WebResponse, Error> {
    Ok(req.into_response(HttpResponse::Ok().finish()))
}

let app = App::new().service(
    web::service("/users/*")
        .guard(guard::Header("content-type", "text/plain"))
        .finish(my_service)
);
```

--------------------------------

### get Attribute Macro Syntax

Source: https://docs.rs/ntex/latest/ntex/web/attr.get.html

Basic syntax for defining a route handler with the get attribute macro.

```rust
#[get]
```

--------------------------------

### HttpMessage Test Example

Source: https://docs.rs/ntex/latest/src/ntex/http/httpmessage.rs.html

Example usage of HttpMessage methods within a test environment using TestRequest.

```rust
#[test]
    fn test_content_type() {
        let req = TestRequest::with_header("content-type", "text/plain").finish();
        assert_eq!(req.content_type(), "text/plain");
        let req =
            TestRequest::with_header("content-type", "application/json; charset=utf=8")
```

--------------------------------

### Start a test server for integration testing

Source: https://docs.rs/ntex/latest/ntex/http/test/fn.server.html

Demonstrates initializing a TestServer with an HttpService and performing a request to verify the response status.

```rust
use ntex::http;
use ntex::web::{self, App, HttpResponse};

async fn my_handler() -> Result<HttpResponse, std::io::Error> {
    Ok(HttpResponse::Ok().into())
}

#[ntex::test]
async fn test_example() {
    let mut srv = http::test::server(
        || http::HttpService::new(
            App::new().service(
                web::resource("/").to(my_handler))
        )
    );

    let req = srv.get("/");
    let response = req.send().await.unwrap();
    assert!(response.status().is_success());
}
```

--------------------------------

### ntex::web::guard::Get

Source: https://docs.rs/ntex/latest/ntex/web/guard/fn.Get.html

The Get function is a guard used to restrict route matching to HTTP GET requests.

```APIDOC
## ntex::web::guard::Get

### Description
Guard to match the GET HTTP method. This function is used within route definitions to ensure the handler only processes GET requests.

### Signature
`pub fn Get() -> MethodGuard`
```

--------------------------------

### Define a GET route in ntex

Source: https://docs.rs/ntex/latest/ntex/web/fn.get.html

Use web::get() within a resource definition to handle GET requests for a specific path.

```rust
use ntex::web;

let app = web::App::new().service(
    web::resource("/{project_id}")
       .route(web::get().to(|| async { web::HttpResponse::Ok() }))
);
```

--------------------------------

### Create a ServiceFactory with configuration

Source: https://docs.rs/ntex/latest/ntex/service/fn.fn_factory_with_config.html

Demonstrates creating a service factory that uses a configuration argument to generate services, followed by service construction and invocation.

```rust
use std::io;
use ntex_service::{fn_factory_with_config, fn_service, Service, ServiceFactory};

#[ntex::main]
async fn main() -> io::Result<()> {
    // Create service factory. factory uses config argument for
    // services it generates.
    let factory = fn_factory_with_config(|y: &usize| {
        let y = *y;
        async move { Ok::<_, io::Error>(fn_service(move |x: usize| async move { Ok::<_, io::Error>(x * y) })) }
    });

    // construct new service with config argument
    let srv = factory.pipeline(&10).await?;

    let result = srv.call(10).await?;
    assert_eq!(result, 100);

    println!("10 * 10 = {}", result);
    Ok(())
}
```

--------------------------------

### get()

Source: https://docs.rs/ntex/latest/ntex/io/cfg/struct.BufConfig.html

Retrieves a buffer from the configuration.

```APIDOC
### pub fn get(&self) -> BytesMut

Retrieves a buffer managed by this configuration.
```

--------------------------------

### build_test_server<F>(factory: F) -> TestServer

Source: https://docs.rs/ntex/latest/ntex/server/fn.build_test_server.html

Starts a new server with a server builder. The factory argument is an AsyncFnOnce that takes a ServerBuilder and returns a ServerBuilder.

```APIDOC
## build_test_server

### Description
Starts a new server with a server builder.

### Signature
`pub fn build_test_server<F>(factory: F) -> TestServer`

### Parameters
- **factory** (F) - Required - An `AsyncFnOnce(ServerBuilder) -> ServerBuilder + Send + 'static` closure used to configure the server.

### Returns
- **TestServer** - Returns a `TestServer` instance.
```

--------------------------------

### get

Source: https://docs.rs/ntex/latest/ntex/util/type.HashSet.html

Retrieves a reference to a value in the set.

```APIDOC
## pub fn get<Q>(&self, value: &Q) -> Option<&T>

### Description
Returns a reference to the value in the set, if any, that is equal to the given value.
```

--------------------------------

### init_service<R, S, E>(app: R)

Source: https://docs.rs/ntex/latest/ntex/web/test/fn.init_service.html

Initializes an application builder instance and constructs a service for testing.

```APIDOC
## init_service

### Description
This function accepts an application builder instance and constructs a service, which can then be used to execute requests in a test environment.

### Signature
`pub async fn init_service<R, S, E>(app: R) -> Pipeline<impl Service<Request, Response = WebResponse, Error = E>>`

### Parameters
- **app** (R) - Required - An application builder instance that implements `IntoServiceFactory`.

### Example
```rust
use ntex::service::Service;
use ntex::http::StatusCode;
use ntex::web::{self, test, App, HttpResponse};

#[ntex::test]
async fn test_init_service() {
    let mut app = test::init_service(
        App::new()
            .service(web::resource("/test").to(|| async { HttpResponse::Ok() }))
    ).await;

    let req = test::TestRequest::with_uri("/test").to_request();
    let resp = app.call(req).await.unwrap();
    assert_eq!(resp.status(), StatusCode::OK);
}
```
```

--------------------------------

### get

Source: https://docs.rs/ntex/latest/ntex/util/type.HashMap.html

Returns a reference to the value corresponding to the key.

```APIDOC
## pub fn get<Q>(&self, k: &Q) -> Option<&V>

### Description
Returns a reference to the value corresponding to the key. The key may be any borrowed form of the map’s key type, but Hash and Eq on the borrowed form must match those for the key type.
```

--------------------------------

### Get slice length

Source: https://docs.rs/ntex/latest/ntex/util/struct.Bytes.html

Returns the number of elements in the slice.

```rust
let a = [1, 2, 3];
assert_eq!(a.len(), 3);
```

--------------------------------

### Get host from Authority

Source: https://docs.rs/ntex/latest/ntex/http/uri/struct.Authority.html

Extract the host subcomponent, which is case-insensitive.

```rust
let authority: Authority = "example.org:80".parse().unwrap();

assert_eq!(authority.host(), "example.org");
```

--------------------------------

### build

Source: https://docs.rs/ntex/latest/src/ntex/client/builder.rs.html

Finalizes the configuration and constructs the Client instance.

```APIDOC
## async fn build<T>(mut self, cfg: T) -> Result<Client, ClientBuilderError>

### Description
Completes the build process and returns a configured `Client` instance. This method is asynchronous and requires a configuration object.

### Parameters
- **cfg** (T) - Required - The configuration object that implements `Into<SharedCfg>`.
```

--------------------------------

### HttpServer::run

Source: https://docs.rs/ntex/latest/ntex/web/struct.HttpServer.html

Starts the HTTP server, initializing worker threads and beginning the accept loop for incoming connections.

```APIDOC
## fn run(self) -> Server

### Description
Starts listening for incoming connections. This method spawns a number of HTTP workers in separate threads and initiates an accept loop for each bound address.

### Notes
- This method will panic if no socket address can be bound.
- This method will panic if an ntex system is not yet configured.

### Example
```rust
use ntex::web::{self, App, HttpResponse, HttpServer};

#[ntex::main]
async fn main() -> std::io::Result<()> {
    HttpServer::new(
        async || App::new().service(web::resource("/").to(|| async { HttpResponse::Ok() }))
    )
        .bind("127.0.0.1:0")?
        .run()
        .await
}
```
```

--------------------------------

### Initialize Test Server Client

Source: https://docs.rs/ntex/latest/src/ntex/web/test.rs.html

Configures the client connector with optional TLS settings and builds the client instance.

```rust
let client = {
        let connector = {
            #[cfg(feature = "openssl")]
            {
                use tls_openssl::ssl::{SslConnector, SslMethod, SslVerifyMode};

                let mut builder = SslConnector::builder(SslMethod::tls()).unwrap();
                builder.set_verify(SslVerifyMode::NONE);
                let _ = builder
                    .set_alpn_protos(b"\x02h2\x08http/1.1")
                    .map_err(|e| log::error!("Cannot set alpn protocol: {e:?}"));
                Connector::default()
                    .lifetime(Seconds::ZERO)
                    .openssl(builder.build())
            }
            #[cfg(not(feature = "openssl"))]
            {
                Connector::default().lifetime(Seconds::ZERO)
            }
        };

        Client::builder()
            .connector::<&str>(connector)
            .build(cfg.clone())
            .await
            .unwrap()
    };
```

--------------------------------

### Get length of Bytes

Source: https://docs.rs/ntex/latest/ntex/util/struct.Bytes.html

Returns the number of bytes contained in the buffer.

```rust
use ntex_bytes::Bytes;

let b = Bytes::from(&b"hello"[..]);
assert_eq!(b.len(), 5);
```

--------------------------------

### get_disjoint_mut

Source: https://docs.rs/ntex/latest/ntex/util/type.HashMap.html

Attempts to get mutable references to multiple values in the map at once.

```APIDOC
## pub fn get_disjoint_mut<Q, const N: usize>( &mut self, ks: [&Q; N], ) -> [Option<&mut V>; N]

### Description
Attempts to get mutable references to N values in the map at once. Returns an array of length N with the results of each query. Panics if any keys are overlapping.
```

--------------------------------

### server_with

Source: https://docs.rs/ntex/latest/ntex/web/test/fn.server_with.html

Starts a test server with a custom configuration and a service factory. This is used for testing web applications by providing a controlled environment.

```APIDOC
## server_with

### Description
Starts a test server with custom configuration. The server is initialized using a provided factory that returns a service factory.

### Signature
`pub async fn server_with<F, I, S, B>(cfg: TestServerConfig, factory: F) -> TestServer`

### Parameters
- **cfg** (TestServerConfig) - Required - The configuration for the test server, such as protocol (h1/h2) or port settings.
- **factory** (F) - Required - A closure or function that returns an object implementing `IntoServiceFactory`.

### Example
```rust
use ntex::web::{self, test, App, HttpResponse};

async fn my_handler() -> HttpResponse {
    HttpResponse::Ok().into()
}

#[ntex::test]
async fn test_example() {
    let mut srv = test::server_with(test::config().h1().port(4000), ||
        App::new().service(web::resource("/").to(my_handler))
    );

    let req = srv.get("/");
    let response = req.send().await.unwrap();
    assert!(response.status().is_success());
}
```
```

--------------------------------

### as_mut

Source: https://docs.rs/ntex/latest/ntex/rt/type.BlockFuture.html

Gets a mutable reference to the pinned value this Pin points to.

```APIDOC
## pub fn as_mut(&mut self) -> Pin<&mut <Ptr as Deref>::Target>

### Description
Gets a mutable reference to the pinned value this `Pin<Ptr>` points to. This is useful when performing multiple calls to functions that consume the pinning pointer.
```

--------------------------------

### as_ref

Source: https://docs.rs/ntex/latest/ntex/rt/type.BlockFuture.html

Gets a shared reference to the pinned value this Pin points to.

```APIDOC
## pub fn as_ref(&self) -> Pin<&<Ptr as Deref>::Target>

### Description
Gets a shared reference to the pinned value this `Pin` points to. This is a safe way to convert `&Pin<Pointer<T>>` to `Pin<&T>`.
```

--------------------------------

### Configure Basic Authentication

Source: https://docs.rs/ntex/latest/src/ntex/ws/client.rs.html

Shows how to set basic authentication credentials during client construction and update them on an existing client instance.

```rust
    #[crate::rt_test]
    async fn basic_auth() {
        let client = WsClient::builder("http://localhost")
            .basic_auth("username", Some("password"))
            .build(SharedCfg::default())
            .await
            .unwrap();
        assert_eq!(
            client
                .head
                .headers
                .get(header::AUTHORIZATION)
                .unwrap()
                .to_str()
                .unwrap(),
            "Basic dXNlcm5hbWU6cGFzc3dvcmQ="
        );

        let client = WsClient::builder("http://localhost")
            .basic_auth("username", None)
            .build(SharedCfg::default())
            .await
            .unwrap();
        assert_eq!(
            client
                .head
                .headers
                .get(header::AUTHORIZATION)
                .unwrap()
                .to_str()
                .unwrap(),
            "Basic dXNlcm5hbWU6"
        );

        client.set_basic_auth("username", Some("password")).unwrap();
        assert_eq!(
            client
                .extra_headers
                .borrow()
                .as_ref()
                .unwrap()
                .get(header::AUTHORIZATION)
                .unwrap()
                .to_str()
                .unwrap(),
            "Basic dXNlcm5hbWU6cGFzc3dvcmQ="
        );
    }
```

--------------------------------

### ClientRequest Usage

Source: https://docs.rs/ntex/latest/ntex/client/struct.ClientRequest.html

Demonstrates how to initiate a request using the Client builder, configure headers, and send the request.

```APIDOC
## ClientRequest Usage

### Description
This example shows how to use the `Client` to create a `ClientRequest` builder, add custom headers, and send the request to a server.

### Code Example
```rust
use ntex::client::Client;

#[ntex::main]
async fn main() {
   let response = Client::new()
        .await
        .get("http://www.rust-lang.org") // <- Create request builder
        .header("User-Agent", "ntex::web")
        .send()                          // <- Send http request
        .await;

   response.and_then(|response| {   // <- server http response
        println!("Response: {:?}", response);
        Ok(())
   });
}
```
```

--------------------------------

### listen_uds

Source: https://docs.rs/ntex/latest/src/ntex/web/server.rs.html

Starts listening for Unix domain connections on an existing listener.

```APIDOC
## listen_uds

### Description
Starts listening for Unix domain connections on an existing listener. Available with the `uds` feature.

### Parameters
- **lst** (UnixListener) - Required - The existing Unix domain listener.
```

--------------------------------

### Trim start matches by pattern

Source: https://docs.rs/ntex/latest/ntex/util/struct.ByteString.html

Removes prefixes matching a pattern.

```rust
assert_eq!("11foo1bar11".trim_start_matches('1'), "foo1bar11");
assert_eq!("123foo1bar123".trim_start_matches(char::is_numeric), "foo1bar123");
```

--------------------------------

### Initialize WsClient with Builder

Source: https://docs.rs/ntex/latest/src/ntex/ws/client.rs.html

Demonstrates building a WebSocket client instance. Note that the client overrides the request method to GET during the handshake process.

```rust
let mut head = Message::<RequestHead>::new();
head.method = Method::POST;
drop(head);

let client = WsClient::builder("http://localhost")
    .build(SharedCfg::default())
    .await
    .unwrap();
assert_eq!(client.head.method, Method::GET);
```

--------------------------------

### Trim start whitespace

Source: https://docs.rs/ntex/latest/ntex/util/struct.ByteString.html

Removes leading whitespace from a string slice.

```rust
let s = "  עברית  ";
assert!(Some('ע') == s.trim_start().chars().next());
```

--------------------------------

### Create New WsClientBuilder

Source: https://docs.rs/ntex/latest/src/ntex/ws/client.rs.html

Initializes a new builder instance with default settings, including a GET method and a 64kb frame size limit.

```rust
impl WsClientBuilder<Base, ()> {
    #[must_use]
    /// Create new client builder.
    fn new<U>(uri: U) -> WsClientBuilder<Base, Connector<Uri>>
    where
        Uri: TryFrom<U>,
        <Uri as TryFrom<U>>::Error: Into<HttpError>,
    {
        let mut head = Message::<RequestHead>::new();
        // the message pool may return a recycled head whose method is not GET
        // (e.g. previously used by the HTTP/1 server dispatcher for a POST request)
        head.method = Method::GET;
        let err = match Uri::try_from(uri) {
            Ok(uri) => {
                head.uri = uri;
                None
            }
            Err(e) => Some(e.into()),
        };

        WsClientBuilder {
            err,
            origin: None,
            protocols: None,
            inner: Some(Inner {
                head,
                addr: None,
                max_size: 65_536,
                server_mode: false,
                timeout: Millis(5_000),
                connector: Connector::<Uri>::default(),
                _t: marker::PhantomData,
            }),
            #[cfg(feature = "cookie")]
            cookies: None,
        }
    }
}
```

--------------------------------

### Configure application with App::configure

Source: https://docs.rs/ntex/latest/ntex/web/struct.App.html

Shows how to modularize application configuration by passing a closure to the configure method.

```rust
use ntex::web::{self, middleware, App, HttpResponse};

// this function could be located in different module
fn config(cfg: &mut web::ServiceConfig) {
    cfg.service(web::resource("/test")
        .route(web::get().to(|| async { HttpResponse::Ok() }))
        .route(web::head().to(|| async { HttpResponse::MethodNotAllowed() }))
    );
}

fn main() {
    let app = App::new()
        .middleware(middleware::Logger::default())
        .configure(config)  // <- register resources
        .route("/index.html", web::get().to(|| async { HttpResponse::Ok() }));
}
```

--------------------------------

### Splitting off the last element

Source: https://docs.rs/ntex/latest/ntex/util/struct.BytesMut.html

Examples of removing the last element from a slice.

```rust
let mut slice: &[_] = &['a', 'b', 'c'];
let last = slice.split_off_last().unwrap();

assert_eq!(slice, &['a', 'b']);
assert_eq!(last, &'c');
```

```rust
let mut slice: &mut [_] = &mut ['a', 'b', 'c'];
let last = slice.split_off_last_mut().unwrap();
*last = 'd';
```

--------------------------------

### pub fn build() -> ServerBuilder

Source: https://docs.rs/ntex/latest/ntex/server/fn.build.html

Initializes the server building process. This function is the entry point for configuring and starting an ntex server.

```APIDOC
## fn build

### Description
Starts the server building process. Returns a `ServerBuilder` instance which can be used to configure server settings before starting the server.

### Signature
`pub fn build() -> ServerBuilder`
```

--------------------------------

### Splitting off the first element

Source: https://docs.rs/ntex/latest/ntex/util/struct.BytesMut.html

Examples of removing the first element from a slice.

```rust
let mut slice: &[_] = &['a', 'b', 'c'];
let first = slice.split_off_first().unwrap();

assert_eq!(slice, &['b', 'c']);
assert_eq!(first, &'a');
```

```rust
let mut slice: &mut [_] = &mut ['a', 'b', 'c'];
let first = slice.split_off_first_mut().unwrap();
*first = 'd';

assert_eq!(slice, &['b', 'c']);
assert_eq!(first, &'d');
```

--------------------------------

### Initialize and Run HttpServer

Source: https://docs.rs/ntex/latest/ntex/web/struct.HttpServer.html

Basic usage of HttpServer to bind to a local address and start the server using an application factory.

```rust
use ntex::web::{self, App, HttpResponse, HttpServer};

#[ntex::main]
async fn main() -> std::io::Result<()> {
    HttpServer::new(
        async || App::new()
            .service(web::resource("/").to(|| async { HttpResponse::Ok() })))
        .bind("127.0.0.1:59090")?
        .run()
        .await
}
```

--------------------------------

### Strip circumfix example

Source: https://docs.rs/ntex/latest/ntex/util/struct.ByteString.html

Removes both a prefix and a suffix exactly once if they do not overlap.

```rust
assert_eq!("bar:hello:foo".strip_circumfix("bar:", ":foo"), Some("hello"));
assert_eq!("bar:foo".strip_circumfix("foo", "foo"), None);
assert_eq!("foo:bar;".strip_circumfix("foo:", ';'), Some("bar"));
assert_eq!("foo:bar:baz".strip_circumfix("foo:bar:", ":bar:baz"), None);
```

--------------------------------

### Runtime::new

Source: https://docs.rs/ntex/latest/ntex/rt/rt_default/struct.Runtime.html

Creates a new instance of the Runtime with default configuration.

```APIDOC
## pub fn new(handle: Box<dyn Notify>) -> Runtime

### Description
Creates a new `Runtime` instance with default configuration using the provided notification handler.

### Parameters
- **handle** (Box<dyn Notify>) - Required - The notification handler for the runtime.
```

--------------------------------

### Implement Configuration for TlsConfig

Source: https://docs.rs/ntex/latest/ntex/service/cfg/trait.Configuration.html

Example implementation of the NAME constant for TlsConfig.

```rust
const NAME: &'static str = "TLS Configuration"
```

--------------------------------

### Initialize and test an ntex server

Source: https://docs.rs/ntex/latest/ntex/server/fn.test_server.html

Demonstrates how to use test_server to spin up a local server instance and perform an HTTP request for integration testing.

```rust
use ntex::{server, http, client::Client};
use ntex::web::{self, App, HttpResponse};

async fn my_handler() -> Result<HttpResponse, std::io::Error> {
    Ok(HttpResponse::Ok().into())
}

#[ntex::test]
async fn test_example() {
    let mut srv = server::test_server(
        async || http::HttpService::new(
            App::new().service(
                web::resource("/").to(my_handler))
        )
    );

    let req = Client::new().get("http://127.0.0.1:{}", srv.addr().port());
    let response = req.send().await.unwrap();
    assert!(response.status().is_success());
}
```

--------------------------------

### ntex::web::test::server_with

Source: https://docs.rs/ntex/latest/src/ntex/web/test.rs.html

Starts a test server with the provided configuration and service factory. This is typically used within test suites to verify application behavior.

```APIDOC
## Function: server_with

### Description
Starts a test server instance using a provided `TestServerConfig` and a service factory. The server runs in a separate thread and is suitable for integration testing of web services.

### Signature
`pub async fn server_with<F, I, S, B>(cfg: TestServerConfig, factory: F) -> TestServer`

### Parameters
- **cfg** (TestServerConfig) - The configuration for the test server, including port, stream type, and timeouts.
- **factory** (F) - A factory function that returns an `IntoServiceFactory` for the web application.

### Usage Example
```rust
use ntex::web::{self, test, App, HttpResponse};

async fn my_handler() -> HttpResponse {
    HttpResponse::Ok().into()
}

#[ntex::test]
async fn test_example() {
    let mut srv = test::server_with(test::config().h1().port(4000), ||
        App::new().service(web::resource("/").to(my_handler))
    );

    let req = srv.get("/");
    let response = req.send().await.unwrap();
    assert!(response.status().is_success());
}
```
```

--------------------------------

### Testing HTTP Methods

Source: https://docs.rs/ntex/latest/src/ntex/web/test.rs.html

Shows how to initialize a service and test PUT, PATCH, and DELETE request handlers.

```rust
    #[crate::rt_test]
    async fn test_request_methods() {
        let app = init_service(
            App::new().service(
                web::resource("/index.html")
                    .route(web::put().to(|| async { HttpResponse::Ok().body("put!") }))
                    .route(web::patch().to(|| async { HttpResponse::Ok().body("patch!") }))
                    .route(
                        web::delete().to(|| async { HttpResponse::Ok().body("delete!") }),
                    ),
            ),
        )
        .await;

        let put_req = TestRequest::put()
            .uri("/index.html")
            .header(header::CONTENT_TYPE, "application/json")
            .to_request();

        let result = read_response(&app, put_req).await;
        assert_eq!(result, Bytes::from_static(b"put!"));

        let patch_req = TestRequest::patch()
            .uri("/index.html")
            .header(header::CONTENT_TYPE, "application/json")
            .to_request();

        let result = read_response(&app, patch_req).await;
        assert_eq!(result, Bytes::from_static(b"patch!"));

        let delete_req = TestRequest::delete().uri("/index.html").to_request();
        let result = read_response(&app, delete_req).await;
        assert_eq!(result, Bytes::from_static(b"delete!"));
    }
```

--------------------------------

### Get Mutable Reference

Source: https://docs.rs/ntex/latest/ntex/util/type.HashMap.html

Retrieves a mutable reference to a value associated with a key.

```rust
use std::collections::HashMap;

let mut map = HashMap::new();
map.insert(1, "a");
if let Some(x) = map.get_mut(&1) {
    *x = "b";
}
assert_eq!(map[&1], "b");
```

--------------------------------

### as_deref_mut

Source: https://docs.rs/ntex/latest/ntex/rt/type.BlockFuture.html

Gets Pin<&mut T> to the underlying pinned value from a nested Pin-pointer.

```APIDOC
## pub fn as_deref_mut(self: Pin<&mut Pin<Ptr>>) -> Pin<&mut <Ptr as Deref>::Target>

### Description
Gets `Pin<&mut T>` to the underlying pinned value from this nested `Pin`-pointer. This is a generic method to go from `Pin<&mut Pin<Pointer<T>>>` to `Pin<&mut T>`.
```

--------------------------------

### Get port from Authority

Source: https://docs.rs/ntex/latest/ntex/http/uri/struct.Authority.html

Retrieve the port subcomponent as a Port object or u16.

```rust
let authority: Authority = "example.org:80".parse().unwrap();

let port = authority.port().unwrap();
assert_eq!(port.as_u16(), 80);
assert_eq!(port.as_str(), "80");
```

```rust
let authority: Authority = "example.org".parse().unwrap();

assert!(authority.port().is_none());
```

```rust
let authority: Authority = "example.org:80".parse().unwrap();

assert_eq!(authority.port_u16(), Some(80));
```

--------------------------------

### bind_uds

Source: https://docs.rs/ntex/latest/src/ntex/web/server.rs.html

Starts listening for incoming Unix domain connections on a specified path.

```APIDOC
## bind_uds

### Description
Starts listening for incoming Unix domain connections. Available with the `uds` feature.

### Parameters
- **addr** (Path) - Required - The filesystem path to bind the Unix domain socket.
```

--------------------------------

### Construct and send an HTTP request

Source: https://docs.rs/ntex/latest/ntex/client/struct.ClientRequest.html

Demonstrates using the Client builder to create a request, add headers, and send it asynchronously.

```rust
use ntex::client::Client;

#[ntex::main]
async fn main() {
   let response = Client::new()
        .await
        .get("http://www.rust-lang.org") // <- Create request builder
        .header("User-Agent", "ntex::web")
        .send()                          // <- Send http request
        .await;

   response.and_then(|response| {   // <- server http response
        println!("Response: {:?}", response);
        Ok(())
   });
}
```

--------------------------------

### RuntimeBuilder::new

Source: https://docs.rs/ntex/latest/ntex/rt/struct.RuntimeBuilder.html

Creates a new instance of the RuntimeBuilder with default configuration.

```APIDOC
## pub fn new() -> RuntimeBuilder

### Description
Creates the builder with default configuration.

### Returns
- **RuntimeBuilder** - A new instance of the builder.
```

--------------------------------

### Trim ASCII Start

Source: https://docs.rs/ntex/latest/ntex/util/struct.ByteString.html

Removes leading ASCII whitespace from a string slice.

```rust
assert_eq!(" \t \u{3000}hello world\n".trim_ascii_start(), "\u{3000}hello world\n");
assert_eq!("  ".trim_ascii_start(), "");
assert_eq!("".trim_ascii_start(), "");
```

--------------------------------

### Retrieve match indices

Source: https://docs.rs/ntex/latest/ntex/util/struct.ByteString.html

Returns an iterator over disjoint matches and their starting indices.

```rust
let v: Vec<_> = "abcXXXabcYYYabc".match_indices("abc").collect();
assert_eq!(v, [(0, "abc"), (6, "abc"), (12, "abc")]);

let v: Vec<_> = "1abcabc2".match_indices("abc").collect();
assert_eq!(v, [(1, "abc"), (4, "abc")]);

let v: Vec<_> = "ababa".match_indices("aba").collect();
assert_eq!(v, [(0, "aba")]); // only the first `aba`
```

--------------------------------

### App::new

Source: https://docs.rs/ntex/latest/ntex/web/struct.App.html

Creates a new instance of the application builder.

```APIDOC
## pub fn new() -> Self

### Description
Create application builder. Application can be configured with a builder-like pattern.
```
Tokens:
Raw