Skip to content

development.md

Latest commit

 

History

History
174 lines (124 loc) · 3.74 KB

development.md

File metadata and controls

174 lines (124 loc) · 3.74 KB
Raw

Aether Development Guide

Prerequisites

  • Rust 1.85+ (see rust-toolchain.toml)
  • PostgreSQL 16+ (local or Docker)
  • cargo-deny, sqlx-cli (optional but recommended)
  • Docker (for testcontainers integration tests)

Quick Start

# Clone and enter repo
cd Aether

# Copy environment template
cp .env.example .env

# Start PostgreSQL
docker compose up -d postgres

# Run migrations
export DATABASE_URL=postgres://aether:aether@localhost:5432/aether
sqlx migrate run

# Build workspace
cargo build --workspace

# Run server (dev)
cargo run -p aether-server --bin monitor-server

# Enroll agent (separate terminal)
cargo run -p aether-agent --bin monitor-agent -- enroll \
  --server-url https://localhost:8443 \
  --token <token>

Workspace Layout

crates/
  aether-agent/      # monitor-agent binary
  aether-server/     # monitor-server binary
  aether-protocol/   # wire formats + signing
  aether-domain/     # pure domain logic
  aether-database/   # sqlx repositories
  aether-shared/     # errors, crypto, TLS
  aether-telemetry/  # tracing
  aether-test-utils/ # test helpers
migrations/          # sqlx migrations
tests/integration/   # cross-crate integration tests

Make Targets

make check      # fmt + clippy + test
make fmt        # cargo fmt
make lint       # clippy -D warnings
make test       # cargo test --workspace
make deny       # cargo deny check
make migrate    # sqlx migrate run

Testing

Unit Tests

cargo test -p aether-domain
cargo test -p aether-protocol

Integration Tests (testcontainers)

Requires Docker:

cargo test -p aether-database --features integration-tests
cargo test --test security_agent_auth

Offline sqlx (CI)

cargo sqlx prepare --workspace
# Commit .sqlx/ directory
SQLX_OFFLINE=true cargo build

Feature Flags

Feature Crate Purpose
development-insecure-http agent, server Plain HTTP for local tests only
integration-tests database, test-utils testcontainers
timescale database Future TimescaleDB support

Never enable development-insecure-http in release builds.

Local TLS

For local HTTPS without insecure feature:

# Generate self-signed cert
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem \
  -days 365 -nodes -subj "/CN=localhost"

export AETHER_TLS_CERT=./cert.pem
export AETHER_TLS_KEY=./key.pem

Or use development-insecure-http feature for tests only:

cargo test -p aether-server --features development-insecure-http

Code Style

  • cargo fmt — rustfmt per rustfmt.toml
  • cargo clippy --workspace --all-targets -- -D warnings
  • No unwrap()/expect() in production code paths
  • Errors: thiserror in libs, anyhow in binaries
  • Time: time crate, not chrono

Adding a Migration

sqlx migrate add description_here
# Edit migrations/<timestamp>_description_here.sql
sqlx migrate run
cargo sqlx prepare --workspace

Debugging Agent Signing

monitor-agent diagnostics sign-test \
  --method POST \
  --path /api/v1/agent/heartbeat \
  --body '{"observed_at":"…"}'

Prints canonical string and signature for manual verification.

CI

GitHub Actions .github/workflows/ci.yml:

  1. fmt check
  2. clippy
  3. deny check
  4. test (with postgres service)
  5. verify no development-insecure-http in release

Common Issues

sqlx compile errors

Ensure DATABASE_URL is set or use SQLX_OFFLINE=true with prepared queries.

Clock skew test failures

Tests use fixed timestamps; check AETHER_CLOCK_SKEW_SECS if flaky.

testcontainers port conflicts

Set DOCKER_HOST or ensure Docker daemon running.

Contributing

See AGENTS.md for crate conventions and PR guidelines.