Crate kanagawa

Kanagawa is a minimal and pragmatic Rust web application framework built for rapid development. It comes with a robust set of features that make building async web applications and APIs easier and more fun.

Getting started

In order to build a web app in Rust you need an HTTP server, and an async runtime. After running cargo init add the following lines to your Cargo.toml file:

# Example, use the version numbers you need
kanagawa = "0.17.0"

Examples

Create an HTTP server that receives a JSON body, validates it, and responds with a confirmation message.

use kanagawa::Request;
use kanagawa::prelude::*;

#[derive(Debug, Deserialize)]
struct Animal {
    name: String,
    legs: u16,
}

#[nuclei::main]
async fn main() -> kanagawa::Result<()> {
    let mut app = kanagawa::new();
    app.at("/orders/shoes").post(order_shoes);
    app.listen("127.0.0.1:8080").await?;
    Ok(())
}

async fn order_shoes(mut req: Request<()>) -> kanagawa::Result {
    let Animal { name, legs } = req.body_json().await?;
    Ok(format!("Hello, {}! I've put in an order for {} shoes", name, legs).into())
}

$ curl localhost:8080/orders/shoes -d '{ "name": "Chashu", "legs": 4 }'
Hello, Chashu! I've put in an order for 4 shoes

$ curl localhost:8080/orders/shoes -d '{ "name": "Mary Millipede", "legs": 750 }'
Hello, Mary Millipede! I've put in an order for 750 shoes

See more examples in the examples directory.

Re-exports

• pub use http_types as http;
• pub use crate::errors::*;

Modules

• config
  Nuclei’s configuration options reside here.
• convert
  Traits for conversions between types.
• errors
• log
  Support for logging in kanagawa; see LogMiddleware.
• prelude
  The Kanagawa prelude.
• security
  HTTP Security Headers.
• utils
  Miscellaneous utilities.

Structs

• Body
  A streaming HTTP body.
• Error
  The error type for HTTP operations.
• GlobalExecutorConfig
  Configuration to init the thread pool for the multi-threaded global executor.
• Handle
  Handle that manages IO submitted to proactor system.
• Next
  The remainder of a middleware chain, including the endpoint.
• Proactor
  Concrete proactor instance
• Redirect
  A redirection endpoint.
• Request
  An HTTP request.
• Response
  An HTTP response
• ResponseBuilder
  Response Builder
• Route
  A handle to a route.
• Server
  An HTTP server.
• Task
  A spawned task.

Enums

• Method
  HTTP request methods.
• StatusCode
  HTTP response status codes.

Traits

• Endpoint
  An HTTP request handler.
• HandleOpRegisterer
  Operation registrar for Proactive IO, represents the outer ring that will send & receive submissions and completions respectively.
• Middleware
  Middleware that wraps around the remaining middleware chain.
• Status
  Provides the status method for Result and Option.

Functions

• block_on
  Runs the global and the local executor on the current thread
• drive
  IO driver that drives underlying event systems
• init
  Init the global executor, spawning as many threads as the number or cpus or the value specified by the ASYNC_GLOBAL_EXECUTOR_THREADS environment variable if specified.
• init_with_config
  Init the global executor, spawning as many threads as specified or the value specified by the specified environment variable.
• new
  Create a new Kanagawa server.
• spawn
  Spawns a task onto the multi-threaded global executor.
• spawn_blocking
  Runs blocking code on a thread pool.
• spawn_local
  Spawns a task onto the local executor.
• spawn_more_threads
  Spawn more executor threads, up to configured max value.
• stop_current_thread
  Stop the current executor thread, if we exceed the configured min value
• stop_thread
  Stop one of the executor threads, down to configured min value
• with_state
  Create a new Kanagawa server with shared application scoped state.

Type Aliases

• AsyncOp
  Submitted async IO operation type
• Result
  A specialized Result type for Kanagawa.

Attribute Macros

• bench
  Enables an async benchmark function.
• main
  Enables an async main function.
• test
  Enables an async test function.