aspirant200715/onyx

Purpose and Workspace

Onyx is a first-principles Rust web framework at Tier 1: a raw TCP HTTP/1.1 server, routing, request extraction, response conversion, and typed errors. The workspace manifest is Cargo.toml; implementation is under onyx/crates/.

Its public application-facing entry point is the core crate prelude/API in onyx/crates/ember-core/src/lib.rs. A minimal server usage example is onyx/crates/ember-core/examples/hello_tcp.rs.

HTTP Foundation

ember-http owns HTTP protocol models and parsing, independent of application routing:

• Request and response representations: onyx/crates/ember-http/src/request.rs, onyx/crates/ember-http/src/response.rs

• HTTP primitives—methods, statuses, headers, and versions: onyx/crates/ember-http/src/method.rs, onyx/crates/ember-http/src/status.rs, onyx/crates/ember-http/src/headers.rs

• Incremental parsing boundary for raw request bytes: onyx/crates/ember-http/src/parser/request.rs, onyx/crates/ember-http/src/parser/request_line.rs

This crate is the protocol boundary between TCP input and a typed HTTP request.

TCP Server and Dispatch

The runtime server is implemented in onyx/crates/ember-core/src/server.rs. It accepts raw TCP traffic, invokes the HTTP parser, then hands parsed requests to routing/handler dispatch. The framework is Rust-native and appears to use direct TCP rather than an external HTTP server, async runtime, reverse proxy, database, or cloud service.

Errors crossing server, routing, and handler boundaries are centralized in onyx/crates/ember-core/src/error.rs, with HTTP-layer errors separately represented in onyx/crates/ember-http/src/error.rs.

Routing and Path Resolution

Routing maps an HTTP method and request path to a handler:

• Route representation and registration: onyx/crates/ember-core/src/route.rs

• Router/dispatch coordination: onyx/crates/ember-core/src/router.rs

• Static/dynamic segment matching and parameter capture: onyx/crates/ember-core/src/path_matcher.rs, onyx/crates/ember-core/src/path.rs

Control flow is request → router → matching route → handler. Dynamic path captures become input for extraction rather than requiring handlers to parse URLs directly.

Handler Input Extraction

Core request extractors isolate handler code from raw HTTP structures:

• Extractor abstraction: onyx/crates/ember-core/src/extractor.rs

• Path and query decoding: onyx/crates/ember-core/src/path.rs, onyx/crates/ember-core/src/query.rs

• Typed header access: onyx/crates/ember-core/src/header.rs

Handlers can receive framework request data and expose failures through result-based error handling, rather than manually validating all transport input.

Response and Error Conversion

Handler outputs are normalized through responder abstractions:

• Generic responder contract and conversions: onyx/crates/ember-core/src/responder.rs

• JSON response support: onyx/crates/ember-core/src/json.rs

• HTTP response construction/status output: onyx/crates/ember-http/src/response.rs, onyx/crates/ember-http/src/status.rs

The outgoing flow is handler return value or EmberError → responder/error mapping → HTTP response → TCP write.

Cross-Cutting Extension Points

Middleware is organized as a core pipeline extension point, with current authentication and logging modules at onyx/crates/ember-core/src/middleware/mod.rs, onyx/crates/ember-core/src/middleware/auth.rs, and onyx/crates/ember-core/src/middleware/logger.rs.

onyx/crates/ember-macros/src/lib.rs is a separate procedural-macro crate, providing compile-time ergonomic extension capability without coupling macro implementation to the HTTP/runtime layers.