Skip to content

development.md

Latest commit

 

History

History
173 lines (125 loc) · 3.95 KB

development.md

File metadata and controls

173 lines (125 loc) · 3.95 KB

Development Setup

Prerequisites

Rust

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Minimum: Rust stable (edition 2021). The runner uses sqlx with compile-time query checking — set SQLX_OFFLINE=true if you don't have a local database.

Protobuf + Swift codegen

brew install protobuf swift-protobuf grpc-swift

Swift / Xcode

Xcode 26.4+ from the Mac App Store. Target: macOS 26+, Apple Silicon only.

brew install swiftlint

gRPC testing

brew install grpcurl

Docker (for cloud mode)

Docker Desktop or colima for container-backed sessions.

Project Structure

relay/
├── runner/           # Rust gRPC+REST server
│   ├── src/          # Source code (~5000 LOC)
│   ├── migrations/   # SQLite migrations (sqlx)
│   └── Cargo.toml
├── MacApp/           # Swift macOS client
│   ├── Packages/     # SPM packages (11 modules)
│   ├── Relay/        # App target
│   └── Relay.xcodeproj
├── proto/            # Protobuf definitions
│   └── terminal.proto
├── docker/           # Docker support files
└── docs/             # Documentation

Building

Rust Runner

cd runner
cargo check                    # Fast compilation check
cargo build                    # Debug build
cargo build --release          # Release build

macOS Client

xcodebuild build \
  -project MacApp/Relay.xcodeproj \
  -scheme Relay \
  -destination 'platform=macOS,arch=arm64' \
  CODE_SIGN_IDENTITY=-

Or open MacApp/Relay.xcodeproj in Xcode.

Protobuf Codegen

./proto/generate.sh

Generates Swift code into MacApp/Packages/RemoteTerminal/Sources/RemoteTerminal/Generated/. Rust codegen is automatic via runner/build.rs.

Running Locally

Runner (no auth, defaults)

cd runner
RUST_LOG=info cargo run

Starts the gRPC server on :50051 and REST API on :8080.

Runner (cloud mode with Docker)

cd runner
cargo run -- init --cloud    # Creates CA, config, database
RUST_LOG=info cargo run      # Starts with cloud_mode=true

Smoke test with grpcurl

grpcurl -plaintext localhost:50051 list
grpcurl -plaintext localhost:50051 relay.terminal.v1.TerminalService/ListSessions
grpcurl -plaintext -d '{}' localhost:50051 relay.terminal.v1.TerminalService/CreateSession

REST API smoke test

curl http://localhost:8080/healthz
curl http://localhost:8080/api/v1/openapi.json
# With auth:
curl -H "Authorization: Bearer <token>" http://localhost:8080/api/v1/health

Testing

Rust

cd runner
cargo test                     # All unit tests
cargo test test_name           # Single test
cargo clippy -- -D warnings    # Lint (matches CI)
cargo fmt --check              # Format check

Swift

cd MacApp
swiftlint lint --strict
xcodebuild test \
  -project Relay.xcodeproj \
  -scheme Relay \
  -destination 'platform=macOS,arch=arm64' \
  CODE_SIGN_IDENTITY=-

CI Pipeline

Single workflow .github/workflows/ci.yml, path-filtered:

Job Trigger Steps
Rust runner/**, proto/** fmt → clippy → test → build release
Security runner/** cargo audit
Swift MacApp/**, proto/** SwiftLint → build → test
Proto proto/** buf lint → buf breaking (PRs only)
Docker Dockerfiles, compose build (no push, GHA cache)

Branch protection requires the CI summary job to pass. All changes go through PRs.

Compiler Settings

Rust

  • unsafe_code = "deny" — no unsafe blocks allowed
  • clippy::pedantic warnings enabled
  • clippy::dbg_macro = "deny" — no debug prints

Swift

  • SWIFT_STRICT_CONCURRENCY = complete — full Sendable/actor isolation
  • SWIFT_TREAT_WARNINGS_AS_ERRORS = YES — zero-warning policy
  • swiftLanguageMode(.v6) on all SPM targets
  • ExistentialAny upcoming feature enabled