Glossary

Quick reference for technical terms, concepts, and jargon used in acton-service documentation.

Framework & Architecture

acton-service

A production-grade Rust microservice framework built on Axum that provides batteries-included features with enforced best practices. See What is acton-service? for full introduction.

Axum

The underlying web framework that acton-service is built on. Axum provides the HTTP routing, extractors, and middleware system. When you see Router, get(), post(), or handler functions, these come from Axum.

Middleware

Code that runs before and/or after your request handlers to provide cross-cutting functionality like authentication, logging, rate limiting, or compression. In acton-service, middleware is applied automatically via ServiceBuilder or explicitly via Router::layer().

Opaque Type

A Rust pattern where the actual type is hidden from the caller. In acton-service's API versioning, VersionedRoutes is an opaque type - you can't inspect or modify it directly, which prevents bypassing version enforcement. The compiler knows the type but doesn't let you access its internals.

Tower

The middleware ecosystem that Axum and acton-service build on. Provides composable layers for adding functionality to services. You'll see Layer and Service traits from Tower throughout the stack.

Tokio

The async runtime that powers acton-service. Handles task scheduling, async I/O, and provides utilities like timers and channels. Required for all async Rust web services.

Protocols & Communication

gRPC

A high-performance RPC (Remote Procedure Call) framework using HTTP/2 and Protocol Buffers. Provides type-safe APIs with bidirectional streaming. acton-service supports running gRPC and HTTP on the same port.

HTTP/2

The second major version of HTTP, supporting multiplexing (multiple requests over one connection), server push, and header compression. Required for gRPC. acton-service automatically negotiates HTTP/1.1 or HTTP/2.

Protocol Buffers (protobuf)

A language-neutral data serialization format from Google. More compact and faster than JSON. Used by gRPC for defining service interfaces and message types in .proto files.

Protocol Detection

acton-service's ability to automatically identify whether an incoming request is HTTP/1.1, HTTP/2, or gRPC and route it appropriately - all on the same port. No configuration needed.

Request/Reply Pattern

A messaging pattern where a client sends a request and waits for a response. Used in NATS for synchronous-style communication over an async message bus.

Pub/Sub Pattern

Publish/Subscribe pattern where publishers send messages to topics and subscribers receive copies of all messages on topics they're subscribed to. Decouples senders from receivers.

Observability & Monitoring

Observability

The ability to understand your system's internal state by examining its outputs (logs, metrics, traces). The three pillars are logging, metrics, and distributed tracing.

OpenTelemetry (OTel)

An open standard for observability that provides vendor-neutral APIs and instrumentation. acton-service uses OTel for automatic tracing, metrics, and context propagation.

OTLP

OpenTelemetry Protocol - the wire protocol for sending telemetry data (traces, metrics, logs) from your service to collectors/backends like Jaeger or Prometheus.

Span

A single unit of work in distributed tracing, representing an operation with a start time, end time, and metadata. Multiple spans form a trace showing a request's path through your system.

Trace

A complete picture of a request's journey through your distributed system, composed of multiple spans across different services. Each trace has a unique trace ID.

Correlation ID

A unique identifier propagated through your request chain to correlate logs, metrics, and traces for a single logical operation. acton-service automatically generates and propagates these.

Request ID

A unique identifier for a single HTTP request, automatically generated by acton-service and added to response headers (x-request-id). Useful for debugging and log correlation.

Trace ID

The unique identifier for an entire distributed trace. Propagated across service boundaries to connect spans from different services into a single trace.

Structured Logging

Logging with machine-readable format (JSON) instead of plain text. Each log entry has fields like timestamp, level, message, trace_id that can be queried and analyzed.

Metrics

Numerical measurements of your system over time (request count, latency, error rate). acton-service automatically collects HTTP metrics via OpenTelemetry.

Histogram

A metric type that samples observations and counts them in configurable buckets. Used for measuring latency distributions (p50, p95, p99 percentiles).

Percentile

A measure indicating the value below which a given percentage of observations fall. p99 latency means 99% of requests were faster than this value.

Resilience & Reliability

Circuit Breaker

A resilience pattern that prevents cascading failures by detecting unhealthy dependencies and failing fast. Has three states: Closed (normal), Open (failing fast), Half-Open (testing recovery). State transitions happen automatically at runtime based on failure rates.

Bulkhead

A resilience pattern (named after ship compartments) that limits concurrent requests to prevent one slow operation from exhausting thread pools and blocking all other requests.

Retry Logic

