API Reference

gRPC API documentation for router-hosts.

Auto-generated

This documentation is auto-generated from protobuf definitions.

---

Protocol Documentation

Table of Contents

• router_hosts/v1/hosts.proto

  • AcmeHealth
  • AddHostRequest
  • AddHostResponse
  • AliasesUpdate
  • CompactAggregatesRequest
  • CompactAggregatesResponse
  • CompactedAggregate
  • CreateSnapshotRequest
  • CreateSnapshotResponse
  • DatabaseHealth
  • DeleteHostRequest
  • DeleteHostResponse
  • DeleteSnapshotRequest
  • DeleteSnapshotResponse
  • ExportHostsRequest
  • ExportHostsResponse
  • GetHostRequest
  • GetHostResponse
  • HealthRequest
  • HealthResponse
  • HooksHealth
  • HostEntry
  • ImportHostsRequest
  • ImportHostsResponse
  • ListHostsRequest
  • ListHostsResponse
  • ListSnapshotsRequest
  • ListSnapshotsResponse
  • LivenessRequest
  • LivenessResponse
  • ReadinessRequest
  • ReadinessResponse
  • RollbackToSnapshotRequest
  • RollbackToSnapshotResponse
  • SearchHostsRequest
  • SearchHostsResponse
  • ServerInfo
  • SinkStatus
  • Snapshot
  • SnapshotComplete
  • TagsUpdate
  • UpdateHostRequest
  • UpdateHostResponse
  • WatchHostsRequest

  • WatchHostsResponse

  • HostsService

• Scalar Value Types

Top

router_hosts/v1/hosts.proto

AcmeHealth

ACME certificate health status

Field	Type	Label	Description
enabled	bool		Whether ACME is enabled
status	string		Certificate status: "valid", "renewing", "expired", "disabled"
expires_at	int64		Certificate expiry timestamp (Unix seconds, 0 if disabled)
error	string		Error message if there's an issue (empty if healthy)

AddHostRequest

Request to add a new host entry

Field	Type	Label	Description
ip_address	string		IP address (IPv4 or IPv6) for the new host (required)
hostname	string		DNS hostname for the new host (required)
comment	string	optional	Optional comment for the host entry
tags	string	repeated	Optional tags for categorization
aliases	string	repeated	Optional hostname aliases

AddHostResponse

Response after adding a host entry

Field	Type	Label	Description
id	string		ID of the newly created host entry
entry	HostEntry		The complete host entry that was created

AliasesUpdate

Wrapper for updating aliases with optional semantics

Field	Type	Label	Description
values	string	repeated	New alias values (empty array = clear all aliases)

CompactAggregatesRequest

Request to compact one aggregate or all aggregates over an event-count threshold

Field	Type	Label	Description
aggregate_id	string		Compact exactly this aggregate (ULID)
over_threshold	int64		Compact every aggregate whose event count exceeds this threshold
dry_run	bool		If true, report what would be compacted without modifying anything

CompactAggregatesResponse

Response after compaction

Field	Type	Label	Description
compacted	CompactedAggregate	repeated	Per-aggregate compaction results
total_events_reclaimed	int64		Total number of events reclaimed across all compacted aggregates

CompactedAggregate

Per-aggregate compaction result

Field	Type	Label	Description
aggregate_id	string		Aggregate identifier (ULID)
events_before	int64		Event count before compaction
events_after	int64		Event count after compaction
version	int64		Preserved high-water (OCC) version — for audit/confirmation, not a write token

CreateSnapshotRequest

Request to create a snapshot of the current hosts database state

Field	Type	Label	Description
name	string		Optional name for the snapshot (auto-generated if not provided)
trigger	string		What triggered this snapshot (defaults to "manual" if not provided)

CreateSnapshotResponse

Response after creating a snapshot

Field	Type	Label	Description
snapshot_id	string		Unique identifier for the newly created snapshot
created_at	google.protobuf.Timestamp		Timestamp when snapshot was created
entry_count	int32		Number of entries in the snapshot

DatabaseHealth

Database health status

Field	Type	Label	Description
connected	bool		Whether the database connection is working
backend	string		Database backend type: "sqlite", "postgresql", "duckdb"
latency_ms	int64		Last health check latency in milliseconds
error	string		Error message if not connected (empty if healthy)

DeleteHostRequest

Request to delete a host entry (creates tombstone event)

Field	Type	Label	Description
id	string		ID of the host entry to delete
expected_version	string	optional	Expected version for optimistic concurrency (optional). If omitted, server fetches current version (racy under concurrency).

DeleteHostResponse

Response after deleting a host entry

Field	Type	Label	Description
success	bool		Whether the deletion succeeded

DeleteSnapshotRequest

Request to delete a snapshot

Field	Type	Label	Description
snapshot_id	string		ID of the snapshot to delete

DeleteSnapshotResponse

Response after deleting a snapshot

Field	Type	Label	Description
success	bool		Whether the deletion succeeded

ExportHostsRequest

Request to export all hosts in a specified format

Field	Type	Label	Description
format	string		Export format: "hosts" (standard /etc/hosts), "json", or "csv"

ExportHostsResponse

Response containing exported host data (streamed in chunks)

Field	Type	Label	Description
chunk	bytes		Chunk of exported data in the requested format

GetHostRequest

Request to retrieve a single host entry by ID

Field	Type	Label	Description
id	string		ID of the host entry to retrieve

GetHostResponse

Response containing the requested host entry

Field	Type	Label	Description
entry	HostEntry		The requested host entry

HealthRequest

Request for detailed health status

HealthResponse

Response containing detailed health status of all components

Field	Type	Label	Description
healthy	bool		Overall health status (true if all critical components are healthy)
server	ServerInfo		Server information
database	DatabaseHealth		Database health status
acme	AcmeHealth		ACME certificate health status
hooks	HooksHealth		Hooks configuration status

HooksHealth

Hooks configuration status

Field	Type	Label	Description
configured_count	int32		Number of configured hooks
hook_names	string	repeated	Names of configured hooks

HostEntry

Represents a single host entry in the hosts file

Field	Type	Label	Description
id	string		Unique identifier for this host entry (ULID format)
ip_address	string		IP address (IPv4 or IPv6) for the host
hostname	string		DNS hostname or FQDN for the host
comment	string	optional	Optional comment to appear in hosts file
tags	string	repeated	Optional tags for categorization and filtering (e.g., "homelab", "production")
created_at	google.protobuf.Timestamp		Timestamp when this entry was created
updated_at	google.protobuf.Timestamp		Timestamp when this entry was last updated
version	string		Version identifier for optimistic concurrency control. Treat as opaque - compare for equality only, do not parse. Format may change in future versions.
aliases	string	repeated	Optional hostname aliases (additional names resolving to same IP)

ImportHostsRequest

Request to import hosts from a file format via streaming chunks

Field	Type	Label	Description
chunk	bytes		Chunk of file data being uploaded
last_chunk	bool		Whether this is the final chunk of the import
format	string	optional	Import format: "hosts" (default), "json", "csv"
conflict_mode	string	optional	Conflict handling: "skip" (default), "replace", "strict"
force	bool	optional	Override strict mode validation (e.g., alias conflicts with existing hostname)

ImportHostsResponse

Response for host import operation (streamed progress updates)

Example counter values for importing 5 entries where 2 already exist:

With conflict_mode = "skip": processed=5, created=3, updated=0, skipped=2, failed=0 (existing entries left unchanged, counted as skipped)

With conflict_mode = "replace": processed=5, created=3, updated=2, skipped=0, failed=0 (existing entries updated with new values)

Example with validation failures (2 invalid entries): processed=5, created=2, updated=0, skipped=0, failed=3 validation_errors=["Line 1: Invalid IP '999.0.0.1': ...", "Line 3: Invalid hostname 'bad_host': ...", "Line 5: Invalid IP 'not-an-ip': ..."]

Note: In replace mode, if existing entry has identical values, it counts as skipped (no-op), not updated.

Field	Type	Label	Description
processed	int32		Total entries processed so far
created	int32		Successfully created entries
updated	int32		Existing entries updated. Only non-zero when conflict_mode = "replace". In skip mode, duplicates increment skipped instead.
skipped	int32		Duplicates skipped (when conflict_mode = "skip")
failed	int32		Validation failures
error	string	optional	Error message if import operation encountered an issue
validation_errors	string	repeated	Details of validation failures (line number and reason) Only populated when failed > 0

ListHostsRequest

Request to list host entries with optional filtering and pagination

Field	Type	Label	Description
filter	string	optional	Optional filter expression (e.g., by tag, active status)
limit	int32	optional	Maximum number of entries to return (pagination)
offset	int32	optional	Number of entries to skip (pagination)

ListHostsResponse

Response containing a single host entry (streamed)

Field	Type	Label	Description
entry	HostEntry		A host entry from the list

ListSnapshotsRequest

Request to list all available snapshots

