Starbase is a framework for building performant command line applications and developer tools. A starbase is built with the following modules:
- Reactor core - Async-first powered by the
- Fusion cells - Thread-safe concurrent systems for easy processing.
- Communication array - Event-driven architecture with
- Shield generator - Native diagnostics and reports with
- Navigation sensors - Span based instrumentation and logging with
- Engineering bay - Ergonomic utilities with
- Command center - Terminal styling and theming with
- Cargo hold - Archive packing and unpacking with
An application is divided into phases, where systems in each phase will be processed and completed before moving onto the next phase. The following phases are available:
- Startup - Register and or load components into the application instance.
- Example: load configuration, detect workspace root, load plugins
- Analyze - Analyze the current application environment, update components, and prepare for
- Example: generate project graph, load cache, signin to service
- Execute - Execute primary business logic.
- Example: process dependency graph, run generator, check for new version
- Shutdown - Shutdown whether a success or failure.
- Example: cleanup temporary files
The startup phase processes systems serially in the main thread, as the order of initializations must be deterministic, and running in parallel may cause race conditions or unwanted side-effects.
The other 3 phases process systems concurrently by spawning a new thread for each system. Active systems are constrained using a semaphore and available CPU count. If a system fails, the application will abort and subsequent systems will not run (excluding shutdown systems).
Systems are async functions that implement the
System trait, are added to an application phase,
and are processed (only once) during the applications run cycle. Systems receive each
component type as a distinct parameter.
Systems are loosely based on the S in ECS that Bevy and other game engines utilize. The major difference is that our systems are async only, run once, and do not require the entity (E) or component (C) parts.
use ; async async
Each system parameter type (
Emitters) is a type alias that wraps the
underlying component manager in a
Arc<RwLock<T>>, allowing for distinct read/write locks per
component type. Separating components across params simplifies borrow semantics.
Furthermore, for better ergonomics and developer experience, we provide a
attribute that provides "magic" parameters similar to Axum and Bevy, which we call system
parameters. For example, the above system can be rewritten as:
Which compiles down to the following, while taking mutable and immutable borrowship rules into account. If a rule is broken, we panic during compilation.
Additional benefits of
- Return type and return statement are both optional, as these are always the same.
- Parameters can be mixed and matched to suit the system's requirements.
- Parameters can be entirely ommitted if not required.
- Avoids writing
write().awaitover and over.
- Avoids importing all necessary types/structs/etc. We compile to fully qualified paths.
- Functions are automatically wrapped for instrumentation.
Jump to the components section for a full list of supported system parameters.
In this phase, components are created and registered into their appropriate manager instance.
In this phase, registered components are optionally updated based on the results of an analysis.
In this phase, systems are processed using components to drive business logic. Ideally by this phase, all components are accessed immutably, but not a hard requirement.
Additionally, execute systems can be associated with arguments. This is useful for functionality like CLI commands.
To access the arguments within the system itself, you can use the
#[system] macro, coupled with
ArgsRef<T> system parameter.
If not using the macro, you can access the arguments like so:
Shutdown runs on successful execution, or on a failure from any phase, and can be used to clean or reset the current environment, dump error logs or reports, so on and so forth.
Components are values that live for the duration of the application (
'static) and are stored
Any instances, ensuring strict uniqueness. Components are dividied into 3
- States - Granular values.
- Resources - Compound values / singleton instances.
- Emitters - Per-event emitters.
States are components that represent granular pieces of data, are typically implemented with a tuple
or unit struct, and must derive
State. For example, say we want to track the workspace root.
use State; use PathBuf; ;
Statederive macro automatically implements
DerefMutwhen applicable. In the future, we may implement other traits deemed necessary.
States can be added directly to the application instance (before the run cycle has started), or
StatesMut system parameter.
StatesRef system parameter can be used to acquire read access to the entire states manager. It
cannot be used alongside
StateRef system parameter can be used to immutably read an individual value
from the states manager. Multiple
StateRefs can be used together, but cannot be used with
StatesMut system parameter can be used to acquire write access to the entire states manager.
It cannot be used alongside
StateMut system parameter can be used to mutably access an individual value,
allowing for the value (or its inner value) to be modified. Only 1
StateMut can be used in a
system, and no other state related system parameters can be used.
Resources are components that represent compound data structures as complex structs, and are akin to instance singletons in other languages. Some examples of resources are project graphs, dependency trees, plugin registries, cache engines, etc.
Every resource must derive
use Resource; use PathBuf;
Resourcederive macro automatically implements
AsRef. In the future, we may implement other traits deemed necessary.
Resources can be added directly to the application instance (before the run cycle has started), or
ResourcesMut system parameter.
ResourcesRef system parameter can be used to acquire read access to the entire resources
manager. It cannot be used alongside
ResourceRef system parameter can be used to immutably read an individual value
from the resources manager. Multiple
ResourceRefs can be used together, but cannot be used with
ResourcesMut system parameter can be used to acquire write access to the entire resources
manager. It cannot be used alongside
ResourceMut system parameter can be used to mutably access an individual value.
ResourceMut can be used in a system, and no other resource related system parameters can be
Emitters are components that can dispatch events to all registered subscribers, allowing for
non-coupled layers to interact with each other. Unlike states and resources that are implemented and
registered individually, emitters are pre-built and provided by the
struct, and instead the individual events themselves are implemented.
Events must derive
Event, or implement the
Event trait. Events can be any type of struct, but
the major selling point is that events are mutable, allowing inner content to be modified by
use ; use Project; ; let emitter = new;
Emitters can be added directly to the application instance (before the run cycle has started), or
EmittersMut system parameter.
Each emitter represents a singular event, so the event type must be explicitly declared as a generic when creating a new emitter.
EmittersMut system parameter can be used to acquire write access to the entire emitters
manager, where new emitters can be registered, or existing emitters can emit an event. It cannot
be used alongside
EmitterRef (preferred) or
EmitterMut system parameters can be used to access an
individual emitter. Only 1
EmitterMut can be used in a system, but multiple
EmitterRef can be
used. The latter is preferred as we utilize interior mutability for emitting events, which allows
multiple emitters to be accessed in parallel.
Errors and diagnostics are provided by the
miette crate. All
layers of the application, from systems, to events, and the application itself, return the
miette::Result type. This allows for errors to be easily converted to diagnostics, and for miette
to automatically render to the terminal for errors and panics.
To benefit from this, update your
main function to return
MainResult, and call
to register error/panic handlers.
use ; async
To make the most out of errors, and in turn diagnostics, it's best (also suggested) to use the
use Diagnostic; use Error;
In systems, events, and other fallible layers, a returned
Err must be converted to a diagnostic
first. There are 2 approaches to achieve this: