Skip to main content

Module

cratefield_core

Trait Module 

Source 
pub trait Module:
    Send
    + Sync
    + 'static {

Show 15 methods    // Required methods
    fn name(&self) -> &'static str;
    fn version(&self) -> &'static str;
    fn requires(&self) -> &'static [Port];
    fn migrations(&self) -> Migrations;
    fn validate_config(&self, cfg: &dyn Config) -> Result<(), ConfigError>;
    fn router(&self, ctx: ModuleContext) -> Router;

    // Provided methods
    fn harness_api(&self) -> u32 { ... }
    fn optional(&self) -> &'static [Port] { ... }
    fn tables(&self) -> &'static [&'static str] { ... }
    fn emits(&self) -> &'static [&'static str] { ... }
    fn public_writes(&self) -> bool { ... }
    fn well_known(&self) -> Option<Router> { ... }
    fn surface(&self) -> Surface { ... }
    fn events(&self) -> Vec<(EventName, EventHandler)> { ... }
    fn scheduled<'a>(
        &'a self,
        ctx: &'a ModuleContext,
        cron: &'a str,
    ) -> BoxFuture<'a, Result<(), AnyError>> { ... }

}
Expand description

A Factory Zero module. Object-safe; composed as Arc<dyn Module>.

Handlers get the request scope as an axum extractor: async fn join(scope: Scope, State(ctx): State<Arc<ModuleContext>>, ...). There is no ambient “current request” (ADR 0007).

Required Methods§

Source

fn name(&self) -> &'static str

Kebab-case name; mounted at /v1/<name>.

Source

fn version(&self) -> &'static str

env!("CARGO_PKG_VERSION"), surfaced by /__health.

Source

fn requires(&self) -> &'static [Port]

Ports the module cannot run without; missing = build error.

Source

fn migrations(&self) -> Migrations

The module’s migrations, embedded per dialect.

Source

fn validate_config(&self, cfg: &dyn Config) -> Result<(), ConfigError>

Rejects invalid configuration: missing required keys or malformed values, reported together with the module name.

When it runs. The conformance kit calls it, and a module’s own tests should. It cannot run at Harness::build or in fz doctor, because neither has the deploy config — the values live on the runtime Env and only exist per request. The Cloudflare runtime therefore runs it once at cold start and logs any failure loudly (console_error!, so it reaches Workers Logs); it does not fail the boot, so a misconfigured module still degrades per request (issue #101) rather than taking the whole Worker down. Turning that into a hard boot failure is a deployment decision for an ADR.

§Errors

Err listing every invalid or missing key for this module.

Source

fn router(&self, ctx: ModuleContext) -> Router

The module’s router, nested under /v1/<name>.

Provided Methods§

Source

fn harness_api(&self) -> u32

Contract version, checked by Harness::build.

Source

fn optional(&self) -> &'static [Port]

Ports the module uses when present.

Source

fn tables(&self) -> &'static [&'static str]

Table names this module owns; duplicates across modules are a build error.

Source

fn emits(&self) -> &'static [&'static str]

Event names this module emits ("<module>.<event>"), listed by /__health.

Source

fn public_writes(&self) -> bool

Whether the module has public write endpoints; drives the production-captcha rule (section 11).

Source

fn well_known(&self) -> Option<Router>

Routes this module serves at the root under /.well-known, for spec-mandated discovery documents (OIDC openid-configuration, jwks.json) that must live outside /v1 (issue #46). Paths are relative to the prefix: register /jwks.json, not /.well-known/jwks.json.

At most one module may provide one: discovery URLs are a singleton namespace, so Harness::build fails (naming every provider) when two modules return a router here. None by default.

Source

fn surface(&self) -> Surface

The module’s UI surface (ADR 0010): the actions a renderer may offer and the views that compose them. Input schemas come from the handler’s own body types (Action::input::<Body>()), so the declaration cannot drift from the route. Harness::build validates it; GET /__surface serves the composition. Default: nothing, and a module that declares nothing renders nothing.

Source

fn events(&self) -> Vec<(EventName, EventHandler)>

Handlers for events other modules emit; registered at Harness::build.

Source

fn scheduled<'a>( &'a self, ctx: &'a ModuleContext, cron: &'a str, ) -> BoxFuture<'a, Result<(), AnyError>>

Scheduled work (cron is the trigger expression). Default: none.

Dyn Compatibility§

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§