Field	Type	Label	Description
limit	uint32		Optional limit for pagination
offset	uint32		Optional offset for pagination

ListSnapshotsResponse

Response containing a single snapshot (streamed)

Field	Type	Label	Description
snapshot	Snapshot		A snapshot from the list

LivenessRequest

Request for liveness check (is the process alive?)

LivenessResponse

Response for liveness check

Field	Type	Label	Description
alive	bool		Always true if the server can respond

ReadinessRequest

Request for readiness check (is the server ready to handle requests?)

ReadinessResponse

Response for readiness check

Field	Type	Label	Description
ready	bool		Whether the server is ready to handle requests
reason	string		Reason for not being ready (empty if ready)

RollbackToSnapshotRequest

Request to restore the hosts database to a previous snapshot state

Field	Type	Label	Description
snapshot_id	string		ID of the snapshot to restore

RollbackToSnapshotResponse

Response after rolling back to a snapshot

Field	Type	Label	Description
success	bool		Whether the rollback succeeded
new_snapshot_id	string		ID of the auto-created snapshot taken before rollback (for undo capability)
restored_entry_count	int32		Number of host entries restored from the snapshot

SearchHostsRequest

Request to search for host entries by query

Field	Type	Label	Description
query	string		Search query (searches IP, hostname, comment, and tags)

SearchHostsResponse

Response containing a single matching host entry (streamed)

Field	Type	Label	Description
entry	HostEntry		A host entry that matches the search query

ServerInfo

Server information and metadata

Field	Type	Label	Description
version	string		Server version (e.g., "0.6.0")
uptime_seconds	int64		Server uptime in seconds
build_info	string		Build information (e.g., "v0.6.0 (abc1234)")

SinkStatus

Upstream health/status a sink reports on its WatchHosts stream.

Field	Type	Label	Description
last_success_unix	int64		Unix seconds of the sink's last successful render+write.
consecutive_failures	int32		Consecutive render/write failures since the last success.
contract_version	string		Template contract version this sink was built against.
rendered_change_id	string		Change ID (see SnapshotComplete.change_id) this sink last rendered.

The server records this value and reports it upstream through metrics; the server never consults it when deciding what to send. Using it to decide what to send would make it a resume token and break the stateless-server constraint (D-06, D-08). | | reload_failed | bool | | Whether the sink's post-write reload hook failed on its last cycle. Distinguishes "your zone file is correct but your resolver did not pick it up" (reload_failed = true) from "your zone file is old" (last_success_unix is stale) — a different page. | | last_reload_success_unix | int64 | | Unix seconds of the sink's last successful reload-hook run. |

Snapshot

Represents a saved snapshot of the hosts database at a point in time

Field	Type	Label	Description
snapshot_id	string		Unique identifier for this snapshot
created_at	google.protobuf.Timestamp		Timestamp when this snapshot was created
entry_count	int32		Number of host entries captured in this snapshot
trigger	string		What triggered this snapshot (e.g., "manual", "pre-rollback", "scheduled")
name	string		Optional snapshot name

SnapshotComplete

Terminates a WatchHosts snapshot: every HostEntry message that precedes it on the stream belongs to the same snapshot.

Field	Type	Label	Description
count	int32		Number of entries in this snapshot. int32 because the practical ceiling is the consumer's configured limits.max_stream_entries (default 50,000) — a server holding more entries than a consumer's ceiling makes that consumer refuse the snapshot rather than truncate it, so the two numbers are the same unit. The server validates the count fits an int32 before setting it and fails the RPC otherwise, so this field can never carry a wrapped negative value.
generated_at	google.protobuf.Timestamp		When this snapshot was generated.
contract_version	string		Template data contract version this snapshot was produced under.
change_id	string		ULID of the newest event in the server's log as of the moment the snapshot began — therefore a LOWER BOUND on the state the entries reflect: the entries may include a mutation that landed after this ID was read, never the reverse. The same server state yields the same value for every consumer. An empty log yields the zero ULID. A consumer comparing change IDs uses exact string equality — never a prefix, ordering, or numeric comparison.

TagsUpdate

Wrapper for updating tags with optional semantics

Field	Type	Label	Description
values	string	repeated	New tag values (empty array = clear all tags)

UpdateHostRequest

Request to update an existing host entry

