Reference — Data Types

The two structured body shapes a client parses after decoding the EdgeCommons protobuf envelope: the get-status status document (the reply to the get-status command) and the event context object carried by every evt message. Both are validated against the source — the status document against src/control.rs (instance_status_json / disabled_status_json / component_status_json), the event context against src/events.rs (Event::fields / Event::plan). For the topic grammar, command envelope, and the event catalog (each type + severity), see messaging-interface.md.

In the decoded/diagnostic body representation, numeric fields are JSON numbers; byte counts and sizes are unsigned 64-bit (a JavaScript consumer may lose precision above 2^53). Timestamps are RFC3339 UTC strings.

The `get-status` document

get-status returns different shapes depending on which instance, if any, the request names:

No instance named — …/FileReplicator/cmd/get-status with no instance body field → a component-wide document: a roster of every instance plus a summary.
One instance named — …/FileReplicator/{id}/cmd/get-status, or the component topic with { "instance": "<id>" } → that one instance’s per-instance document (or its disabled document if it was disabled at startup). An unknown id is the error UNKNOWN_INSTANCE.

The reply is always wrapped by the command contract: { "ok": true, "result": <document> }.

Component-wide document

{
  "component": "com.mbreissi.edgecommons.FileReplicator",
  "thing": "gw-01",
  "instances": [ /* per-instance and/or disabled documents */ ],
  "summary": { "instances": 3, "active": 2, "disabled": 1 }
}

Field	Type	Notes
`component`	string	The component’s full name.
`thing`	string	The resolved ThingName (`-t`).
`instances`	array	One entry per configured instance — a per-instance document for a live instance, a disabled document for one disabled at startup.
`summary.instances`	int	Total configured instances (live plus disabled).
`summary.active`	int	How many are currently active (never counts disabled ones).
`summary.disabled`	int	How many were disabled at startup (`onPermissionError: disableInstance`).

Per-instance document

{
  "instance": "spool-to-archive",
  "active": true,
  "configuredEnabled": true,
  "schedule": { "mode": "immediate" },
  "awaiting":   { "count": 1, "bytes": 40, "files": [ { "path": "a.csv", "size": 40, "ageSecs": 100 } ] },
  "inProgress": [ { "path": "big.bin", "size": 100, "bytesDone": 30, "percent": 30.0, "destination": "s3", "attempt": 1 } ],
  "replicated": { "count": 4310, "bytes": 90 },
  "failed":     { "count": 2, "items": [ { "path": "x.csv", "attempts": 3, "lastError": "…", "state": "failed" } ] }
}

Field	Type	Notes
`instance`	string	The instance id.
`active`	bool	Effective activation (persisted runtime state wins over config `enabled`).
`configuredEnabled`	bool	The config `enabled` value (what a `set-activation` `reset` reverts to).
`schedule.mode`	string	The configured mode, verbatim: `immediate` \| `cron` \| `window`.
`awaiting.count`	int	Files ready and queued but not yet started.
`awaiting.bytes`	int	Total bytes of the awaiting set.
`awaiting.files[]`	array	Up to 100 entries (`count`/`bytes` reflect the full set): `path` (source-relative), `size` (int bytes), `ageSecs` (int — whole seconds queued).
`inProgress[]`	array	Up to 100 in-flight transfers: `path`, `size`, `bytesDone` (int), `percent` (float 0.0–100.0, one decimal), `destination` (backend label, e.g. `local`/`s3`), `attempt` (int, 1-based).
`replicated.count`	int	Lifetime successfully-replicated count (running stat).
`replicated.bytes`	int	Lifetime replicated bytes.
`failed.count`	int	Current count of items needing attention: failed, exhausted, quarantined, and cleanup-failed.
`failed.items[]`	array	Up to 100 entries: `path`, `attempts` (int), `lastError` (string), `state`, plus `quarantinedAt` only when `state == "quarantined"` and `cleanupAttempts` only when `state == "cleanup_failed"`.

failed.items[].state is one of failed (retrying), exhausted (retry budget spent, retained in place), quarantined (moved to failedDir), or cleanup_failed. quarantinedAt is an RFC3339 UTC timestamp.

