AICore Web

aicore-web is an async REST framework workspace for AICore.

This first delivery includes:

• async router-based request dispatch on top of std.http_server
• ordered filters with short-circuit support
• request context carrying headers, query parameters, path parameters, and body
• JSON-first request/response helpers and JSON framework error responses
• XML object request/response helpers with safe flat-object parsing in aicore_web_xml
• input validation primitives and built-in validation helpers in aicore_web_validation
• compiler-lowered route/filter and validation annotations via aic web-gen
• bounded server configuration, method allow-listing, request/path/header limits, safe path preflight checks, lifecycle stats, and bounded async accept batches
• in-memory dispatch test helpers in aicore_web_testing
• reusable structured JSON-line logging in aicore_log with the aicore_web_log web adapter
• reusable metrics in aicore_metrics with the aicore_web_metrics web adapter and demo /metrics route
• reusable W3C traceparent context propagation in aicore_trace with the aicore_web_trace web adapter
• reusable typed configuration in aicore_config with the aicore_web_config server configuration adapter
• reusable authentication primitives in aicore_auth with aicore_web_auth filters for API keys, bearer tokens, optional auth, and required auth
• reusable resilience primitives in aicore_resilience with aicore_web_resilience filters for rate limits, timeout budgets, and circuit breakers
• OpenAPI 3.0.3 JSON generation in aicore_web_openapi with a demo /openapi.json route and deterministic annotation fixture checks
• optional PostgreSQL web integration helpers in aicore_web_postgres without coupling aicore_web_core to postgres-client
• a runnable demo app under packages/demo_app
• a conformance app under packages/conformance_app covering filters, JSON, XML, validation, extractors, observability, and security limits
• a repeatable benchmark app and quick/full/soak benchmark harness under packages/benchmark_app and scripts/benchmark.sh
• a production-shaped operations example under examples/production_service_app
• an optional PostgreSQL integration example under examples/postgres_client_app
• checked service templates and a copy workflow under templates/ and scripts/scaffold-web-service.sh

Workspace Commands

aic check /absolute/path/to/aicore-web
aic build /absolute/path/to/aicore-web
aic run /absolute/path/to/aicore-web/packages/demo_app
aic run /absolute/path/to/aicore-web/packages/conformance_app
aic run /absolute/path/to/aicore-web/examples/production_service_app
./scripts/benchmark.sh /absolute/path/to/aicore-web /absolute/path/to/aicore-web/benchmark-results quick
bash /absolute/path/to/aicore-web/scripts/check-release-metadata.sh /absolute/path/to/aicore-web
bash /absolute/path/to/aicore-web/scripts/check-openapi-fixture.sh /absolute/path/to/aicore-web
bash /absolute/path/to/aicore-web/scripts/check-templates.sh /absolute/path/to/aicore-web

Installation

Use the AICore CLI from the sibling Aicore/aicore repository:

cargo install --path /absolute/path/to/Aicore/aicore --force
aic setup

Then run the workspace commands above.

Documentation

• API guide
• Middleware author guide
• XML scope
• Shutdown lifecycle
• Production notes
• Operations guide
• Performance and backpressure
• Testing
• Security
• Authentication
• Resilience
• OpenAPI
• Structured logging
• Metrics
• Tracing
• Configuration
• Public API
• Compatibility and release policy
• Release process
• PostgreSQL integration
• Service scaffolding

Release Status

Current version: 0.1.0.

Minimum tested AICore compiler: keaz/aicore@bd5d70a.

GA runtime support targets: Linux on ubuntu-latest and macOS on macos-latest. CI runs every supported runtime target with bounded timeouts for the demo app, conformance app, and benchmark smoke tests.

Platform	GA runtime status	Coverage
Linux (ubuntu-latest)	Supported target	GitHub Actions matrix runs aic check, demo app, conformance app, benchmark smoke, and postgres example check.
macOS (macos-latest)	Supported target	GitHub Actions matrix runs the same bounded release gate as Linux.
Windows	Not production-supported	Native async REST server coverage is tracked upstream in keaz/aicore#391.

Manual route/filter registration remains production-supported. Source attributes for routes, filters, and DTO validation are lowered by the sibling AICore compiler; inspect generated registration and validators with aic web-gen.

Servlet/Actix-style middleware is implemented with ordered Filter types: accepted requests run before in ascending order before route dispatch, after runs in reverse order for filters that continued, and short-circuit/error paths return stable JSON Respond(...) responses. Duplicate filter orders are rejected; server preflight rejects happen before filters.