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
¶
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
¶
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
¶
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
¶
The cursors the standing cursor_lag finding names (its
detail.cursors), () while none stands or the node names none.
node_id
property
¶
The node this service is registered at — level 4 of every topic
it writes. None before :meth:start.
service_id
property
¶
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
¶
Where the node currently has this service (re-resolved on every reconnect for a local service).
cursor_prefix
property
¶
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 ¶
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 ¶
: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
¶
: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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
Subscribe to local durable-stream changes. Closed with this service.
retained_view ¶
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 ¶
(path, reason) for every published path with no bound Signal
yet — see :func:_pending_reason for what each reason means.
status ¶
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 ¶
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.
wake_on ¶
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 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 ¶
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 ¶
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 ¶
:meth:chaski.Service.announce_commands, keeping the routes of the
bound signals this connector writes.
handle_signal_write
async
¶
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 ¶
Serve until stopped: :func:run with this service.
health_problem ¶
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
¶
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 ¶
The signals whose samples are being refused, keyed by signal id (or topic, for a sample without one).
source_clock_status ¶
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 ¶
The protocol half of a connector. Subclass it, implement the four
async methods, hand an instance to :class:ConnectorService.
connect
async
¶
Open the source. Raise on failure, with a message naming what failed (host, port, endpoint) — the loop logs it and retries.
discover
async
¶
Discover the source's tags. Called after connect (or without
it, when catalogue_requires_connection is False).
read
async
¶
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
¶
Release the source. Must tolerate being called on a half-open or already-closed connection.
write
async
¶
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
¶
The producer classes this service runs, sorted by name.
door
property
¶
The door every input resolves through — the base class's own,
open after :meth:start. Outputs write with :meth:send.
accept_gap_path
property
¶
The node-local path of this service's accept-gap command (_CmdMaintain).
add ¶
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 ¶
Import package (and every submodule under it) and run every
concrete producer it defines. Returns how many were added.
discover_directory ¶
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 ¶
Whether producer's live triggers are held while its first
backfill runs (:mod:chaski.dataops.backfill).
request_backfill ¶
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 ¶
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 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 ¶
Catalogue every declared SignalOutput and bind every
AnnotationOutput on instances. Returns the catalogue's
{source: tag_id}. Requires :meth:start.
serve
async
¶
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.
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 ¶
Write config, launch colcad, and wait for its local /healthz.
status ¶
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 ¶
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 ¶
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 ¶
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 ¶
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.
position
property
¶
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 ¶
One page from the cursor's stored position, or from from_offset
when that lies ahead of it. Never moves the cursor.
head ¶
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 (a record, or its offset) as the last PROCESSED
position. Returns whether the cursor moved.
observe ¶
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 ¶
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 ¶
Delete this cursor at the door — idempotent, also when it never existed. A later fetch under the same name starts over.
drain ¶
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 ¶
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.