The Hotaru 0.8 era starts from 23/May/2026.

Hotaru Web Framework

Overview

Small, sweet, easy framework with a protocol-neutral, no_std-ready core

Official Website | Example Project

Repository transfer notice: the Hotaru repository has moved to https://github.com/Field-of-Dream-Studio/hotaru.

MSRV: 1.88

Stability in 0.8.x

The tokio + HTTP stack (default features trans, http, tokio) is the tested, supported path and is safe for production use today.

Everything else is experimental and will stabilize by 0.8.7:

• RuntimeSpec trait surface (hotaru_rt_tokio is the supported default; hotaru_rt_embassy is experimental)
• no_std builds of hotaru_core (Cortex-M / RISC-V bare-metal, CI-verified and connected to experimental embedded backend crates, but not yet production-validated on hardware)
• IO adapter crates: hotaru_io_futures ships as a standalone crate (limited real-world use). hotaru_io_embedded lives in the workspace and is still experimental and unpublished (crates.io). The hotaru facade exposes EmbeddedIo through its optional io_embedded feature.
• Embassy runtime backend (hotaru_rt_embassy, experimental)

If you are shipping something now, stick with the tokio default and revisit the experimental paths as they land.

Key Features

• Multi-Protocol: HTTP/1.1 and HTTPS (TLS) ship out of the box. The Protocol trait is an open extension point for custom TCP-based protocols (WebSocket, MQTT, and other frames), though no non-HTTP protocol ships in this workspace today
• Server + Client: Endpoints for inbound traffic, outpoints for outbound. Same protocol trait, same routing, same middleware
• Runtime-Neutral Core: hotaru_core speaks to any async runtime through the RuntimeSpec trait. Tokio ships today via hotaru_rt_tokio; other runtimes can plug in via the same sibling-crate pattern. IO adapters are further along, with hotaru_io_tokio, hotaru_io_futures, and the experimental in-workspace hotaru_io_embedded
• no_std-Ready Core: hotaru_core builds bare-metal on Cortex-M4/M7 and RISC-V (with atomics) under alloc. CI verified on thumbv7em-none-eabihf and riscv32imac-unknown-none-elf
• Sync main: fn main() { run_server!(APP); }. No async fn main, no #[tokio::main]
• Ergonomic Macros: endpoint! / outpoint! / middleware! DSL in three flavors (trans, semi-trans, attr)
• Full-Stack: Akari template rendering, form/URL-encoded body parsing, session cookies, HTTP body compression (gzip / deflate / brotli / zstd) all built in
• Flexible Routing: Regex, literal, and pattern segments (<int:id>, <uuid:token>, <**path>) with a tree walker

Quick Start

use hotaru::prelude::*;
use hotaru::http::*;

LServer!(
    APP = Server::new()
        .binding("127.0.0.1:3003")
        .single_protocol(ProtocolBuilder::new(HTTP::server(HttpSafety::default())))
        .build()
);

fn main() {
    run_server!(APP);
}

endpoint! {
    APP.url("/"),
    pub index<HTTP> {
        text_response("Hello, Hotaru!")
    }
}

run_server!(APP) builds a tokio runtime, blocks the current thread, and shuts down on Ctrl+C. No async fn main, no #[tokio::main]. See Core Concepts for the sibling macros (run_server_until!, run_server_no_block!, run_server_no_block_until!) when you need a custom stop source or multi-server orchestration.

Installation

Using the CLI Tool (Recommended)

Install the Hotaru CLI tool:

cargo install hotaru

Create a new project:

hotaru new my_app
cd my_app
cargo run

Manual Installation

Add to your Cargo.toml:

[dependencies]
hotaru = "0.8.3"
tokio = { version = "1", features = ["full"] }

Optional Features

Default features: trans, http, tokio. Cargo's additive feature unification means sub-features pull in their prerequisites automatically — you never have to enable a base feature by hand.

Protocol stack

• http (default-on): HTTP/1.1 stack (hotaru_http + ahttpm). Opt out with default-features = false for protocol-only builds (e.g. gRPC-only deployments) — hotaru::http::*, HTTP, HttpContext, HttpRequest, HttpResponse, etc. then disappear from the crate surface.
• tokio (default-on): Tokio runtime + TCP/IO defaults for the umbrella crate (Server, Client, Url, S* aliases, TcpTransport, TokioRuntime). If you disable default features but still use those defaults, re-enable tokio.
• https: TLS/HTTPS support — surfaces HTTPS, TlsTransport, TlsOutboundTarget, TlsClientConfig. Implies http.
• http_compression: HTTP body codecs for Content-Encoding (gzip / deflate / brotli / zstd). Off by default because brotli + zstd together add ~7 s to a clean build. Implies http. Without this feature, ContentCoding::decode_compressed / encode_compressed return io::ErrorKind::Unsupported for compressed bodies.

Endpoint macro flavor — pick one (see Core Concepts):

• trans (default) — bang macro with hotaru-blocks body
• semi-trans — stacked attributes above an fn
• attr — single attribute with args

Misc

• debug: Enable debug logging for development and troubleshooting.
• external-ctor: Use the external ctor crate instead of Hotaru's built-in constructor implementation. When enabling, you must also add ctor to your dependencies:

  [dependencies]
  hotaru = { version = "0.8.3", features = ["external-ctor"] }
  ctor = "0.4.0"
  tokio = { version = "1", features = ["full"] }

Example — HTTPS server with body compression:

[dependencies]
hotaru = { version = "0.8.3", features = ["https", "http_compression"] }
tokio = { version = "1", features = ["full"] }

Example — gRPC-only (no HTTP):

[dependencies]
hotaru = { version = "0.8.3", default-features = false, features = ["trans", "tokio"] }
hotaru_grpc = "..."
tokio = { version = "1", features = ["full"] }

Binary Commands

Use the CLI to scaffold projects — it generates build.rs for asset copying and src/resource.rs for runtime template/static lookup, which are non-trivial to wire up by hand.

cargo install hotaru                   # install the CLI (see Installation above)
hotaru new my_app                      # scaffold a new project
hotaru init                            # or scaffold into the current Cargo crate
cd my_app && cargo run                 # serves http://127.0.0.1:3003

Project Structure

my_app/
├── Cargo.toml              # Dependencies and project metadata
├── build.rs                # Asset copying build script
├── src/
│   ├── main.rs            # Application entry point with LServer! + endpoint!
│   └── resource.rs        # Resource locator helpers
├── templates/             # Akari HTML templates
└── programfiles/          # Static assets (CSS, JS, images)

The build script copies templates/ and programfiles/ to the target directory at compile time so they're accessible at runtime.

Core Concepts

Endpoints

Three macro flavors, enabled by the trans / semi-trans / attr cargo features. Pick one per project; trans is the default. All three register the same route at startup; they only differ in syntax.

trans (default) — bang macro with hotaru-blocks body:

endpoint! {
    APP.url("/users/<int:id>"),
    pub get_user<HTTP> {
        let user_id = req.param("id").unwrap_or_default();
        akari_json!({ id: user_id })
    }
}

semi-trans — stacked attributes above an fn:

#[endpoint]
#[url("/users/<int:id>")]
pub fn get_user<HTTP>() {
    let user_id = req.param("id").unwrap_or_default();
    akari_json!({ id: user_id })
}

attr — single attribute with args:

#[endpoint("/users/<int:id>")]
pub fn get_user<HTTP>() {
    let user_id = req.param("id").unwrap_or_default();
    akari_json!({ id: user_id })
}

akari_json! is the JSON-response macro re-exported via hotaru::prelude; it already wraps json_response(...) so callers don't compose the two. Keys are bare idents (not "..."). req.param(...) returns Option<String>.

Macro Notes

• Endpoints and middleware auto-register at startup — no manual router.register().
• trans form: brace syntax {} with doc comments inside the block; angle-bracket body defaults to req. Optional fn-style pub fn name(req: HTTP) { ... } is also accepted.
• Remaining readme examples use trans. To switch, set default-features = false on the hotaru dependency and turn on the flavor you want, e.g. hotaru = { version = "0.8.3", default-features = false, features = ["semi-trans", "http", "tokio"] }. Cargo feature unification would otherwise keep trans on alongside it; remember to re-add http and tokio since default-features = false also drops the default HTTP stack and Tokio facade defaults.
• See macro_ra.md for syntax details. Analyzer support is planned.

Middleware

Attach a middleware to a protocol via the ProtocolBuilder. Add htmstd = "0.8" to your Cargo.toml for the bundled middleware library:

use htmstd::CookieSession;

LServer!(
    APP = Server::new()
        .binding("127.0.0.1:3003")
        .single_protocol(
            ProtocolBuilder::new(HTTP::server(HttpSafety::default()))
                .append_middleware::<CookieSession>(),
        )
        .build()
);

CookieSession writes encrypted session cookies. By default, those cookies are production-safe (Secure, HttpOnly, SameSite=Lax, Path=/). If you are running a plain-HTTP development environment, configure the cookie safety policy explicitly through the app config:

use htmstd::{CookieSecurity, CookieSession, CookieSessionSettings};

LServer!(
    APP = Server::new()
        .binding("127.0.0.1:3003")
        .mode(RunMode::Development)
        .set_config(CookieSessionSettings::new().security(CookieSecurity::Auto))
        .single_protocol(
            ProtocolBuilder::new(HTTP::server(HttpSafety::default()))
                .append_middleware::<CookieSession>(),
        )
        .build()
);

