System
System service API reference
Services
SystemService Service
System-level, read-only metadata surface for the GoodMem control plane.
<h3>Design rationale</h3>
<ul>
<li>Keep operational introspection separate from resource/data plane APIs. The existing
services (MemoryService, PingService, etc.) are scoped to tenant resources and enforce
RBAC at the resource level. System metadata should remain callable before authentication is
configured so bootstrapping tools (CLI installers, readiness probes) can discover build
details.</li>
<li>Provide a single aggregation point for lightweight control-plane signals such as version
details, advertised capabilities, and compatibility warnings. This prevents proliferation
of ad-hoc “version” RPCs on unrelated services and keeps the expectations clear for callers:
anything under SystemService is safe to call, side-effect free, and cheap.</li>
<li>Disallow heavy or stateful operations here. Activities that mutate cluster state, require
elevated permissions, or contact user-configured upstream providers remain in dedicated
services such as AdminService or PingService to preserve clear authorization boundaries
and operational semantics.</li>
</ul>
<h3>Good fit for this service</h3> <ul> <li>Read-only build metadata (semantic version, git revision, dirty workspace indicator).</li> <li>Server capability flags that help clients adapt behaviour (e.g., “supports inference proxy”, “requires schema ≥ X”).</li> <li>Control-plane lifecycle hints (drain state, maintenance windows) when exposed as informational snapshots.</li> </ul>
<h3>Bad fit for this service</h3>
<ul>
<li>Anything that requires per-resource permissions or talks to tenant data (belongs in the
existing resource services).</li>
<li>Operations that mutate state or require administrator decision making (belongs in
AdminService).</li>
<li>High-frequency, streaming diagnostics such as inference probes (belongs in
PingService).</li>
</ul>
Authentication: Calls MAY be served before API keys exist. Implementations should ensure the
interceptor chain allows anonymous access (e.g., via MethodAuthorizer).
Side effects: None. All RPCs under this service MUST be idempotent, fast, and telemetry-friendly.
GetServerInfo
Summary: Returns the server's advertised version and build metadata.
Use cases:
- CLI bootstrap comparing client and server semantic versions.
- Observability tooling recording deployed build identifiers.
- Automated installers verifying dirty-build markings before enabling upgrades.
Response contract: Implementations SHOULD populate the numeric fields when the
Implementation-Version manifest entry follows MAJOR.MINOR.PATCH semantics. When parsing
fails, the string is still returned verbatim and the numeric components remain zero so callers
can fall back to string comparison.
| Type | |
|---|---|
| Request | goodmem.v1.GetServerInfoRequest |
| Response | goodmem.v1.GetServerInfoResponse |
Messages
GetServerInfoRequest
Empty request envelope for {@link SystemService#GetServerInfo}.
GetServerInfoResponse
Response payload describing the running server build.
| Field | Type | Description |
|---|---|---|
version | string | Canonical semantic version string from the server manifest (`Implementation-Version`). This is the primary value callers should display, and it is returned verbatim even when it represents a dirty or development build (for example `1.2.3-dirty` or `0.0.0-dev.abcdef`). |
major | uint32 | Numeric major version, parsed from {@link #version}. Left at zero when parsing fails. |
minor | uint32 | Numeric minor version, parsed from {@link #version}. Left at zero when parsing fails. |
patch | uint32 | Numeric patch version, parsed from {@link #version}. Left at zero when parsing fails. |
dirty | bool | True when the build was produced from a dirty workspace. Derived from the manifest entry or git metadata when available. |
git_commit | string | Git commit SHA (short or full) baked into the manifest (`Build-Commit-SHA`). Optional when unavailable. |
git_describe | string | Output from `git describe --tags --always --dirty`, when the build pipeline provides it. |
build_time | google.protobuf.Timestamp | Build completion timestamp in UTC. Optional; absent when the build pipeline does not supply it. |
capabilities | ...InfoResponse.CapabilitiesEntry | Arbitrary key/value pairs advertising optional capabilities or feature flags. Keys should be short snake_case identifiers (e.g., `supports_proxy`, `requires_migration_42`). |
GetServerInfoResponse.CapabilitiesEntry
| Field | Type | Description |
|---|---|---|
key | string | |
value | string |