AsterForge

Shared runtime foundation and infrastructure kernel for Aster services.
Product-neutral components, schemas, stores, and lifecycle mechanics for AsterDrive, AsterYggdrasil, and future Aster projects.

What is AsterForge?

AsterForge is the shared runtime foundation for Aster products. It is no longer just a place for duplicated helper functions; it is the product-neutral infrastructure kernel that Aster services plug into for lifecycle, component registration, health reporting, shutdown ordering, configuration reload, cache backends, database-owned infrastructure tables, mail outbox dispatch, audit log mechanics, scheduled tasks, runtime leases, logging, metrics, panic handling, API helpers, Actix middleware, external-auth connectors, storage key helpers, and validation.

Forge is not a product business framework. Product-specific code, permissions, user-facing API semantics, product entities, task payloads/results, audit action enums, presentation rules, and business repositories should stay in the owning application repositories. Product-neutral runtime mechanics, common database schemas/stores, component graph contracts, retry/claim/lease rules, and cross-process coordination belong in Forge when multiple Aster services need the same behavior.

The target shape for new products is a thin product entrypoint:

aster_forge_runtime::AsterRuntime::builder()
    .component(http_component(...))
    .component(database_component(...))
    .component(background_task_component(...))
    .component(mail_outbox_component(...))
    .component(audit_component(...))
    .run()
    .await?;

Product code still owns resource creation and business semantics; Forge owns the reusable lifecycle and persistence mechanics behind those components.

All crate names use the aster_forge_* prefix. The workspace targets Rust 1.94.0+, edition 2024, and uses dual MIT OR Apache-2.0 license metadata.

Crates

Area	Crates
Runtime kernel	aster_forge_runtime, aster_forge_config, aster_forge_logging, aster_forge_metrics, aster_forge_panic, aster_forge_alloc
Web and API	aster_forge_api, aster_forge_api_docs_macros, aster_forge_actix_middleware, aster_forge_actix_observability, aster_forge_external_auth
Data, coordination, and background work	aster_forge_db, aster_forge_cache, aster_forge_tasks, aster_forge_mail, aster_forge_audit
Storage and domain-neutral helpers	aster_forge_storage_core, aster_forge_file_classification
Utilities	aster_forge_crypto, aster_forge_utils, aster_forge_validation

Integration rules

• Keep product permissions, user-facing errors, business repositories, API semantics, task payloads/results, audit actions/details, and presentation rules in the product repository.
• Use Forge-owned schema/store builders for product-neutral infrastructure tables such as runtime leases, scheduled tasks, mail outbox, and audit logs.
• Register runtime subsystems through Forge components instead of hand-writing shutdown order in product entrypoints.
• Map Forge errors at the product service boundary.
• Write explicit product-side adapters for metrics, runtime config, permission, audit presentation, and policy decisions.
• Use AsterDrive and AsterYggdrasil as references, not as reasons to move business logic into Forge.

See docs/guide/new-project-integration.md for the target new-product shape and docs/guide/integration-principles.md for the detailed boundary rules.

Service template

New Aster services can start from the bundled cargo generate template:

cargo generate --git https://github.com/AsterCommunity/AsterForge.git \
  templates/aster-service \
  --name aster_product_service \
  --define server_port=3000

The template wires a thin product entrypoint to Forge runtime components, keeps generation prompts to package description and HTTP port, uses the official AsterForge Git repository for Forge dependencies, uses conservative defaults for server/database/cache/config-sync/logging, derives project-name based defaults for database URL and config sync topic, leaves file logging disabled by default, includes a migration crate for Forge-owned infrastructure tables, and uses Cargo metadata such as env!("CARGO_PKG_NAME") for process, health, panic, and placeholder mail display names. Product repositories still own their business routes, product migrations, config registry, audit enums/details, task payloads/results, and mail template rendering.

Documentation

• Documentation site
• Chinese guide
• New project integration guide
• English overview
• Crate reference pages
• Reference projects

The Chinese crate pages are currently the authoritative integration reference. English pages provide entry points while the crate-by-crate documentation is being mirrored.

Development

cargo check --workspace
cargo test --workspace
cargo fmt --all

Documentation site:

cd docs
bun install
bun run docs:dev

Project structure

crates/                 Rust workspace crates
docs/                   VitePress documentation site and crate reference pages
developer-docs/         Compatibility entry points for developer documentation
scripts/                Repository maintenance scripts
templates/              cargo-generate templates for new Aster services

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option, as declared in the workspace package metadata.