Automatic retry of failed requests with exponential backoff. Handles transient errors like network timeouts. Must only be used with idempotent operations.

Exponential Backoff

A retry strategy where wait time doubles after each failure (100ms, 200ms, 400ms, 800ms). Prevents overwhelming a failing service. Often includes jitter (randomization).

Idempotent

An operation that produces the same result whether executed once or multiple times. GET, PUT, DELETE are idempotent. POST is not (creates duplicates). Required for safe retries.

Cascading Failure

When failure in one service causes failures in dependent services, which cascade through your system. Circuit breakers prevent this by failing fast instead of overwhelming failing dependencies.

Health Check

An endpoint (/health) that reports if your service is alive. Kubernetes uses this for liveness probes to know when to restart pods.

Readiness Check

An endpoint (/ready) that reports if your service is ready to handle traffic. Different from health - a service can be alive but not ready (e.g., warming up cache, waiting for database).

Authentication & Authorization

JWT (JSON Web Token)

A compact, URL-safe token format for transmitting claims between parties. Commonly used for authentication. Contains header, payload (claims), and signature. Can be verified without calling auth service.

Claims

Data embedded in a JWT token like user ID (sub), client ID, roles, permissions. Extracted automatically by acton-service and made available in request context.

Bearer Token

An authentication scheme where the token itself grants access. Sent in Authorization: Bearer <token> header. Holder of the token is authorized.

Cedar

AWS's open-source authorization language and policy engine. Provides fine-grained access control with principals, resources, actions, and context. More expressive than role-based access.

RBAC (Role-Based Access Control)

Authorization model where permissions are assigned to roles, and users are assigned roles. Simpler than attribute-based but less flexible.

ABAC (Attribute-Based Access Control)

Authorization model that uses attributes of users, resources, and environment to make access decisions. More flexible than RBAC. Cedar implements ABAC.

Principal

In authorization systems, the entity requesting access (user, service, device). Cedar requires defining principals in policies.

Resource

In authorization systems, the thing being accessed (document, API endpoint, database record). Cedar policies specify which principals can access which resources.

Action

In authorization systems, the operation being performed (read, write, delete). Combined with principal and resource to make authorization decisions.

Fail-Open vs Fail-Closed

Security policy for handling errors during authorization checks. Fail-open allows access on error (permissive). Fail-closed denies access on error (strict, more secure).

Data Storage & Caching

Connection Pool

A cache of database connections that can be reused rather than creating new connections for each request. Improves performance and limits database load. Managed automatically by acton-service.

SQLx

A Rust SQL library with compile-time query verification. Checks your SQL queries against your database schema during compilation, catching errors before runtime.

Compile-time Verification

SQLx feature that validates SQL queries during cargo build by connecting to a development database. Requires DATABASE_URL environment variable. Use offline mode for CI/CD.

Migration

A version-controlled change to your database schema (add table, add column, etc.). SQLx supports migration files that can be applied automatically on service startup.

Cache-Aside Pattern

A caching strategy where application code explicitly manages the cache: check cache, if miss then fetch from database and populate cache. Used in acton-service's Redis integration.

TTL (Time To Live)

How long cached data remains valid before expiring. After TTL expires, cache entry is deleted and must be refetched from source.

Deadpool

A connection pooling library for Rust. acton-service uses it for managing database and Redis connection pools.

Message & Event Systems

NATS

A high-performance messaging system for cloud-native applications. Supports pub/sub, request/reply, and streaming (JetStream). Used by acton-service for event-driven architectures.

JetStream

NATS's persistence layer providing streams (message storage) and consumers (message processing) with guaranteed delivery. More robust than core NATS for critical messages.

Subject

NATS terminology for a message topic. Supports hierarchical naming (e.g., orders.created.uk) and wildcards (orders.*).

Stream

In NATS JetStream, a message store that captures and persists messages on specific subjects. Configurable retention policies (time, size, work queue).

Consumer

In NATS JetStream, a way to consume messages from a stream with configurable acknowledgment and replay policies.

Durable Consumer

A NATS consumer that remembers its position in the stream even if it disconnects. Allows resuming from the same point after restart.

Acknowledgment

Confirming that a message has been successfully processed. Required for NATS JetStream to know it can delete or redeliver messages.

Configuration & Deployment

XDG Base Directory Specification

A standard for organizing user-specific configuration files. acton-service uses ~/.config/acton-service/{service_name}/config.toml following this standard.

Environment Variable

Configuration value set in the shell environment. acton-service reads ACTON_* prefixed variables. Higher precedence than config files.

