wora

Write Once Run Anywhere (WORA): A Rust framework for building applications (daemons, etc.) that run in different environments (Linux, Kubernetes, etc.). Just like Java's claim, it really doesn't run everywhere. no_std or embedded environments are not supported.

Status

This crate is an early-stage async framework. The main public API is usable, with Unix-like platforms as the primary target and environment-specific executors for systemd, launchd, and container-style deployments.

• restart policies and shutdown supervision can be applied by exec_async_runner_with_restart_options
• initial typed config and secret loading is built into the runner
• event-driven apps can use Wora::run_event_loop to auto-apply typed reloads
• observability can be routed through sinks via O11yProcessor

Feature Tour

• abstracts over common boilerplate with an API
• execute the same code in different executors (with or without recompiling)
• translates platform-specific control inputs into runtime control events
• watches metadata and secrets directories and emits typed reload events
• supervises readiness, health, and graceful shutdown
• exposes host, process, runtime, and tracing observability events
• ships observability sinks and a processor for fan-out

Supported Environments

• async-based apps
• Unix-like environments
  • Linux-specific host details through procfs
  • macOS host details through sysinfo
• service-manager and orchestration integrations
  • SystemdExecutor
  • LaunchdExecutor
  • ContainerExecutor

Architecture

WORA has five main pieces:

• App: the workload lifecycle trait. Applications implement setup, main, reload_config, reload_secrets, and end.
• AsyncExecutor: the environment adapter. Executors provide directories, setup, readiness, and teardown behavior.
• Wora: the runtime context passed to apps. It carries directories, host data, event channels, runtime status, and observability options. Health and readiness are reported through Wora::report_health(...), Wora::report_readiness(...), or the cloned RuntimeStatusHandle.
• WFS: the virtual filesystem abstraction. PhysicalVFS is the host filesystem implementation.
• LockBackend: the single-instance coordination abstraction. ProcLockBackend uses host lock files and InMemoryLockBackend is useful for tests and fully virtual runner flows.
• O11yProcessor: the observability pipeline for fan-out into sinks.

exec_async_runner wires those pieces together by creating a lock file, initializing observability, building the Wora context, running executor and app setup, loading initial config and secrets, watching the metadata and secrets directories, invoking App::main, supervising shutdown/readiness/health, and then running teardown.

When a lock backend reports contention, the runner returns MainEarlyReturn::AlreadyRunning(...) instead of collapsing that case into a generic exit code.

Getting Started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.

Prerequisites

• Rust >= 1.95

Usage

Run the basic example:

cargo run --example basic

Run the daemon-style event loop example:

cargo run --example async_daemon -- --run-mode user

Run the Linux systemd daemon example:

cargo run --example systemd_daemon

Sample unit file:

examples/systemd_daemon.service

Run the onboarding example:

cargo run --example onboarding

Run checks:

cargo fmt --check
cargo test

AI Disclosure

OpenAI Codex is used to write documentation/tests and find issues. Everything is reviewed by me and I vouch for these AI-generated changes.

Versioning

We use SemVer for versioning when x.y.z when x is > 0, otherwise versioning is arbitrary. For the versions available, see the tags on this repository.

Authors

• Adam Flott - Initial work - adamflott

See also the list of contributors who participated in this project.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details

Acknowledgments