CookieSecurity::Auto follows RunMode: Production/Beta keep Secure cookies, while Development/Build allow plain HTTP cookies. For production, also configure a stable SessionSecret so sessions survive process restarts.

Middleware can also be attached per-endpoint via middleware = [...] inside the endpoint! block — see example_hotaru for the pattern.

Templates

Render HTML with Akari via akari_render! — the macro looks up the template file and substitutes the named bindings:

endpoint! {
    APP.url("/profile"),
    pub profile<HTTP> {
        akari_render!("profile.html", name = "Alice")
    }
}

HTTP Safety Configuration

Configure request validation per endpoint:

endpoint! {
    APP.url("/upload"),
    config = [HttpSafety::new()
        .with_max_body_size(50 * 1024 * 1024)  // 50MB
        .with_allowed_methods(vec![HttpMethod::POST])
    ],
    pub upload<HTTP> {
        // Handle file upload
    }
}

Examples

Check out the example repository for:

• Basic routing and handlers
• Form processing and file uploads
• Session management with cookies
• CORS configuration
• Multi-protocol applications

Crate Ecosystem

Hotaru is built on a modular architecture:

• hotaru - Main framework with convenient API
• hotaru_core - Core protocol and routing engine
• hotaru_trans - Procedural macros for endpoint! and middleware!
• hotaru_http - HTTP implementation for Hotaru
• hotaru_tls - TLS/HTTPS implementation for Hotaru
• hotaru_rt_tokio - Tokio runtime backend (TokioRuntime)
• hotaru_io_tokio - Tokio TCP/IO backend (TcpTransport, TokioIo)
• hotaru_io_futures - futures-io adapter backend (FuturesIo, experimental)
• hotaru_io_embedded - embedded-io-async adapter backend (EmbeddedIo) — experimental; in-workspace, unpublished (crates.io), and re-exported by hotaru when io_embedded is enabled
• hotaru_lib - Utility functions (compression, encoding, etc.)
• htmstd - Standard middleware library (CORS, sessions)

Changelog

0.8.4 (Current)

• Continued backend split work by moving Tokio-specific IO/runtime support out of hotaru_core.
• Clarified platform and task-mobility feature modes.
• Added explicit local-executor refinements: spawn_local_atomic and spawn_local_no_atomic.
• Made sync primitive selection feature-based: parking_lot, spin, or Hotaru RefCell fallback.
• Removed hidden target_has_atomic behavior from core feature selection.
• Replaced the old full/lite regex names with additive full_regex / lite_regex; when neither is enabled, Hotaru drops the regex dependency and uses its regex-stub path.
• Split facade regex style from template support: full_regex / lite_regex control routing regex, while template controls Akari template support.
• Added hotaru facade re-exports for EmbeddedIo behind io_embedded, and exposed the experimental Embassy backend crate behind embassy.
• Added CI coverage for the hotaru facade on a no-atomic bare-metal target, and deduplicated the core feature matrix so each feature combination is compiled once.
• Updated repository metadata and documentation links for the transfer to https://github.com/Field-of-Dream-Studio/hotaru.
• Continued preparation for a smaller backend-neutral core.

0.8.3

