Dapr Building Blocks
The optional sidecar runtime behind Redis, Pub/Sub & more
Dapr is the runtime adapter layer Nucleus can sit on instead of talking to infrastructure directly. When you flag withDapr on Redis (or wire a Dapr pub/sub component), the framework routes through a Dapr sidecar and gains its full set of portable building blocks — state, pub/sub, service invocation, secrets, bindings, distributed locks, cryptography, configuration and workflows — without binding your code to a specific vendor.
Internally this is the DaprConnectionManager (exported as the daprService singleton). It manages one connection to the sidecar and exposes a typed method for every building block. It is entirely opt-in: with Dapr off, Nucleus connects to Postgres and Redis directly and none of this is in the path. This page documents the layer explicitly so nothing about how Nucleus reaches infrastructure is a black box.
Connection & the sidecar#
Dapr runs as a sidecar next to your app. The manager connects to it over HTTP (default) or gRPC, lazily and once, and reuses that client for every call.
host / port / endpointenv: DAPR_HOST, DAPR_HTTP_PORT, …OptionalDefaults to 127.0.0.1:3500. Reads DAPR_HOST / DAPR_HTTP_PORT, or a full DAPR_HTTP_ENDPOINT / DAPR_GRPC_ENDPOINT when the sidecar is elsewhere. An optional DAPR_API_TOKEN authenticates app→sidecar calls.
lazy connect + statusDISCONNECTED → CONNECTING → CONNECTEDOptionalgetClient() auto-connects on first use and reuses the client thereafter. A single-flight connection promise prevents thundering-herd reconnects, and every connect is bounded by a timeout so a missing sidecar fails fast instead of hanging.
health checkshealthCheck() / testConnection()OptionalhealthCheck() pings the sidecar's healthz endpoint (and reports the dapr-version); testConnection() runs a real round-trip across state, health and config so you can verify the wiring, not just the socket.
State & configuration#
The state store is the building block Redis uses in Dapr mode — a portable key/value API with bulk, query and transactional operations.
stateaddState / getState / deleteStateOptionalSave, read and delete keys against a state store (default statestore-redis). getBulkState reads many keys at once, queryStates runs filter/sort/page queries, and stateTransaction commits multiple operations atomically.
configurationgetConfig(keys, store)OptionalReads dynamic configuration values from a Dapr config store (default configstore) — useful for runtime flags that live outside your config.nucleus.json.
Service invocation & bindings#
Reach other services and external systems through the sidecar, with discovery, retries and mTLS handled for you.
service invocationinvokeService(appId, method, httpMethod, data)OptionalCall another Dapr app by its appId — the same appId primitive each Nucleus service declares — without knowing its address. The mesh resolves it, securing the hop with mTLS.
output bindingsinvokeBinding(name, operation, data)OptionalTrigger an external resource (queues, blob stores, SMTP, cron, cloud services) through a configured binding component, keeping vendor SDKs out of your code.
Secrets & cryptography#
Pull secrets from a managed store and perform envelope encryption without holding key material in the app.
secretsgetSecret(store, key) / getBulkSecrets(store)OptionalFetch one secret or the whole store from a secret-store component (Vault, cloud secret managers, K8s secrets) — so credentials never live in the image or config file.
cryptographyencrypt / decrypt(component, keyName, bytes)OptionalEnvelope encryption against a crypto component: the key stays in the provider, the app only sends/receives bytes. Useful for field-level encryption beyond the database layer.
Distributed locks & workflows#
Coordinate across replicas and run durable, long-lived processes.
distributed lockstryLock / unlock(store, resourceId, owner, ttl)OptionalAcquire a named lock with an owner and an expiry so only one replica runs a critical section (a backup, a migration, a scheduled job). tryLock returns { success } rather than throwing, so callers branch cleanly.
workflowsstart / get / terminate / pause / resume / raise / purgeOptionalDrive Dapr's durable workflow engine: start an instance, query it, pause/resume, raise external events into it, terminate or purge it — for orchestrations that must survive restarts.
Related sections