Configuration Precedence

The order in which config sources override each other. In acton-service: Environment variables (highest) → current dir config.toml → XDG config → system config → defaults (lowest).

Hot-Reload

Updating configuration without restarting the service. Limited support in acton-service (e.g., Cedar policies with hot_reload: true). Most config requires restart.

Lazy Initialization

Deferring connection establishment until first use. For databases/redis/nats, initialization happens in background during startup rather than blocking service start.

Optional Dependency

A database/redis/nats connection marked as optional: true in config. Service starts successfully even if connection fails, but requests using it will error.

Degraded State

Service status when optional dependencies are unavailable. Service is alive but not fully functional. Reflected in /ready endpoint.

Kubernetes & Container Orchestration

Liveness Probe

Kubernetes check to determine if a container is alive. Maps to acton-service's /health endpoint. Restart pod if failing.

Readiness Probe

Kubernetes check to determine if a container is ready to serve traffic. Maps to acton-service's /ready endpoint. Remove from load balancer if failing.

ConfigMap

Kubernetes resource for storing non-sensitive configuration as key-value pairs. Mounted as files or environment variables in pods.

Secret

Kubernetes resource for storing sensitive configuration (passwords, API keys). Encrypted at rest. Mounted as files or environment variables.

Ingress

Kubernetes resource for HTTP/HTTPS routing from outside the cluster to services inside. Provides load balancing and SSL termination.

Service (Kubernetes)

Kubernetes resource that provides stable networking endpoint for a set of pods. Types: ClusterIP (internal), LoadBalancer (external), NodePort.

HPA (Horizontal Pod Autoscaler)

Kubernetes resource that automatically scales the number of pod replicas based on CPU, memory, or custom metrics.

PDB (Pod Disruption Budget)

Kubernetes resource that limits how many pods can be unavailable during voluntary disruptions (upgrades, node drains) to maintain availability.

ServiceMonitor

Custom resource used by Prometheus Operator to discover and scrape metrics from services. Automatically configures Prometheus to collect acton-service metrics.

Rust & Compile-time Guarantees

Cargo Feature

Conditional compilation flags in Rust. acton-service uses features to make dependencies optional (e.g., database, cache, events). Enable with features = ["database"] in Cargo.toml.

GATs (Generic Associated Types)

An advanced Rust feature enabling more expressive type system patterns. Required by some acton-service dependencies. Requires Rust 1.65+.

RAII (Resource Acquisition Is Initialization)

A Rust pattern where resources (connections, files) are automatically cleaned up when they go out of scope. Prevents connection leaks.

Extractor Pattern

Axum pattern for extracting data from requests (path params, query, body, headers, state). Functions like State(state): State<AppState> use this pattern.

Prelude

A module that re-exports commonly used types. use acton_service::prelude::*; imports most types you'll need, reducing boilerplate.

API Design & Versioning

API Versioning

Maintaining multiple versions of your API simultaneously so clients can upgrade on their own timeline. acton-service enforces versioning via types.

Type-Enforced Versioning

acton-service's approach where unversioned routes won't compile. The type system (via VersionedRoutes opaque type) prevents accidentally creating unversioned endpoints.

RFC 8594

IETF standard "The Sunset HTTP Header Field" - a header indicating when an API version will be deprecated. acton-service automatically adds this.

Deprecation Header

HTTP header (Sunset, Deprecation, Link) informing clients that an API version will be removed. acton-service adds these automatically when configured.

Breaking Change

An API modification that breaks existing clients (removed field, changed type, new required parameter). Requires new API version.

Miscellaneous

CORS (Cross-Origin Resource Sharing)

Browser security feature that restricts web pages from making requests to different domains. acton-service provides middleware to configure allowed origins.

Service Mesh

Infrastructure layer (like Istio, Linkerd) that handles service-to-service communication, security, and observability without changing application code.

Load Balancer

Distributes traffic across multiple instances of a service. Can be software (nginx, HAProxy) or cloud provider service (AWS ALB, GCP Load Balancer).

Multi-Stage Build

Docker technique using multiple FROM statements to create lean production images. Build stage has compilers, final stage only has binaries.

Content Negotiation

HTTP feature where client and server agree on response format (JSON vs XML) via Accept headers. acton-service handles this automatically.

Next Steps

• Core Concepts - Deeper explanations of fundamental patterns
• API Versioning - Type-enforced versioning in detail
• Resilience Patterns - Circuit breakers, retries, bulkheads
• Observability - Tracing, metrics, logging setup