ores.service

ores.service is the shared infrastructure every ORE Studio NATS backend service is built on. It owns no domain type and no wire type of its own. What it owns is the envelope around them: the service lifecycle that fetches the JWKS key with backoff, builds a JWT verifier, registers the handlers and drains on shutdown; the host envelope that parses the arguments, starts the logging lifecycle and runs the application; the per-request database context built from the validated JWT; and the handler helpers that stamp server-authoritative fields, check permissions, reply and decode.

The component is model-free. It carries no entity, junction or operation model, so no C++ or SQL is generated from it and it appears in no shell output. Every source file is hand-written. The only generated artefacts it owns are its two component_files.cmake source lists, which codegen renders from a directory scan and which carry the generated marker.

The two runners are the reason the component exists. Before them, each service carried its own copy of the same fifty-line host body and the same startup sequence, and two of them had silently drifted from the canonical shape. A service now writes only its own registration call and its own domain logic. Every .service binary and the tools that share the host envelope (ores.shell, ores.http.server, ores.compute.wrapper) are callers.

The component is protocol-adjacent rather than protocol-owning. It reads the workflow step command headers that ores.workflow declares, and it publishes the workflow and telemetry messages those components model, but it declares no subject and produces no protocol header of its own.

• config/ — standard_service_options, the one place a domain service builds and parses the shared common/logging/database/NATS option set, and standard_options, the struct it reads them into. Its make_options_description() also registers the NATS shared config domain. The two tools that build their own parsers instead of using this class, ores.http.server and ores.compute.wrapper, call register_shared_domain() themselves, so this is the main call site rather than the only one.
• messaging/ — the handler surface. handler_helpers.hpp holds stamp, has_permission, reply, error_reply, decode and log_handler_entry; workflow_helpers.hpp holds the workflow step context, the step idempotency check and the step-completion publishers.
• service/ — the lifecycle itself: run for a database-backed service, run_signing for a service that mints its own tokens, run_host_async and run_host_sync for the process envelope, make_request_context for the JWT-to-context step, heartbeat_publisher for liveness, notify_systemd_ready for the readiness notification, and exit_code for the process exit contract.

• A connected NATS client and a database context per service.
• The JWKS public key fetched from IAM, or the service's own RSA private key for the signing lifecycle.
• Inbound NATS messages: their subject, headers and payload bytes.
• The process environment: NOTIFY_SOCKET for the readiness notification, and the option environment variables the parser reads.
• Command-line arguments and the parsed options of the calling tool.

• A registered, ready and gracefully draining NATS service, with the subscription count logged.
• A per-request ores::database::context scoped to the JWT's tenant, party and roles.
• A READY=1 notification to systemd where NOTIFY_SOCKET is set.
• Heartbeat messages on the telemetry service's subject.
• Step-completion events on the workflow engine's subject.
• A process exit status drawn from exit_code.

• include/ores.service/service/domain_service_runner.hpp — run, the database-backed service lifecycle.
• include/ores.service/service/service_lifecycle.hpp — the pieces that lifecycle is built from: add_shutdown_signals, arm_startup_cancellation, fetch_public_key_or_shutdown and announce_ready_and_drain.
• include/ores.service/service/signing_service_runner.hpp — run_signing, the IAM variant that signs rather than verifies.
• include/ores.service/service/host_runner.hpp — run_host_async, run_host_sync and host_runner_options.
• include/ores.service/service/request_context.hpp — make_request_context.
• include/ores.service/service/heartbeat_publisher.hpp — the liveness publisher.
• include/ores.service/service/systemd_notify.hpp — notify_systemd_ready.
• include/ores.service/service/exit_codes.hpp — exit_code.
• include/ores.service/error_code.hpp — error_code, the reply error the request context and the handler helpers answer with.
• include/ores.service/config/standard_service_options.hpp — the shared option set.
• include/ores.service/messaging/handler_helpers.hpp — the handler helpers.
• include/ores.service/messaging/workflow_helpers.hpp — the workflow step helpers.
• include/ores.service/ores.service.hpp — the namespace documentation header.

• ores.nats — the client, the wire codec, the message type, the JWKS fetch and the standard header names.
• ores.security — JWT verification and signing.
• ores.database — the per-request context type.
• ores.workflow.api — the step-completion event, the step query protocol and the header names its step commands carry.
• ores.telemetry.core — the logging lifecycle manager the host envelope starts.
• ores.platform — the shutdown-signal set and the environment access the readiness notification reads.
• ores.logging — the logger every helper in the component writes to.
• ores.utility — tenant ids, the program-options helpers and the streaming operators the host envelope logs with.

• Component Architecture Audit – the structural checklist this component was worked through.
• Component Clean Standard – the item-by-item standard this component now meets.
• NATS entity protocol specification – the protocol this component's helpers serve and the headers it reads.
• ores.nats – the transport, the wire codec and the JWKS fetch.
• ores.security – JWT verification and signing.
• ores.database – the request context this component builds.
• ores.workflow.api – the step protocol whose headers and events the helpers use.
• PlantUML class diagram conventions – the rules the component diagram follows.
• Unit test conventions – the Catch2 conventions the component's tests follow.
• Code Review Checklist – the naming and component-only checks this component passes.

target_link_libraries(${lib_target_name}
    PUBLIC
        ores.nats.lib
        ores.security.lib
        ores.database.lib
        ores.utility.lib
        ores.workflow.api.lib
        Boost::boost
    PRIVATE
        ores.logging.lib)

target_link_libraries(${tests_target_name}
    PRIVATE
        ${lib_target_name}
        ores.utility.lib
        ores.testing.lib
        ores.logging.lib
        Catch2::Catch2
        faker-cxx::faker-cxx
        Threads::Threads)