• Core/backend split: hotaru_core is now backend-neutral at the public type layer. Concrete Tokio runtime and TCP/IO implementations moved into sibling crates (hotaru_rt_tokio, hotaru_io_tokio), while the umbrella hotaru crate keeps the familiar Tokio defaults.
• IO adapter crates: futures-io and embedded-io-async adapters moved out of core into hotaru_io_futures and hotaru_io_embedded. Each backend uses local wrapper types (TokioIo<T>, FuturesIo<T>, EmbeddedIo<T>) so adapter impls stay additive and avoid trait-coherence conflicts.
• Simpler hotaru_core features: core no longer owns io_*, rt_*, tokio, or embassy feature flags. It now keeps only the platform axis (std / embedded) and task-mobility axis (spawn_send / spawn_local); runtime and IO backends are selected through backend crates, or through optional facade features on hotaru.
• hotaru facade defaults to Tokio/std: the umbrella keeps Tokio as the supported default path, while exposing experimental optional embedded, embassy, and io_embedded features for in-workspace backend work. io_embedded re-exports EmbeddedIo; the backend crate remains unpublished on crates.io.
• Runtime abstraction cleanup: RuntimeSpec is the backend-neutral runtime trait, with Tokio implemented externally by hotaru_rt_tokio::TokioRuntime. Framework types (Server, Client, builders, and URL/protocol-entry types) now carry explicit transport/runtime parameters in core, while hotaru restores ergonomic defaults.
• MaybeSend task-mobility model: async framework surfaces use MaybeSend so spawn_send builds keep real Send bounds and spawn_local builds can support local !Send futures. hotaru_io_embedded gates its actual embedded-io-async trait impls on spawn_local, not on the embedded platform flag.
• Framework-owned async IO traits: HotaruRead, HotaruWrite, HotaruBufRead, HotaruBufWrite, HotaruIOError, HotaruBufReader, and HotaruBufWriter provide the common IO trait surface used by transports and protocols without hardcoding Tokio types in core.
• Native async trait surfaces: core transport/protocol traits use return-position impl Future instead of async-trait, reducing proc-macro dependency surface and avoiding unnecessary boxed futures at trait boundaries.
• Protocol-agnostic endpoint outcomes: EndpointOutcome<C> lets generated endpoints apply return values to any request context. HTTP keeps the existing HttpResponse endpoint style, while non-HTTP/inbound-only protocols can use () outcomes without placeholder responses.
• Per-protocol URL parsing hooks: Protocol can customize URL tokenization/literal parsing, and URL parser internals such as RawToken, TypeKind, tokenize, and tokens_to_patterns are re-exported for protocol-specific routing work.
• Preferred-language middleware: htmstd adds PreferredLanguageMiddleware, PreferredLanguage, settings, and request-extension helpers for parsing and negotiating the Accept-Language header.
• no_std preparation: core continues moving toward no_std readiness with alloc usage, core imports, Akari embedded/no_std alignment, generic IO errors, and backend-neutral abstractions. Embassy and embedded backend work exists in-tree but remains experimental.
• Sync-main entry macros: run_server! / run_server_until! (blocking) and run_server_no_block! / run_server_no_block_until! (fire-and-forget) let users run a server from an ordinary fn main() — no #[tokio::main], no async fn main. Backed by a new BlockingRuntimeCap capability trait implemented by TokioRuntime.

0.8.2

• http and http_compression moved to optional features (compression default-off)
• HTTP re-exports relocated to hotaru::http
• Clean builds ~35% faster (dropped tracing, gated heavy codecs)
• regex bumped 1.5.6 -> 1.12
• AccessPointTable switched to PRwLock (no more poisoning)
• hotaru_trans .. middleware inheritance now honors the URL's app ident
• hotaru_trans anonymous-fn _ form fixed
• Client / outpoint runtime paired with Client<TS>, the outpoint! macro, and run! / call! invocation sugar
• Protocol trait reshape: channel-based open_channel / handle / send; new Channel trait + ProtocolFlow
• RequestContext rework: Default supertrait, type Channel anchor, inject_request / into_response; new EmptyError
• Result-typed execution chain — no boxing at chain boundaries
• Named access points with a single canonical registration funnel
• Instance-based transports: TransportSpec::Inbound / Outbound replace Accepter / Connector
• HTTPS feature: HTTPS = Http1Protocol<TlsStream, TlsTransport>
• New LServer! / LClient! / LUrl! / LPattern! macros replace LApp!

0.7.x

• Multi-protocol support (HTTP, WebSocket, custom TCP)
• Enhanced security controls with HttpSafety
• Improved middleware system with protocol inheritance
• Performance optimizations in URL routing
• Comprehensive security testing
• .worker() method now properly configures dedicated worker threads per Server instance
• Fixed hotaru new and hotaru init to generate correct endpoint! macro syntax
• Built-in constructor implementation (no external ctor dependency required)
• Fn-style blocks: New syntax pub fn name(req: HTTP) { ... } for endpoint! and middleware! macros (original hotaru blocks syntax preserved)
• Bug fix for URL routing

0.6.x

• Protocol abstraction layer
• Request context improvements
• Standard middleware library (htmstd)
• Cookie-based session management

0.4.x and earlier

• Async/await support with Tokio
• Akari templating integration
• Cookie manipulation APIs
• File upload handling
• Form data processing improvements

Learn More

• Akari Template Engine: https://crates.io/crates/akari
• Homepage: https://hotaru.rs
• Documentation Home Page: https://fds.rs
• GitHub: https://github.com/Field-of-Dream-Studio/hotaru
• Documentation: https://docs.rs/hotaru

Video Resources	URL
Quick Tutorial	Youtube: https://www.youtube.com/watch?v=8pV-o04GuKk&t=6s Bilibili: https://www.bilibili.com/video/BV1BamFB7E8n/

AI-assisted development

Definitions and component declarations are maintained in GOVERNANCE.md.

📄 License

MIT License — see LICENSE.txt.

Copyright (c) 2024-2026 @ Field of Dreams Studio (FDS) & Project-StarFall & PMINE-FDS