ConfigService
Base path /squiddy.v1.ConfigService/ · defined in proto/squiddy/v1/config.proto
ConfigService is the remote-configuration RPC. It replaces the legacy GET|POST /api/GetRemoteConfiguration JSON endpoint with a typed Connect contract shared verbatim by the Go server and the KMP clients.
Authentication
Calls carry the API key of the environment they read, in the X-API-Key header. The key determines the tenant, project and environment, so a client sends only its app_id: any addressing coordinate in the request is ignored in favour of the key's. A request without a valid key is rejected with unauthenticated.
Procedures
| Procedure | Summary |
|---|---|
GetRemoteConfiguration | GetRemoteConfiguration resolves the per-app configuration for the requesting client. |
GetRemoteConfiguration
POST /squiddy.v1.ConfigService/GetRemoteConfiguration
GetRemoteConfiguration resolves the per-app configuration for the requesting client. Application failures surface as a Connect error carrying a typed ErrorDetail, never as an in-band status envelope.
The ErrorDetail's exception_code names the failure, and the Connect status code of the error follows from it:
- 5000, any other failure:
internal. - 5001, the configuration resolved but is incomplete:
failed_precondition. - 5002, a required request field is missing or malformed:
invalid_argument. - 5003, no configuration is published for the app_id:
not_found. - 5004, the key is valid but its account is not being served:
permission_denied. It is not retryable: keep serving the configuration already cached, and tell a human.
Where the installation enforces plan limits, a key that exceeds its plan's request rate is refused with resource_exhausted (HTTP 429 on the Connect protocol) and no ErrorDetail. The Retry-After header says how many whole seconds to wait before calling again.
Errors: failed_precondition, internal, invalid_argument, not_found, permission_denied, resource_exhausted, unauthenticated
GetRemoteConfigurationRequest
Request of GetRemoteConfiguration.
GetRemoteConfigurationRequest identifies the client asking for its configuration. The six identity fields are required (their presence/emptiness is enforced by the server, not by the wire type, so they are plain strings). lang_fingerprint is the opaque token the client echoes back from a previous response; it is optional so an absent token (never sent) stays distinct from an empty string.
tenant, project and environment are the addressing coordinates that, together with app_id, locate a configuration in the multi-tenant store, so the same app_id can resolve to different configurations per tenant and environment. They are optional for backward compatibility: a legacy appID-only client omits them, and the server resolves the request against the default tenant/project/environment.
BREAKING CHANGE: when the data-plane requires an API key, the tenant, project and environment are ALL derived from the authenticated key, not from the request — any client-supplied value for the three is ignored (closing the tenant-spoofing seam). A request without a valid X-API-Key is rejected with CodeUnauthenticated. app_id stays client-supplied, since one key serves every app in its environment. The three addressing fields remain on the wire because the anonymous data-plane — used in local dev when no control plane is configured — still honors the client-supplied coordinates as before. A key is bound to one environment and an environment belongs to exactly one project, so a keyed client can send app_id alone and still resolve its configuration. An app_id with no configuration published in the key's environment is answered with not_found.
config_fingerprint is the application-level equivalent of an HTTP If-None-Match: the opaque token the client received as config_fingerprint in a previous response. Connect calls travel over POST, where 304/If-None-Match have no meaning, so the conditional is expressed in the message itself. When the token still matches the freshly resolved configuration the server answers with a minimal not_modified response. It is optional so a client that never sends it (every legacy client) is distinct from one sending an empty token, and it always yields the full payload.
entity_id is the percentage-rollout bucketing key: the stable identity of whoever is asking, which the server hashes to decide whether this client is inside the share of the audience a gradually-released configuration block targets. THE ENTITY-KEY CONTRACT, which a client must honour for a rollout to behave:
- Send a value that never changes for the same user or installation. Generate it once (a random UUID at first launch is enough), persist it, and reuse it on every call — including after an app update. A value that changes re-rolls the dice, so the client would drift in and out of the rollout between calls.
- It is hashed VERBATIM: the server does not trim, lowercase or otherwise normalize it, so "AB-1" and "ab-1" are two different entities. Send the same bytes every time.
- It needs no particular meaning to the server and is never echoed back, matched against configuration values, or used for addressing — so prefer an opaque per-install id over personal data such as an email or phone number.
- It is optional. Omitting it does not fail a request: the server then buckets on app_id, so the whole app is either inside a rollout or outside it (per-app instead of per-install granularity) — which also means a percentage rollout cannot be gradual for that client. A configuration that declares no rollout ignores the field entirely.
| # | Field | JSON | Type | Presence | Constraints |
|---|---|---|---|---|---|
| 1 | app_id | appId | string | singular | — |
| 2 | app_bundle_id | appBundleId | string | singular | — |
| 3 | app_version | appVersion | string | singular | — |
| 4 | app_type | appType | string | singular | — |
| 5 | app_mode | appMode | string | singular | — |
| 6 | app_language | appLanguage | string | singular | — |
| 7 | lang_fingerprint | langFingerprint | string | optional | — |
| 8 | custom_params | customParams | string | repeated | — |
| 9 | tenant | tenant | string | optional | — |
| 10 | project | project | string | optional | — |
| 11 | environment | environment | string | optional | — |
| 12 | config_fingerprint | configFingerprint | string | optional | — |
| 13 | entity_id | entityId | string | optional | — |
GetRemoteConfigurationResponse
Response of GetRemoteConfiguration.
GetRemoteConfigurationResponse is the resolved configuration, minus the legacy status/statusCode/statusMsg envelope (errors now travel as Connect errors). Scalar fields the server may leave unset use optional to preserve presence semantics; message-typed fields already carry presence inherently.
lang_fingerprint is the SHA-256 token of the languages resolved for this client: the client stores it with the languages and echoes it on the next call, so the server can leave the languages out while they still match. It is present whenever the configuration has languages for the client, so the two fields are read together:
- languages and lang_fingerprint both set: the languages, and the token to store with them.
- languages absent, lang_fingerprint set: the languages are unchanged, so keep the ones you hold. The token is the echo of the request's lang_fingerprint.
- both absent: the configuration has no languages for this client, so languages held from an earlier response no longer apply.
A server that predates the echo left lang_fingerprint out together with the languages, so from such a server "both absent" after sending a lang_fingerprint can also mean "unchanged". The minimal not_modified answer described below carries neither field: the client keeps its languages and their token along with the rest of its copy.
config_fingerprint and not_modified are the response half of the conditional contract. config_fingerprint is the SHA-256 token of the whole resolved configuration and is emitted on every successful response, so the client can store it and echo it back as the request's config_fingerprint. not_modified is true only on the minimal response the server returns when the echoed token still matches: in that case every heavy block (server_api, app_update, info_point, languages) is omitted and the client keeps the copy it already holds. It is a plain bool because false — the ordinary full response — is the meaningful default for a client that ignores the field.
| # | Field | JSON | Type | Presence | Constraints |
|---|---|---|---|---|---|
| 1 | hub_name | hubName | string | optional | — |
| 2 | hub_version | hubVersion | string | optional | — |
| 3 | config_version | configVersion | string | optional | — |
| 4 | server_api | serverApi | ServerApi | singular | — |
| 5 | app_update | appUpdate | AppUpdate | singular | — |
| 6 | info_point | infoPoint | InfoPoint | singular | — |
| 7 | languages | languages | Languages | singular | — |
| 8 | lang_fingerprint | langFingerprint | string | optional | — |
| 9 | config_fingerprint | configFingerprint | string | optional | — |
| 10 | not_modified | notModified | bool | singular | — |
Types
ServerApi
ServerApi is the resolved server-API block. server_settings is a repeated message rather than optional: when populated it is the full list, and an empty list means "no settings" — the list itself is never null.
| # | Field | JSON | Type | Presence | Constraints |
|---|---|---|---|---|---|
| 1 | base_url | baseUrl | string | optional | — |
| 2 | mode | mode | string | optional | — |
| 3 | api_version | apiVersion | string | optional | — |
| 4 | active_debug | activeDebug | bool | singular | — |
| 5 | server_settings | serverSettings | ServerSetting | repeated | — |
ServerSetting
ServerSetting is a single key/value server setting echoed to the client. All four fields are always present.
| # | Field | JSON | Type | Presence | Constraints |
|---|---|---|---|---|---|
| 1 | key | key | string | singular | — |
| 2 | value | value | string | singular | — |
| 3 | type | type | string | singular | — |
| 4 | action | action | string | singular | — |
AppUpdate
AppUpdate is the resolved app-update block: a required flag plus an optional localized title/message.
| # | Field | JSON | Type | Presence | Constraints |
|---|---|---|---|---|---|
| 1 | required | required | bool | singular | — |
| 2 | title | title | string | optional | — |
| 3 | message | message | string | optional | — |
InfoPoint
InfoPoint is the resolved info-point block: a halt flag plus an optional localized title/message.
| # | Field | JSON | Type | Presence | Constraints |
|---|---|---|---|---|---|
| 1 | halt | halt | bool | singular | — |
| 2 | title | title | string | optional | — |
| 3 | message | message | string | optional | — |
Languages
Languages carries the default language and the language dictionary list. lang_list is a list of maps from a key to a list of string-to-string maps, modelled through a wrapper hierarchy because proto3 forbids both repeated map and a map whose value is itself a map:
Languages -> repeated LangBlock -> map<string, StringMapList>
-> repeated StringMap -> map<string, string>.
| # | Field | JSON | Type | Presence | Constraints |
|---|---|---|---|---|---|
| 1 | default_lang | defaultLang | string | singular | — |
| 2 | lang_list | langList | LangBlock | repeated | — |
LangBlock
LangBlock is one element of lang_list: a map from a key to a list of string-to-string maps. The repeated-of-maps value is wrapped in StringMapList because a proto3 map value may not itself be a map or repeated.
| # | Field | JSON | Type | Presence | Constraints |
|---|---|---|---|---|---|
| 1 | entries | entries | map<string, StringMapList> | map | — |
StringMapList
StringMapList wraps a list of string-to-string maps, since a proto3 map value cannot be a repeated field directly.
| # | Field | JSON | Type | Presence | Constraints |
|---|---|---|---|---|---|
| 1 | items | items | StringMap | repeated | — |
StringMap
StringMap wraps a single string-to-string map; the wrapper lets it be used as a repeated element inside StringMapList.
| # | Field | JSON | Type | Presence | Constraints |
|---|---|---|---|---|---|
| 1 | entries | entries | map<string, string> | map | — |
ErrorDetail
ErrorDetail is the typed payload attached to a Connect error so clients can react to an application failure without parsing an in-band status envelope. It replaces the legacy ko response (statusCode/statusMsg/...): exception_code carries the application code (5000-5004), while the Connect status code on the error itself conveys the idiomatic status. config_version is optional because it is known only for failures raised after the configuration was loaded (e.g. exception_code 5001); hub_name is always set.
hub_version is DEPRECATED and no longer stamped on errors: on a failure it only named the build of the retired .NET assembly the message format came from, which tells whoever is reading the error nothing actionable. The field is kept on the wire, always empty, so existing clients do not break. The successful response still carries hub_version, where it is part of the contract.
| # | Field | JSON | Type | Presence | Constraints |
|---|---|---|---|---|---|
| 1 | exception_code | exceptionCode | int32 | singular | — |
| 2 | config_version | configVersion | string | optional | — |
| 3 | hub_name | hubName | string | singular | — |
| 4 | hub_version | hubVersion | string | singular | deprecated |