Field	Type	Label	Description
id	string		ID of the host entry to update (required)
ip_address	string	optional	New IP address (optional, keeps existing if not provided)
hostname	string	optional	New hostname (optional, keeps existing if not provided)
comment	string	optional	New comment (optional, keeps existing if not provided, empty string to clear)
expected_version	string	optional	Expected version for optimistic concurrency control
aliases	AliasesUpdate		New aliases (wrapper for optional semantics)
tags	TagsUpdate		New tags (wrapper for optional semantics - moved from field 5) Use this field to update tags. To clear all tags, pass an empty TagsUpdate with no values. Omit this field to preserve existing tags.

UpdateHostResponse

Response after updating a host entry

Field	Type	Label	Description
entry	HostEntry		The updated host entry with new values

WatchHostsRequest

Opening (and, in follow mode, only) request on a WatchHosts stream.

Field	Type	Label	Description
follow	bool		Whether to keep the stream open and push a fresh snapshot on every change (sink mode) instead of closing after one snapshot (one-shot mode). Read only from the FIRST message on the stream; the server ignores this field on every later message, so a status-only message may leave it unset.
status	SinkStatus	optional	Sink status. Meaningful on EVERY message including the first: a reconnecting sink uses the opening message to report the state it already has on disk, and the server records it.

WatchHostsResponse

One message on a WatchHosts response stream: either one host entry, or the terminator for the snapshot that preceded it.

Field	Type	Label	Description
entry	HostEntry		A single host entry belonging to the in-progress snapshot.
complete	SnapshotComplete		Terminator for the in-progress snapshot.

HostsService

Service definition for managing /etc/hosts entries via gRPC

Host management

Method Name	Request Type	Response Type	Description
AddHost	AddHostRequest	AddHostResponse	Add a new host entry to the hosts file
GetHost	GetHostRequest	GetHostResponse	Retrieve a single host entry by its ID
UpdateHost	UpdateHostRequest	UpdateHostResponse	Update an existing host entry
DeleteHost	DeleteHostRequest	DeleteHostResponse	Delete a host entry (creates tombstone event)
ListHosts	ListHostsRequest	ListHostsResponse stream	List all host entries with optional filtering and pagination (server streaming)
SearchHosts	SearchHostsRequest	SearchHostsResponse stream	Search for host entries by query string (server streaming)
ImportHosts	ImportHostsRequest stream	ImportHostsResponse stream	Import hosts from a file format via client streaming with server progress updates
ExportHosts	ExportHostsRequest	ExportHostsResponse stream	Export all hosts in a specified format via server streaming
WatchHosts	WatchHostsRequest stream	WatchHostsResponse stream	Stream host entries plus a snapshot terminator over a bidirectional stream; in follow mode, push a fresh snapshot on every change.
CreateSnapshot	CreateSnapshotRequest	CreateSnapshotResponse	Create a snapshot of the current hosts database state
ListSnapshots	ListSnapshotsRequest	ListSnapshotsResponse stream	List all available snapshots (server streaming)
RollbackToSnapshot	RollbackToSnapshotRequest	RollbackToSnapshotResponse	Restore the hosts database to a previous snapshot (creates backup snapshot first)
DeleteSnapshot	DeleteSnapshotRequest	DeleteSnapshotResponse	Delete a snapshot by its ID
CompactAggregates	CompactAggregatesRequest	CompactAggregatesResponse	Compact bloated aggregates by folding their event log to a single event
Liveness	LivenessRequest	LivenessResponse	Check if the server process is alive (minimal check, no I/O)
Readiness	ReadinessRequest	ReadinessResponse	Check if the server is ready to handle requests (verifies database connectivity)
Health	HealthRequest	HealthResponse	Get detailed health status of all server components

Scalar Value Types

.proto Type	Notes	C++	Java	Python	Go	C#	PHP	Ruby
double		double	double	float	float64	double	float	Float
float		float	float	float	float32	float	float	Float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long	int64	long	integer/string	Bignum
uint32	Uses variable-length encoding.	uint32	int	int/long	uint32	uint	integer	Bignum or Fixnum (as required)
uint64	Uses variable-length encoding.	uint64	long	int/long	uint64	ulong	integer/string	Bignum or Fixnum (as required)
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long	int64	long	integer/string	Bignum
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int	uint32	uint	integer	Bignum or Fixnum (as required)
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long	uint64	ulong	integer/string	Bignum
sfixed32	Always four bytes.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sfixed64	Always eight bytes.	int64	long	int/long	int64	long	integer/string	Bignum
bool		bool	boolean	boolean	bool	bool	boolean	TrueClass/FalseClass
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode	string	string	string	String (UTF-8)
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str	[]byte	ByteString	string	String (ASCII-8BIT)