Skip to content

API reference

Generated from the docstrings in chaski's source.

Service

Service(name: str, mount: str = '', *, node: Any = None, display_name: str | None = None, description: str | None = None, version: str | None = None, logs: bool = True, state_dir: Path | None = None, mqtt_port: int | None = None, api_port: int | None = None, metadata: dict[str, Any] | None = None, architecture_metadata: dict[str, Any] | None = None, health_metrics: Iterable[HealthMetricDeclaration] | None = None, max_queued_messages: int = 0, commands: Iterable[tuple[str, str]] | None = None, telemetry: ServiceTelemetry | None = None, service_type: ServiceType | str = ServiceType.CONNECTOR)

A publisher on either the local or the external door — one implementation, one constructor. See the module docstring for the lifecycle.

node says who this Service is to Colca: None (default, inside a deployment), a node= URL string (outside one — the identity is loaded or minted under state_dir), or a :class:LocalDoor (an embedded node's own local door — internal, chaski.Node.service() only).

mqtt_port/api_port are for a node whose published doors sit behind a non-standard port (a test harness, a port-mapped deployment).

metadata and architecture_metadata ride the retained _ServiceDetails record as given: what an editor shows about this service beyond its health — protocol, icon, the driver behind it. architecture_metadata is merged under the live status/detail :meth:status writes.

health_metrics names the Prometheus metrics that describe this service's health (_ServiceDetails.health_metrics); a container passes colca_data_contracts.container_resource_health_metrics().

commands are the (contract, node-local path) pairs this service executes, announced in _ServiceDetails.commands so the node can answer a command nobody executes with a 404 _Ack. A path may use + for one segment and a trailing #. A :class:~chaski.dataops.DataOpsService announces its @on_command handlers itself. See :meth:announce_commands.

service_type is the _ServiceDetails.service_type the service registers with. The default stays connector for compatibility; a service that is no connector (a bridge, a simulator, an app backend) says what it is, e.g. ServiceType.OTHER, so the hub does not count it as one.

Construction does not dial the node; it only loads or mints an external identity on disk. See :meth:start.

readiness property

readiness: Readiness

Whether :meth:start reached the node, and the reason while it has not (see :class:chaski.startup.Readiness). A health door reports it from the first moment, before the node answers. Once ready, the live broker link is :meth:is_broker_connected.

identity_conflict property

identity_conflict: str

Why another process is taken to run as this service, "" while no session takeover happened in the last IDENTITY_CONFLICT_HOLD_S.

cursor_lag property

cursor_lag: str

The summary of the node's cursor_lag finding about this service, "" while there is none.

The node (colca 0.19+) watches every cursor: when a record this service reads has waited unread longer than the node's threshold, it writes the finding next to the service's own record, and retires it once the cursor caught up. Consumers read when woken, so this is how a lost wake or a stuck loop shows; a health check fails on it.

cursor_lag_cursors property

cursor_lag_cursors: tuple[str, ...]

The cursors the standing cursor_lag finding names (its detail.cursors), () while none stands or the node names none.

node_id property

node_id: str | None

The node this service is registered at — level 4 of every topic it writes. None before :meth:start.

service_id property

service_id: str | None

This service's identity at the node: the registry ULID minted at self-registration (local) or the pinned one (external) — what the catalogue's connector field carries. None before :meth:start.

mount property

mount: str

Where the node currently has this service (re-resolved on every reconnect for a local service).

cursor_prefix property

cursor_prefix: str

The cursor namespace this identity owns, which :meth:stream prepends: c/{name}/ for a local service, {ulid}/ for an external one. The door refuses cursors outside it.

start

start(*, connect_timeout: float = 10.0) -> Service

Connect, self-register (local) or authenticate (external), publish the initial retained _ServiceDetails, and subscribe to this service's own _Signal records. Idempotent — a second call on an already-started Service is a no-op.

Outside a deployment, a refused CONNECT (the identity is not yet enrolled) raises :class:NotEnrolled — see :meth:wait_enrolled to poll instead of raising once.

One attempt: a node that cannot be reached raises. A long-running service calls :meth:start_when_reachable instead, which retries. :attr:readiness says how the attempt went.

start_when_reachable

start_when_reachable(stop: Event | None = None, *, connect_timeout: float = 10.0) -> bool

:meth:start, retried while the node cannot be reached.

For a long-running service whose node may be down when it starts or come up after it: it never gives up on an unreachable node. Between attempts it waits a jittered backoff of at most :data:~chaski.startup.STARTUP_RETRY_MAX_S seconds, longer when the node answers 429 with Retry-After, and :attr:readiness reports waiting with the reason. Any other failure (a configuration error) is raised at once.

Returns True once started, False if stop was set (or the service closed) first.

start_when_reachable_async async

start_when_reachable_async(stop: Event | None = None, *, connect_timeout: float = 10.0) -> bool

:meth:start_when_reachable off the event loop, stopped by an :class:asyncio.Event; the loop (and a health door on it) keeps answering meanwhile.

is_broker_connected

is_broker_connected() -> bool

Whether the MQTT door is currently reachable — the fact a health endpoint reports. False before :meth:start; afterwards the real socket state, including an outage the caller is buffering against.

enroll_hint

enroll_hint() -> str

The exact one-liner an operator runs to enroll this identity (also the text of a raised :class:NotEnrolled). Outside a deployment only.

wait_enrolled

wait_enrolled(timeout: float = 60.0, *, poll_interval: float = 2.0) -> Service

Retry refused authentication until enrollment or the deadline.

An unenrolled identity cannot subscribe yet. poll_interval is the compatibility name for the minimum retry backoff, not an idle poll.

declare

declare(path: str, *, data_type: str, unit: str | None = None, semantic_type: str | None = None, description: str | None = None) -> None

Announce path in this service's catalogue without a sample.

The catalogue entry is the one :meth:publish makes for path, so the node can bind a Signal to it before the first value: a later publish(path, ...) uses the same tag and keeps data_type. With no sample to infer it from, data_type is stated: a Signal data type such as "string", "float", "int", "boolean" or "json". unit, semantic_type and description are as for :meth:publish.

Before :meth:start the declaration is kept and published with the catalogue at start; after it the catalogue is republished at once. Declaring the same thing again publishes nothing; declaring something different updates the entry. A declared path stays in the catalogue for the run, like a published one.

publish

publish(path: str, value: Any, *, unit: str | None = None, timestamp: Any | None = None, semantic_type: str | None = None, description: str | None = None) -> None

Publish one sample at path.

unit, semantic_type (the name of a semantic tag the node knows, such as availability) and description travel in the path's catalogue entry. The node applies them to the signal it binds and follows later changes: a call naming a different value updates the entry; one naming none keeps what the entry says.

The first call for a never-seen path mints a DataTag and grows the catalogue (republished immediately); every call resolves the Signal the node minted for that tag from this service's own _Signal subscription. Before that Signal exists, the sample is buffered (bounded) and flushed the moment it binds.

send

send(topic: str, payload: str, *, retain: bool = False) -> None

Publish one record at topic on this service's MQTT session, at QoS 1, and wait for the node's PUBACK.

payload is the record as a JSON string. retain for a state record. A record the node refuses raises franzmq.errors.PublishRejected; no PUBACK in time raises PublishTimeout. Must not be called from an MQTT callback, which cannot wait for its own PUBACK. Under :func:writes_until, a write past the deadline or while the link is down raises :class:NotSent.

pipelined

pipelined() -> Iterator[PublishBatch]

Pipeline the writes of the block (:meth:publish, :meth:send, :meth:retract): each is handed to the MQTT client at once, and the block ends when the node confirmed all of them. A refused or unconfirmed write raises there (PublishRejected, PublishTimeout), as it would have from the write. At most :data:~chaski.publishing.PUBLISH_WINDOW writes wait at a time.

retract

retract(topic: str) -> None

Retire the state record at topic: an empty retained payload, which the node keeps as a tombstone and drops from its KV.

send_command

send_command(contract: str, path: str, fields: dict[str, Any] | None = None, *, lifetime: float | None, node: str | None = None, progress: bool = False, operation_id: str | None = None, on_behalf_of: Actor | Mapping[str, Any] | str | None = None) -> SentCommand

Send one command and return once the node accepted it (stored and queued); :meth:SentCommand.wait waits for its outcome. node is the node that executes it, this service's node when None; path is in this node's coordinates, a child's mount included. lifetime is seconds until it expires, or None for a command that never expires and is delivered whenever its node is reachable. See :class:chaski.command.CommandSender, which also describes operation_id (an idempotency key the executor answers repeats of from its record) and on_behalf_of (the person this service acts for; asserted by this service, not attested by the node). Under :func:writes_until the command expires by the deadline at the latest; past it or while the link is down it is not sent and raises :class:NotSent.

command

command(contract: str, path: str, fields: dict[str, Any] | None = None, *, lifetime: float | None, node: str | None = None, timeout: float = 30.0, operation_id: str | None = None, on_behalf_of: Actor | Mapping[str, Any] | str | None = None) -> dict[str, Any]

Send one command and return its outcome, the _Ack as the executor wrote it (result_code, message, and whatever else it carries, such as state_writes). :meth:send_command says what node, path and lifetime mean. Waiting ends after timeout seconds with :class:TimeoutError and leaves the command queued. Under :func:writes_until it is also waited for until the deadline at the latest.

write_signal

write_signal(path: str, value: Any, *, lifetime: float | None, node: str | None = None, progress: bool = False, operation_id: str | None = None, on_behalf_of: Actor | Mapping[str, Any] | str | None = None, params: Mapping[str, Any] | None = None) -> SentCommand

Write value to the signal at path: a _CmdParam at the signal's own position, executed by the connector that holds its binding (:mod:chaski.connector, "Signal writes"). Returns once the node accepted it; .wait(timeout) returns the connector's answer, sent after the value was written and read back: result.outcome is applied (with result.value), failed, unknown, unsupported or refused, and result_code 498 means it expired before it ran. A wait that times out says nothing about the write: it may still happen. Read the signal's current value then. node, path and lifetime are as in :meth:send_command; give a write to a machine a short lifetime.

operation_id makes the write idempotent: send the same id when retrying the same write and the connector answers the repeat from its record ("replayed": true) without writing the source again. on_behalf_of names the person this service writes for; the connector hands both, with the attested sender, to the driver (Driver.write's command) and the _Ack carries them. params are further command fields beside value for a connector that takes them (:meth:chaski.ConnectorService.handle_signal_write).

kv

kv(prefix: str = '', *, contract: str | Iterable[str] | None = None) -> list[KvEntry]

A snapshot of the node's retained state under prefix — every page of GET /kv followed to the end — optionally narrowed to one or more uns contracts (contract="_Signal", contract=["_SystemElement", "_Group"]), which the node filters before decoding any payload. Only entries this identity may read are returned. Requires :meth:start.

watch_streams

watch_streams(*streams)

Subscribe to local durable-stream changes. Closed with this service.

retained_view

retained_view(*, contracts, streams, cursor, scope, on_change=None)

Rebuildable retained view, updated from durable stream notifications.

scope is a :class:chaski.ViewScope naming the paths the view reads: its snapshot, its stream drain and its unread count stay inside them. ViewScope.whole_node() reads every path and has to be asked for.

For a read that must include every record admitted before it, capture view.heads() and call view.wait_caught_up(heads, timeout); view.position(stream) is how far the view applied.

stream

stream(name: str, *, cursor: str | None = None, max: int = 1000, signal_ids: Iterable[str] | None = None, contracts: Iterable[str] | None = None, topics: Iterable[str] | None = None) -> Stream

A named, durable cursor over the node's stream name (metrics, annotations, alarms, ...) — see :class:chaski.door.Stream for the fetch → process → ack contract.

cursor names the cursor within :attr:cursor_prefix and defaults to the stream's name. Pass another name to follow a stream twice or to start fresh (svc.stream("metrics", cursor="ingest-02")), and retire the old one with Stream.retire(). max bounds one page. signal_ids filters the metrics stream at the door; contracts (colca 0.18+) and topics (MQTT filters, colca 0.19+) any stream. Pass what wakes the consumer, so the node counts only those records as unread on its cursor. Requires :meth:start.

pending

pending() -> list[tuple[str, str]]

(path, reason) for every published path with no bound Signal yet — see :func:_pending_reason for what each reason means.

status

status(ok: bool, detail: str = '') -> None

Report runtime health through the deployment's telemetry exporter.

Combined with :attr:handler_health: a service whose handlers are failing reports that too, and is unhealthy once one failed unhealthy_after times in a row, whatever ok says.

reject

reject(consumer: str, subject: dict[str, Any], rejected: Reject) -> None

Record that consumer set an input aside on purpose, durably: the service's rejected_input _Finding, retained, with the node's PUBACK awaited. Runners call this when a handler raises :class:chaski.Reject, and acknowledge the input only after it returned. Every rejection is one more record on the entities stream; the retained record is the latest. :meth:clear_rejections retires it once the inputs were dealt with.

clear_rejections

clear_rejections() -> None

Retire the rejected_input finding.

wake_on

wake_on(topics=()) -> TopicWakeup

A push wake-up on exactly topics, for :meth:consume's bell.

A topic may be an MQTT filter (+, #): the bell rings for every message under it, e.g. colca/v1/_Signal/+/Line/# for a consumer that follows anything added below Line.

A consumer that reads a few signals of a busy node drains a scoped stream (stream(..., signal_ids=...)) and passes wake_on(<their _Metric topics>).bell: it wakes when one of them changes and at no other time. :meth:TopicWakeup.rebind follows a changed set; the subscriptions survive reconnects, and every reconnect rings once.

consume

consume(stream: Stream, handler: Callable[[Record], Any], *, bell: Any = None, stop: Event | None = None, consumer: str | None = None, idle_drain_s: float | None = IDLE_DRAIN_S) -> None

Run handler(record) for every record of stream (from :meth:stream), now and whenever it grows, until stop is set.

A handler that raises is not acknowledged: the cursor moves only past the records before it, the same record is retried with bounded, jittered backoff, and :attr:handler_health reports the consumer degraded, then unhealthy. Raise :class:chaski.Reject to set a record aside instead (see :meth:reject). bell is a :class:chaski.Doorbell rung by the stream's MQTT topics and on reconnect; without one the stream's growth is watched. After idle_drain_s without a ring it drains anyway (unless the newest stream-change hint shows the cursor at the head), so a filtered cursor keeps moving past the records it skips. Blocks.

stream.position says how far the handler got; stream.wait_caught_up(head, timeout) lets another thread wait for a head it captured, for a read that must include that record.

announce_commands

announce_commands(commands: Iterable[tuple[str, str]]) -> None

Announce the (contract, node-local path) commands this service executes, replacing what it announced before, and republish _ServiceDetails when started. Announce before :meth:start where possible: the last will is built at connect and carries what was announced then, so a crashed service keeps its commands.

close

close() -> None

Seal the catalogue (any known path not published this run goes stale), republish _ServiceDetails with is_active=False, and disconnect. Registration and ids stay. Idempotent.

retire

retire(token: str | None = None) -> None

Remove this service for good: publish empty retained _ServiceDetails and _DataTags so the tree forgets it. Outside a deployment it also revokes the enrollment (DELETE /enroll), which needs token. The context manager never calls this.

ConnectorService

ConnectorService(name: str, mount: str = '', *, driver: Driver, interval: float = 1.0, heartbeat_interval: float = 5.0, max_pending: int = 10000, reconnect_retries: int = 5, outage_reminder: float = 300.0, summary_interval: float = 60.0, telemetry: Telemetry | None = None, timestamp_source: Literal['acquisition', 'source'] = 'acquisition', report_by_exception: bool = True, integrity_interval: float = 60.0, read_timeout: float | None = None, **service_kwargs: Any)

Bases: Service

A Service that discovers tags through a :class:Driver and polls them. Construct it like a :class:~chaski.Service (the same node= rule decides the door), then :meth:run it.

interval is the poll cadence in seconds; heartbeat_interval how often the synthetic heartbeat flips; max_pending the bound on metrics kept through a broker outage; reconnect_retries the source reconnect attempts per outage before the loop stays alive and tries again next poll; outage_reminder how many seconds a broker outage may last before it is logged again (the first failure and the recovery are always logged); summary_interval the cadence of the [DATA] throughput line.

Readings are reported by exception: a value equal to the last one published for its Signal (within the Signal's precision) is not sent again. integrity_interval bounds the silence: an unchanged value is republished once that many seconds have passed since it was last sent, so a consumer can tell a steady signal from a dead one. Set report_by_exception=False to publish every reading.

announce_commands

announce_commands(commands: Iterable[tuple[str, str]]) -> None

:meth:chaski.Service.announce_commands, keeping the routes of the bound signals this connector writes.

handle_signal_write async

handle_signal_write(write: SignalWrite) -> CommandResult

Execute one signal write and answer it. The default is :meth:SignalWrite.apply. Override it to check who sent the write, to write a value derived from the command, or to add to the answer's result (module docstring, "Taking over a write"). A repeat of an operation_id never gets here.

run

run(*, health_port: int | None = 8888) -> None

Serve until stopped: :func:run with this service.

health_problem

health_problem() -> str

Why the connector is not healthy, "" while it is: not started yet (Colca not reached, see :attr:readiness), another process running as this connector (:attr:identity_conflict), or the broker link down while samples are journaled.

serve async

serve() -> None

Register, discover, poll. Returns when :meth:stop is called.

A node that cannot be reached yet does not end it: the connector retries with backoff (:meth:~chaski.Service.start_when_reachable) and reports itself not ready meanwhile; the source is not touched before the node answers. A configuration error raises.

refusing

refusing() -> dict[str, RefusalSpell]

The signals whose samples are being refused, keyed by signal id (or topic, for a sample without one).

source_clock_status

source_clock_status() -> SourceClockStatus | None

How far the source's clock is off over the last 15 minutes (:mod:chaski.source_clock); None with timestamp_source="acquisition". Call it from the loop's thread.

Driver

Driver(*, logger: Logger | None = None)

The protocol half of a connector. Subclass it, implement the four async methods, hand an instance to :class:ConnectorService.

connect async

connect() -> None

Open the source. Raise on failure, with a message naming what failed (host, port, endpoint) — the loop logs it and retries.

discover async

discover() -> Discovery

Discover the source's tags. Called after connect (or without it, when catalogue_requires_connection is False).

read async

read(targets: list[Target]) -> Iterable[tuple[Topic, Any, SignalRecord] | Reading]

One poll of targets. A target a driver could not read is simply absent from the result; a lost source raises :class:SourceDisconnectedError.

close async

close() -> None

Release the source. Must tolerate being called on a half-open or already-closed connection.

write async

write(target: Target, value: Any, command: Command) -> None

Write value to the tag target names and return once the source accepted it. The connector reads the tag back through :meth:read before it answers. command is the signal write being executed: who sent it and for whom, its operation_id, its expiry and all its fields (module docstring, "Who wrote it, and once"). Raise :class:SourceDisconnectedError when the source is gone and any other exception when the source refused the write. The default raises :class:WriteUnsupported.

DataOpsService

DataOpsService(name: str, mount: str = '', *, node: Any = None, data_dir: Path | None = None, retention: float | None = None, historian: Historian | None = None, retry_min: float = 1.0, trim_interval: float = 3600.0, buffer_floor: float | None = None, health_port: int = health.PORT_DEFAULT, backfill_rate: float = DEFAULT_RATE, backfill_busy: float = DEFAULT_BUSY, backfill_stall_after: float = DEFAULT_STALL_AFTER_S, **service_kw: Any)

Bases: Service

A :class:chaski.Service that runs :class:~chaski.dataops.Producer classes. Everything the base class does works unchanged (node=, registration, logs, kv(), stream()); this adds the producer runtime described in the module docstring.

::

import chaski
from chaski.dataops import Producer, SignalRangeInput, SignalOutput, every

class Oee(Producer):
    name = "oee"
    system_element_name = "press3"
    speed = SignalRangeInput("speed", window="1h")
    oee = SignalOutput("oee", data_type="float", description="Rolling OEE")

    @every("1m")
    async def tick(self):
        frame = self.speed.fetch(self.watermark, now())
        self.oee.publish(compute_oee(frame))
        self.advance_watermark(now())

svc = chaski.DataOpsService("analytics", mount="site1/line1")
svc.add(Oee)
svc.run()

data_dir holds the buffer (default: the service's own state directory, ~/.colca/services/<name>); retention is the broker's metrics retention in seconds, what a declared window is validated against; historian an optional read-only :class:~chaski.dataops.inputs.Historian -- without one, a :class:~chaski.dataops.NodeHistorian over the node's API when PREKIT_URL, PREKIT_CLIENT_ID and PREKIT_CLIENT_SECRET are set (:meth:NodeHistorian.from_env); retry_min/ trim_interval the failure backoff minimum and buffer-trim cadence; buffer_floor the least history (seconds) the buffer keeps of every input, beyond each input's declared window plus a margin (:func:compute_trim_horizons): what a code-change replay can reach back. Without it, DATAOPS_BUFFER_FLOOR_S, else retention; health_port the health door (0 for an ephemeral port); backfill_rate (windows per second) and backfill_busy (share of wall time) the most a backfill may take, and backfill_stall_after (seconds without a finished window) when the health door reports a running backfill as stalled (:mod:chaski.dataops.backfill). Every other keyword is the base class's.

producers property

producers: list[type[Producer]]

The producer classes this service runs, sorted by name.

door property

door: Door

The door every input resolves through — the base class's own, open after :meth:start. Outputs write with :meth:send.

buffer property

buffer: Buffer

The one local state, open after :meth:start.

accept_gap_path property

accept_gap_path: str

The node-local path of this service's accept-gap command (_CmdMaintain).

add

add(producer_cls: type[Producer]) -> DataOpsService

Run producer_cls. Explicit registration — the counterpart of :meth:discover. A second class with the same name replaces the first (one producer per name, the buffer keys watermarks by it). Returns self for chaining.

discover

discover(package: str) -> int

Import package (and every submodule under it) and run every concrete producer it defines. Returns how many were added.

discover_directory

discover_directory(path: Path) -> int

Import every top-level *.py under path (see :func:import_directory) and run every concrete producer those files define. Returns how many were added.

backfill_holds

backfill_holds(producer: str) -> bool

Whether producer's live triggers are held while its first backfill runs (:mod:chaski.dataops.backfill).

request_backfill

request_backfill(producer: str, start: Any, end: Any, *, window: Any = None) -> str

Run producer again over [start, end) (unix seconds or datetimes), to repair what it emitted there. The job is recorded in the buffer and runs on a separate instance, throttled like every backfill, also after a restart. window ("6h" or seconds) is how much history one step processes; without it, the producer's backfill window, or one hour. Returns the job id. Requires :meth:start; a producer exposes it to the node with its own @on_command handler calling self.runtime.request_backfill(self.name, start, end).

start

start(*, connect_timeout: float = 10.0) -> DataOpsService

The base class's :meth:~chaski.Service.start, then open the buffer. Idempotent. Every @on_command of the added producers is announced (:meth:~chaski.Service.announce_commands) before the service connects, so its last will carries them too.

instantiate

instantiate() -> list[Producer]

Instantiate every added producer and attach it to this runtime — without running setup(); :meth:serve does that. A producer whose constructor raises is skipped with a logged reason.

bind_outputs

bind_outputs(instances: list[Producer]) -> dict[str, str]

Catalogue every declared SignalOutput and bind every AnnotationOutput on instances. Returns the catalogue's {source: tag_id}. Requires :meth:start.

serve async

serve(stop: Event | None = None) -> None

Run the service on the current event loop until stop is set — see the module docstring for the startup order. :meth:run is the blocking wrapper with signal handling.

run

run() -> None

Block: :meth:serve on a fresh event loop until SIGINT/SIGTERM.

Node

Node(name: str, *, parent: str | tuple[str, str] | None = None, data_dir: str | Path | None = None, retention: str | None = None, log_level: str = 'info', binary: str | None = None, contracts_bundle: str | None = None)

An embedded colca node: colcad as a supervised subprocess.

parent is None (root / not yet enrolled), a bare URL (trust-on-first-use), or (url, pubkey) (an explicit pin — see the module docstring). retention is a Go duration string (e.g. "336h") applied to the node's metrics stream retention; None leaves colcad's own default in force.

start

start(*, timeout: float = 30.0) -> Node

Write config, launch colcad, and wait for its local /healthz.

status

status() -> NodeStatus

One of stopped | starting | awaiting_enrollment | enrolled | offline | crashed, from colcad's /healthz and the child process. "offline" means the node was connected before in this process.

wait_enrolled

wait_enrolled(timeout: float = 60.0) -> None

Block until status() is "enrolled", or raise. A TimeoutError carries the current status's detail (the enroll hint, most often); a colcad crash while waiting raises NodeCrashed immediately rather than waiting out the deadline for a process that is never coming back.

enroll_hint

enroll_hint(*, mount: str | None = None, token_env: str = 'COLCA_ADMIN_TOKEN') -> str

The command the parent's operator runs once to enroll this node. The node's API door is loopback-only, so the hint carries the key.

retire_hint

retire_hint(*, token_env: str = 'COLCA_ADMIN_TOKEN') -> str

The one-liner that removes this node from its parent's registry. Deleting the local data directory (this node's identity and its durable streams) is deliberately the integrator's own act, not something this method does.

service

service(name: str, mount: str = '') -> Service

A local Service on this node's own local door.

Stream

Stream(door: Door, name: str, cursor: str, *, max: int = 1000, signal_ids: Iterable[str] | None = None, contracts: Iterable[str] | None = None, topics: Iterable[str] | None = None)

A named cursor over one colca stream, as Service.stream() returns it.

The cursor lives at the door: /fetch reads from its stored position and only /ack moves it. Reopening the same name resumes where it was acked; a new name starts at the stream's first retained record.

Iterating drains the stream, acking page by page. for record in stream: yields records in stream order and acks a page only when the consumer asks for the record after its last one. A consumer that raises or stops mid-page gets that page again next time, so handlers must be idempotent. Iteration stops at the first empty page.

:meth:ack commits before the page boundary if needed. :meth:follow repeats the drain whenever a :class:chaski.Doorbell rings, and after a silent :data:chaski.doorbell.IDLE_DRAIN_S so a filtered cursor keeps moving. A pruned range (Page.gap) raises :class:StreamGapError.

page_size property

page_size: int

The most records one :meth:fetch asks for.

position property

position: int

The last offset this cursor passed, as far as this object knows.

Moves with every :meth:ack (also the page acks of :meth:drain, :meth:follow and Service.consume), and to the head when a drain finds the cursor already there. Every record up to it was handled or skipped by the cursor's filter. 0 until the first ack or drain in this process; no network I/O.

fetch

fetch(*, from_offset: int | None = None) -> Page

One page from the cursor's stored position, or from from_offset when that lies ahead of it. Never moves the cursor.

head

head() -> int

Capture the last admitted offset without moving/changing this cursor.

A drain that must end stops at this fixed boundary: a live producer may never leave the stream empty. Tail reads do not replace cursor filters.

ack

ack(upto: Record | int) -> bool

Ack upto (a record, or its offset) as the last PROCESSED position. Returns whether the cursor moved.

observe

observe(page: Page, before: int) -> None

Learn the cursor's stored position from a page read from it.

before is :attr:position captured before the fetch. A page read from the cursor starts right after its stored position. One that starts below before means the node lost acknowledged records (its data was reset or restored): the position goes back to the node's, so acks and stream-change hints below the old one count again. An ack from another thread during the fetch only moves the position forward, so it is never mistaken for a reset.

wait_caught_up

wait_caught_up(head: int, timeout: float | None = None) -> bool

Block until :attr:position reached head (e.g. from :meth:head, captured when a request arrived).

Waits on this stream's own acknowledgements from whoever drains it; nothing is read here. False when timeout (seconds) passed first.

retire

retire() -> None

Delete this cursor at the door — idempotent, also when it never existed. A later fetch under the same name starts over.

drain

drain(*, stop: Event | None = None, head: int | None = None) -> Iterator[Record]

Yield every record from the cursor's position to the head, page by page, acking each page after its records were consumed. Capture a finite head so continuous producers cannot keep this call open forever. Cancellation leaves a partially consumed page unacknowledged for replay. The final page may include records admitted after the captured head.

head is a boundary the caller already holds, such as the :attr:chaski.stream_changes.StreamChange.head of the hint that woke it; None reads it with :meth:head first.

follow

follow(bell: Doorbell | None = None, *, stop: Event | None = None, idle_drain_s: float | None = IDLE_DRAIN_S) -> Iterator[Record]

:meth:drain now, then again after every ring of bell, until stop is set. Ring the bell from the MQTT subscription to the topics this stream reads and on every reconnect. The generation is taken before each drain, so a ring during a drain is not lost. Setting stop ends it.

After idle_drain_s without a ring it drains anyway: a filtered stream whose topics stay silent still walks its cursor past the records it skips, so it does not hold the node's retention (None waits for the bell alone).

Without a bell it watches the stream's growth, and each hint's head bounds the drain: a hint the cursor already passed costs no request, and a drain reads no tail first. The idle drain is skipped too while the newest hint shows the cursor at the head: it has already walked past every record up to it.

NotEnrolled

NotEnrolled(name: str, node_url: str, command: str)

Bases: RuntimeError

Raised by :meth:Service.start when the node refuses this identity's CONNECT — outside a deployment only. The message says how an operator enrolls it; also available bare via :meth:Service.enroll_hint.