Skip to content

Latest commit

 

History

History
202 lines (132 loc) · 5.16 KB

README.md

File metadata and controls

202 lines (132 loc) · 5.16 KB

Overwatch

Build Status Codecov Status

MIT License crates.io docs.rs

A lightweight framework for building modular, interconnected applications.

Overwatch simplifies the development of complex systems by enabling seamless communication between independent components. It combines the flexibility of microservices with the simplicity of a unified framework.

Table of Contents

Requirements

  • Rust ≥ 1.63

Quick Start

Add overwatch and overwatch-derive to your Cargo.toml:

[dependencies]
overwatch = "1"
overwatch-derive = "1"

Here's a simple example to get you started:

// This example is for illustration purposes only and is not meant to compile.
// There's parts of the code that are required to be implemented by the user.
// Please refer to the examples directory for working code. 

use overwatch::{
    overwatch::OverwatchRunner,
    services::{ServiceCore, ServiceData},
    OpaqueServiceHandle
};
use overwatch_derive::Services;

struct MyService;

impl ServiceData for MyService {
    // Implement ServiceData
}

#[async_trait::async_trait]
impl ServiceCore for MyService {
    // Implement ServiceCore
}

#[derive(Services)]
struct MyApp {
    my_service: OpaqueServiceHandle<MyService>,
    // ... other services
}

fn main() {
    // `MyAppServiceSettings` is a struct that contains the settings for each service.
    // Generated by the `Services` derive.
    let my_app_settings = MyAppServiceSettings {
        my_service: ()
    };
    let my_app =
        OverwatchRunner::<MyApp>::run(my_app_settings, None).expect("OverwatchRunner failed");
    my_app.wait_finished();
}

Features

  • Modular Design: Build self-contained, reusable components with clear interfaces.
  • Asynchronous Communication: Scalable and non-blocking communication between components.
  • Lifecycle Management: Centralized control over component initialization, updates, and shutdown.
  • Dynamic Configuration: Handle runtime configuration updates seamlessly.
  • Testability: Components are designed for easy testing and mocking.

Design Goals

Our architecture is built on three core principles:

Modularity

  • Components are self-contained with well-defined interfaces.
  • Communication between components is explicit and predictable.
  • Designed for easy testing and performance evaluation.

Single Responsibility

  • Each component focuses on a single task for easier debugging.
  • Shared state is minimized to reduce complexity.

Observability

  • Workflows are transparent and traceable.
  • Components are designed for easy testing and monitoring.
  • Asynchronous communication ensures scalability and clarity.

Components

Overwatch

  • Acts as the central messaging relay for internal communications.
  • Manages the lifecycle of all services.
  • Handles dynamic configuration updates.

Services

  • Modular units that perform specific tasks within the system.
  • Operated and coordinated by Overwatch.

Project Structure

  • overwatch: The core framework.
  • overwatch-derive: Macros to simplify component implementation.

Development Workflow

Running Tests

  • Run all tests: cargo test.
  • View test outputs: cargo test -- --nocapture.

Running Examples

  • Execute an example: cargo run --example {example_name}.

Generating Documentation

  • Build and open documentation: cargo doc --open --no-deps.

Contributing

We welcome contributions! Please read our Contributing Guidelines for details on how to get started.

License

Overwatch is licensed under the MIT License.

Community

Join the conversation and get help: