Skip to content

README.md

Latest commit

 

History

History
278 lines (212 loc) · 8.26 KB

README.md

File metadata and controls

278 lines (212 loc) · 8.26 KB
Raw

Abstract illustration of the optional Capa sidecar runtime

Capa Runtime

Cloud Application API · Experimental gRPC Sidecar Runtime

Capa Java · Capa Go (historical)

Go Version License

📖 Introduction

Capa Runtime is an experimental sidecar implementation for the Capa (Cloud Application API) ecosystem. The current executable provides a small gRPC runtime baseline for metadata, lifecycle, and API-contract development. It can run alongside a Capa SDK, but it is not required to use the SDK.

Project status: This repository provides a buildable experimental gRPC runtime baseline. Runtime startup, metadata RPCs, and graceful shutdown are tested; actor methods return gRPC UNIMPLEMENTED while they remain scaffolding. HTTP interception, bindings, and SaaS integrations are roadmap items rather than production-ready features.

Ecosystem Roles

Component Description Current Use
Capa SDK Language-native Cloud Application APIs Application integration
Capa Runtime Optional gRPC sidecar Metadata, lifecycle, and future extended APIs

🏗️ Architecture

flowchart LR
    App[Application] -->|language API| SDK[Capa SDK]
    App -->|optional gRPC| Runtime[Capa Runtime]
    Runtime --> Metadata[In-memory metadata]
    Runtime --> Lifecycle[Startup and shutdown lifecycle]
    Runtime -. unimplemented RPCs .-> Actors[Actor contract scaffolding]
Loading

The dashed edge marks contract scaffolding, not a production actor runtime.

Architecture Layers

capa/
├── cmd/capa/               # Runtime entry point
├── pkg/                    # Core packages
│   ├── actors/             # Actor API scaffolding
│   ├── grpc/               # gRPC API and server lifecycle
│   ├── proto/              # Generated Runtime API types
│   └── runtime/            # Core runtime lifecycle
├── docker/                 # Docker configurations
├── spec/                   # Runtime API specification
└── utils/                  # Utility functions

Key Design Principles:

  • Optional Sidecar: Capa Runtime is optional; SDK works independently
  • Small Runtime Surface: Only implemented packages participate in builds
  • Explicit Lifecycle: Startup failures propagate and shutdown is bounded
  • Extensible API: Generated gRPC contracts provide the integration boundary

✨ Features

Capability Status Notes
gRPC runtime server ✅ Baseline Starts on configured addresses and registers the Runtime API
Metadata API ✅ Implemented Stores and retrieves runtime metadata in memory
Graceful shutdown ✅ Implemented Stops on signals or the Shutdown RPC with a bounded timeout
Actor API 🔬 Scaffolding RPC contracts return gRPC UNIMPLEMENTED; persistence and execution are not implemented
HTTP interception 🗺️ Roadmap Not included in the current runtime
Bindings and SaaS 🗺️ Roadmap Not included in the current runtime

🎯 Motivation

Why Sidecar?

The sidecar is intended for capabilities whose lifecycle or network boundary should remain outside the application process. The following are design motivations, not claims about the current implementation:

  1. Actor Model: May require persistent connections and scheduling
  2. Traffic Interception: Would require network-level control
  3. Binding: Can benefit from decoupled event processing

Sidecar or SDK?

Capability SDK Runtime Notes
Cloud APIs ✅ — Use the language SDK directly
Metadata — ✅ Implemented by the gRPC runtime
Lifecycle shutdown — ✅ Signal and RPC initiated
Actor ❌ 🔬 Contract only; implementation is incomplete
Binding ✅ 🗺️ Runtime support is a roadmap item
Traffic interception ❌ 🗺️ Not included in the current runtime

🚀 Getting Started

Prerequisites

  • Go 1.25 or higher with automatic toolchain selection enabled; this repository selects Go 1.26.5 for patched builds
  • Docker (optional, for containerized deployment)
  • Kubernetes (optional, for orchestrated deployment)

Installation

# Clone the repository
git clone https://github.com/capa-cloud/capa.git
cd capa

# Verify and build the runtime
go test ./...
go build -o capa ./cmd/capa

# Run locally
./capa --app-id example --port 3500

Docker Deployment

# Build Docker image from the repository root
docker build -f docker/Dockerfile -t capa-runtime:latest .

# Run container
docker run -d \
  --name capa-runtime \
  -p 3500:3500 \
  capa-runtime:latest

Kubernetes Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: capa-runtime
spec:
  replicas: 1
  selector:
    matchLabels:
      app: capa-runtime
  template:
    metadata:
      labels:
        app: capa-runtime
    spec:
      containers:
      - name: capa-runtime
        image: capa-runtime:latest
        args: ["--listen-address=0.0.0.0", "--port=3500"]
        ports:
        - containerPort: 3500
---
apiVersion: v1
kind: Service
metadata:
  name: capa-runtime
spec:
  selector:
    app: capa-runtime
  ports:
  - port: 3500
    targetPort: 3500

⚙️ Configuration

The runtime is configured with command-line flags:

Flag Default Description
--app-id capa-app Application identifier
--env local Application environment
--cloud local Cloud provider identifier
--listen-address 127.0.0.1 gRPC API listen address
--port 3500 gRPC API port
--callback-port 3501 Application callback port reserved for actor integration
--shutdown-timeout 10s Maximum graceful shutdown duration

📚 Runtime API

The gRPC contract is defined in spec/proto/runtime/v1/runtime.proto. The current executable registers the generated Runtime service and implements metadata and shutdown behavior. Actor RPCs are present for compatibility but return gRPC UNIMPLEMENTED until an actor runtime is available. The Shutdown RPC also completes the process lifecycle; no additional operating-system signal is required.

🌐 Ecosystem

Capa Runtime is part of the Capa Cloud ecosystem:

Project Language Description
capa-java Java Java SDK implementation
capa-go Go Historical SDK reference; check its repository status before reuse
cloud-runtimes-jvm Java JVM API specification
cloud-runtimes-golang Go Go API specification

🤝 Contributing

We welcome contributions to Capa Runtime!

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Development Setup

# Clone and build
git clone https://github.com/capa-cloud/capa.git
cd capa

# Download dependencies
go mod download

# Run tests
go test ./...

# Vet and build the binary
go vet ./...
go build -o capa ./cmd/capa

📜 License

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

Developing a small, explicit runtime boundary for Cloud Application APIs

Capa Cloud · Documentation