API reference and notes

Source revision, common mistakes, and behavior that differs from older documentation.

This guide treats source code as authoritative. If an older document conflicts with behavior, the public API at the source revision below takes precedence.

Source revision#

This guide targets the lilyrs 0.1.0 release and source commit 78ca08b822aa192623c7bcffd90edaf06e4f8e55. Publication and source review date: 18 September 2026. lilyrs and the required component crates are published on crates.io. The manifest minimum and validated toolchain are Rust 1.96.1, with edition 2024.

The primary installation path is lilyrs = { version = "0.1.0", features = ["http-api"] }. Public source is available at lily-platform/lilyrs, and versioned API documentation is on docs.rs. Direct component crates are also published; this guide uses the facade in application examples.

Registry publication, source review, and application tests are separate evidence. Results obtained from the older checkout are not presented as results for the updated examples; the testing page explains validation coverage.

Common mistakes#

Incorrect assumption	Correct use
`build` opens a socket	The listener opens during `start`
Controllers are created for every request	They have application lifetime; receive Scoped services in actions
`guard(instance)` protects every route	The action needs a guard attribute
`Result<String, E>` is plain text	It is a JSON string; use `PlainText` for explicit text
`Result<(), E>` automatically means 204	Use `NoContent`
DI registrations are added manually at runtime	Injectable generates link-time registrations
Middleware after-code marks the end of a stream	A lazy response may complete later
Cache integration enables response caching	The application owns HTTP caching policy
OpenAPI security performs authentication	A guard performs the actual check
`detached()` preserves Mongo timeouts	Use a configured operation context
Uploading stores the file	Parsing is provided; the application owns persistence
`lilyrs = "0.1.0"` enables HTTP	Select the `http-api` feature
`http-api` enables every facade module	DI is at the framework root; separate `lilyrs::injection` requires `injection`
Base and factory features are combined	Select `*-factory` instead of the corresponding base; do not use `--all-features`

Differences from older documents#

C01 — Startup API; resolved. The old akinci_core and synchronous builder example recorded on 14 September is absent from the new root README. The current application entry point is lilyrs::http_api; the builder uses new(&str) with an address or default, followed by async build/start. This record is not an open issue against the current README.

C02 — Crate names; resolved. The new root README documents the Lilyrs facade and current components; the old akinci_* architecture list has been removed. This site retains the HTTP API, WebSocket, and Consumer product split. The cache package is now lily_redis, and the Mongo repository package is lily_mongo_repository; application examples access them through lilyrs::redis and lilyrs::mongodb.

C03 — Repeated global middleware; scope clarification. The rejection statement in the current HTTP README appears in the controller/action attribute context. Repeating a middleware type in the combined controller/action list is rejected. Global middleware::<M>() calls collect registrations in order; descriptor validation checks conflicting exclusive keys, not type names. Do not combine these scopes to assume that every repeated global registration is rejected. Register each global type once. The previous review's probe that observed two constructor calls is historical evidence; this release update does not claim to have rerun it.

C04 — Mongo operation context; still present. The service example in Mongo's lib.rs still uses detached(), while operational guidance recommends configured contexts. detached() has no deadline. This guide uses DatabaseService::operation_context(token) and an explicit cancellation bridge for request operations.

Evidence from the earlier review is preserved in the historical docs/lily-http-api-analiz.md. These statuses have been revised against the published release's source; the framework source code was not changed.

Distinguish built-in APIs from application recipes#

Lily's HTTP surface includes guards/middleware, DI, CORS, CSRF, cookies, typed extraction, files/streams/SSE, and OpenAPI. The application supplies the token verifier, session store, HTTP rate-limit binding, Swagger UI, and health-endpoint policy.

Do not use NestJS names such as modules, pipes, interceptors, exception filters, Passport/JWT module, automatic versioning, or cron as though identical APIs existed in Lily. Build similar behavior through Lily's verified extension points when needed.

Examples#

Download the code for the first application, DI, middleware, authentication, cookies, CSRF, files and SSE, OpenAPI, background worker, HTTP errors, typed requests, PostgreSQL transactions, PgRepository, MongoDB, and rate limiting.

These are the teaching modules used in the pages. Each page lists its dependency/configuration and external service requirements. Copying all of them into one binary may create OpenAPI coverage or route registration conflicts; choose the example for the topic you are working on.