Conta Command

A command is a named, typed operation that changes data. Every command is traced, persisted, and queryable.

Action-oriented APIs

Commands replace anonymous request bodies with named, typed operations. A CreateInvoiceCommand carries the intent that a POST /invoices leaves implicit, and the operation is traceable end to end. See action-oriented APIs for the full rationale.

Terminology

Command: A named object representing a state-changing operation. Every command has a class name, a UUID, and an optional source reference. Defined in the command model.
Command log: The database table where every command execution is recorded — who triggered it, what happened, how long it took, and whether it succeeded or failed. Described in the schema reference.
Command state: The outcome of a command: Successful, Rejected, Failed, Cancelled, or Conflict. Derived from HTTP status codes and problem responses.
Command tracing: The framework that automatically captures commands as they execute — through HTTP endpoints, background jobs, or any other execution path. Powered by the interceptor and filter.
Command importance: A classification (Low, Normal, High) that signals how significant a command is. Paired with retention to control how long entries are kept.
Command retention: Derived from importance: ShortLived, LongLived, or Permanent. Used by cleanup jobs to decide which command log entries to keep and which to purge.

Why commands

Every execution is recorded with its outcome, problem code, and duration. A single table powers debugging, monitoring, failure analysis, and cross-tenant insights.

Adoption tiers

The library is layered. Each tier builds on the previous, and you can stop at any tier — what you adopt should match what you need.

Define commands: Module: conta-command-api. Typed, named operations as a stable contract between client and server. You get action-oriented APIs with no runtime cost — no tracing, no persistence, no migrations.
Trace: Module: conta-command-tracing-mn. @CommandTracing captures every execution — UUIDs, durations, outcomes, problem codes — and exposes them via lifecycle hooks for MDC, OpenTelemetry, or custom metrics.
Persist: Implement a CommandTracingEventPublisher to write traced commands to your own command_log table. The conta-command-postgresql module ships ready-made migrations for that table — durable history, queryable by SQL. Wiring guide.
Query: Module: conta-command-query-mn. A query API for searching the log by tenant, class, state, time, importance, and JSONB attributes.

The minimum useful adoption is the first tier: define commands and get the contract. Adopt the rest when you need central debugging, audit trails, or cross-tenant insights.

Command model

A sealed Command interface with three permitted subtypes: TenantCommand, UserCommand, and GlobalCommand. Mix in DryRunEnabled, AttributesEnabled, or UserIdAware as needed — composition over inheritance.

Command tracing

Add @CommandTracing to a controller or service. The interceptor captures the command, the filter captures the response, and your CommandTracingEventPublisher persists the result. Works for HTTP endpoints and background jobs alike.

Command lifecycle hooks

Plug into onCommandStarted, onCommandCompleted, and onCommandFailed for MDC correlation, OpenTelemetry spans, or custom metrics.

Command persistence

The library traces commands — you provide the storage. Entity, publisher, event listener, repository: a complete guide to wiring up the command persistence chain.

Command reference

Command states, importance, retention, sensitive data handling, and problem+json integration.

Command log schema

The command_log table — every column explained.

Command query API

Search stored commands by tenant, class, state, time range, importance, and JSONB attributes.

Command log queries

SQL patterns and helper functions for interactive querying of the command log.

Roadmap

What’s coming next: command activity journal, command replay, tenant-scoped command logs, and retention cleanup.

Related projects

conta-gradle-plugins: Shared Gradle plugins for Conta projects. Includes the archive-extract plugin used to install and rename migrations from library dependencies into your project.
conta-problem-json: Structured error responses following the problem+json standard (RFC 9457). When a command fails, the problem code and full problem body are captured in the command log — enabling failure analysis and error categorization across the platform.
fork-yeah: Year-over-year forking of domain objects. When a fork command creates copies of entities for the next period, each forked object carries a reference back to its source — and the fork command itself is traced via conta-command.