A cleanup_failed item is not a transfer failure: the file reached and verified on every destination, but its source completion action did not succeed — the archive move failed, archiveDir is missing or unwritable, the delete failed, or the archived copy did not match the source. The source is still in the watch directory, the item is not counted in replicated, and its cleanupAttempts (not attempts, which counts transfers) says how many completion attempts were made. Fix the cause, then send trigger to re-drive it. See Explanation - Completion is proven, not assumed.

There is no link (destination-connectivity) field — file-replicator has no destination circuit-breaker (see explanation › Resilience). Do not depend on it.

Disabled-instance document

An instance disabled at startup by onPermissionError: disableInstance (the default) still answers get-status — with its reason — instead of UNKNOWN_INSTANCE. It shares the same top-level keys as a live instance (all tallies zeroed) plus the disabled* fields, so a consumer needs no separate schema:

{
  "instance": "plant-in",
  "active": false,
  "configuredEnabled": false,
  "disabled": true,
  "disabledReason": "permission denied: /data/in",
  "disabledRole": "ingress",
  "disabledPath": "/data/in",
  "schedule": { "mode": "disabled" },
  "awaiting":   { "count": 0, "bytes": 0, "files": [] },
  "inProgress": [],
  "replicated": { "count": 0, "bytes": 0 },
  "failed":     { "count": 0, "items": [] }
}

Field	Type	Notes
`disabled`	bool	Always `true` on this document.
`disabledReason`	string	Human-readable summary of the startup violation.
`disabledRole`	string	The offending directory role: `ingress` \| `egress` \| `archive` \| `failed`.
`disabledPath`	string	The path that failed the startup readable/writable check.
`schedule.mode`	string	The literal `"disabled"`.

Event `context` field types

Every evt message body is { "severity", "type", "message"?, "timestamp", "context"?, "alarm"?, "active"? } (see messaging-interface.md › Events). The context object carries the event-specific data; its fields, across all event types, have these types:

Context field	Type	Appears on	Meaning
`path`	string	most file events, `permission-denied`	Source-relative file path (or, for `permission-denied` egress, the destination).
`size`	int	`file-ready`, `replication-*`	File size in bytes.
`destination`	string	`replication-*`	Backend label of the target (`local`/`s3`/…).
`attempt`	int	`replication-started`/`-progress`/`-failed`	Current attempt, 1-based.
`attempts`	int	`retries-exhausted`, `file-quarantined`, `file-cleanup-failed`	Total attempts made — transfer attempts, except on `file-cleanup-failed`, where it counts source completion attempts.
`action`	string	`file-cleanup-failed`	The source completion action that failed: `archive` or `delete`.
`bytesDone`	int	`replication-progress`	Bytes transferred so far.
`percent`	float	`replication-progress`	Percent complete, 0.0–100.0.
`bytes`	int	`replication-completed`	Bytes transferred (total).
`willRetry`	bool	`replication-failed`	Always `true` — the engine will retry (contrast `retries-exhausted`).
`nextAttemptAt`	string (RFC3339)	`replication-failed`	Next scheduled attempt time; present only when scheduled.
`archivePath`	string	`file-archived`	Where the source was archived; omitted when unknown.
`quarantinePath`	string	`file-quarantined`	Where the source was quarantined; omitted when unknown.
`discovered`	int	`scan-complete`	Files newly enqueued this scan tick.
`awaiting`	int	`scan-complete`	Total files ready after the tick.
`source`	string	`instance-activated`/`-deactivated`	Who toggled activation (e.g. `control`).
`instances`	int	`component-ready`	Number of instances that started.
`version`	string	`component-ready`	Component version.
`scope`	string	`schedule-triggered`	`"all"` or an instance id.
`window`	string	`window-opened`/`-closed`	The schedule’s human-readable label (e.g. `0 22 * * * -> 0 6 * * *`).
`mode`	string	`schedule-complete`	`"cron"` \| `"window"`.
`role`	string	`permission-denied`	`ingress` \| `egress` \| `archive` \| `failed`.
`link`	string	`disconnected` — not emitted	Destination link label (there is no destination circuit-breaker).

message vs context. For the events with a natural error string — replication-failed, retries-exhausted, file-quarantined, file-cleanup-failed, permission-denied — the error is promoted to the top-level message field and removed from context (never duplicated in the decoded body). So a consumer reads the human error from message, and the machine fields (path, attempt, willRetry, role, …) from context.