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

ProcedureSummary
GetRemoteConfigurationGetRemoteConfiguration 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:

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:

#FieldJSONTypePresenceConstraints
1app_idappIdstringsingular—
2app_bundle_idappBundleIdstringsingular—
3app_versionappVersionstringsingular—
4app_typeappTypestringsingular—
5app_modeappModestringsingular—
6app_languageappLanguagestringsingular—
7lang_fingerprintlangFingerprintstringoptional—
8custom_paramscustomParamsstringrepeated—
9tenanttenantstringoptional—
10projectprojectstringoptional—
11environmentenvironmentstringoptional—
12config_fingerprintconfigFingerprintstringoptional—
13entity_identityIdstringoptional—

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:

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.

#FieldJSONTypePresenceConstraints
1hub_namehubNamestringoptional—
2hub_versionhubVersionstringoptional—
3config_versionconfigVersionstringoptional—
4server_apiserverApiServerApisingular—
5app_updateappUpdateAppUpdatesingular—
6info_pointinfoPointInfoPointsingular—
7languageslanguagesLanguagessingular—
8lang_fingerprintlangFingerprintstringoptional—
9config_fingerprintconfigFingerprintstringoptional—
10not_modifiednotModifiedboolsingular—

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.

#FieldJSONTypePresenceConstraints
1base_urlbaseUrlstringoptional—
2modemodestringoptional—
3api_versionapiVersionstringoptional—
4active_debugactiveDebugboolsingular—
5server_settingsserverSettingsServerSettingrepeated—

ServerSetting

ServerSetting is a single key/value server setting echoed to the client. All four fields are always present.

#FieldJSONTypePresenceConstraints
1keykeystringsingular—
2valuevaluestringsingular—
3typetypestringsingular—
4actionactionstringsingular—

AppUpdate

AppUpdate is the resolved app-update block: a required flag plus an optional localized title/message.

#FieldJSONTypePresenceConstraints
1requiredrequiredboolsingular—
2titletitlestringoptional—
3messagemessagestringoptional—

InfoPoint

InfoPoint is the resolved info-point block: a halt flag plus an optional localized title/message.

#FieldJSONTypePresenceConstraints
1halthaltboolsingular—
2titletitlestringoptional—
3messagemessagestringoptional—

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>.

#FieldJSONTypePresenceConstraints
1default_langdefaultLangstringsingular—
2lang_listlangListLangBlockrepeated—

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.

#FieldJSONTypePresenceConstraints
1entriesentriesmap<string, StringMapList>map—

StringMapList

StringMapList wraps a list of string-to-string maps, since a proto3 map value cannot be a repeated field directly.

#FieldJSONTypePresenceConstraints
1itemsitemsStringMaprepeated—

StringMap

StringMap wraps a single string-to-string map; the wrapper lets it be used as a repeated element inside StringMapList.

#FieldJSONTypePresenceConstraints
1entriesentriesmap<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.

#FieldJSONTypePresenceConstraints
1exception_codeexceptionCodeint32singular—
2config_versionconfigVersionstringoptional—
3hub_namehubNamestringsingular—
4hub_versionhubVersionstringsingulardeprecated