Configuration, connections & runners

This page covers how a FACE instance is told about the systems it reads from and the compute it runs on. ConfigService stores connections: a source system, its non-secret settings and a separately held credential bundle. The same service tests connections, explores a source’s catalogue and takes bounded samples from it. It also registers runners, reports health, manages the integration settings (messaging numbers, billing and Google credentials, partner links) and offers two direct Databricks helpers. RunnerEnrollmentService works the other way round. A runner that the control plane cannot dial, for example one behind NAT, opens an outbound stream and receives its fetch work over that stream. Authentication and status-code conventions are on the API overview.

Summary

ConfigService

Full name semantics.v1.ConfigService.

Instance configuration: connections, runners, integration settings and resources. Every RPC needs a bearer session. Service-account tokens are refused (PERMISSION_DENIED) on every ConfigService RPC except ListConnections and ListRunners, which a workload needs in order to run. The handlers add no further role check, so any other recognised role may call them.

ListConnections

rpc ListConnections(ListConnectionsRequest) returns (ListConnectionsResponse);

• Kind: Unary.
• Auth: Bearer session. Service-account tokens are allowed.
• Errors: INTERNAL when the connection registry cannot be read.

Returns every connection stored on this instance. Each row carries two server-computed fields that answer different questions. credential_state tells you whether this node holds a credential bundle for the connection. source_backing tells you whether the address points at a demo mock service. Nothing is dialled to compute either. Use TestConnection to find out whether a source is reachable.

Connection config messages come back with their secret fields empty. Properties whose names look like secrets are moved to the credential store when the connection is created, so they do not appear in properties either.

Request: ListConnectionsRequest

No fields.

Response: ListConnectionsResponse

CreateConnection

rpc CreateConnection(CreateConnectionRequest) returns (CreateConnectionResponse);

• Kind: Unary.
• Auth: Bearer session. Service-account tokens are refused.
• Errors: None as gRPC status. Every failure returns success: false with message: no connection in the request, an id that already exists, an invalid id, a missing type, a malformed runner-deploy setting, or a credential store that could not be written.

Stores a connection and its credentials in a single operation. The credential bundle is written first. If that write fails, no connection record is created, so a success: true always means that both were stored.

• Id. If connection.id is empty, the server generates one. Either way the id comes back in connection_id, on failure too, so a retry can reuse it instead of creating a second row. An id must not be blank, must not have leading or trailing whitespace, must not contain a path separator or a NUL byte, and must not start with .. An id that already exists is refused. There is no update RPC: to change a connection, delete it and create it again.
• Type. connection.type is required. The server normalises its spelling to the canonical type name, so “Service Now”, “service-now” and “servicenow” are one type. A type the catalogue does not know is stored in normalised form rather than refused. See Connection types and credential keys.
• Credentials. There are two sources, and the server merges them into one write-only bundle: the credentials map, and the secret-valued fields of the config message (password, client_secret, api_key, personal_access_token, service_account_json, security_token). When both set the same key, the map wins. A properties entry whose name looks like a secret (for example *_token, *_secret) is moved into the bundle as well. Values that look like secrets are refused in the Snowflake and Databricks runner-deploy settings.
• Warnings. These are the same as ListConnectionsResponse.warnings. A warning is not a failure: the connection was created, and the caller is told what the storage does and does not guarantee.

Request: CreateConnectionRequest

Response: CreateConnectionResponse

DeleteConnection

rpc DeleteConnection(DeleteConnectionRequest) returns (DeleteConnectionResponse);

• Kind: Unary.
• Auth: Bearer session. Service-account tokens are refused.
• Errors: None as gRPC status. Read outcome: DELETE_CONNECTION_OUTCOME_NOT_FOUND for an unknown id, DELETE_CONNECTION_OUTCOME_FAILED for an empty id or a storage failure.

Removes a stored connection and its credential bundle. The credential bundle is removed first, and the record is kept if that fails. DELETED therefore never means that the record went while the secret stayed.

What a delete does not do:

• It does not revoke anything at the source. Nothing is dialled. A key that must be revoked has to be revoked in the system that issued it.
• It does not rewrite references. Fetch definitions, rules and lineage records that name this connection id keep the id, and it no longer resolves.
• NOT_FOUND means only that this instance does not hold the id now. It does not prove that the connection never existed elsewhere, for example on another instance or in a snapshot restored later.

Request: DeleteConnectionRequest

Response: DeleteConnectionResponse

TestConnection

rpc TestConnection(TestConnectionRequest) returns (TestConnectionResponse);

• Kind: Unary.
• Auth: Bearer session. Service-account tokens are refused.
• Errors: None as gRPC status. Returns success: false with message when the connection cannot be read, does not exist (“Connection not found”), has a type with no registered connector, or fails its probe.

Looks up the stored connection and its credentials and asks the connector to probe the source. Read success and live_check_performed together:

Even a true/true result only establishes that the endpoint is reachable and that the credential was accepted. It does not establish that records exist, that a sensor is publishing, or that the credential has scope for any other resource.

Request: TestConnectionRequest

Response: TestConnectionResponse

ExploreConnection

rpc ExploreConnection(ExploreConnectionRequest) returns (ExploreConnectionResponse);

• Kind: Unary.
• Auth: Bearer session. Service-account tokens are refused.
• Errors: None as gRPC status. Every outcome is a normal response. Check discovery_attempted, then description.supported, description.reason and description.aspects.

Asks a stored connection’s source what it holds: datasets, columns and their declared types, the source’s own comments and tags, the declared keys, and column masks and row filters where the catalogue publishes them. Every field comes from the source or is left empty. The response discloses table names, column names and comments, and it never carries row data: datasets[].sample is always unset. To read rows, call SampleConnectionDataset.

• When the id is empty or unknown, when the registry cannot be read, or when no connector is registered for the type, discovery_attempted is false and description.supported is false, with reason saying which.
• When the connector ran and failed, discovery_attempted is true, supported is false, and reason quotes what the source or driver said. A failed read is not a statement that the source is empty.
• When the connection has no stored credentials, the attempt is still made with none. A connector that needs a credential says so in reason.

How to read the result:

• A catalogue read is not a reachability check. Some connectors answer from a protocol handshake and some from a metadata query. supported: false can be a real answer: “this protocol has no catalogue”.
• The result shows only what this principal can see. Catalogues filter by the connection credential’s grants, so an empty list means “none visible to this role”. Check aspects before concluding that something is absent.
• A declared key is not an enforced one. See DeclaredRelationship.
• An absent mask does not prove an unredacted read. Redaction applied outside the catalogue, or by a view in front of the table, is invisible here.

Request: ExploreConnectionRequest

Response: ExploreConnectionResponse

SampleConnectionDataset

rpc SampleConnectionDataset(SampleConnectionDatasetRequest) returns (SampleConnectionDatasetResponse);

• Kind: Unary.
• Auth: Bearer session. Service-account tokens are refused.
• Errors: None as gRPC status. Every refusal or failure returns sampled: false with reason and no sample.

Reads a bounded set of actual rows from one dataset on a stored connection. It is the only RPC on this service that returns customer data. Bounded sampling is currently implemented for Snowflake and Databricks connections. For any other type the call is refused with a reason saying that this backend has not implemented sampling for that source type.

Processing order:

1. name must be non-empty.

2. row_limit must be between 0 and 1000. A value outside that range is refused, not clamped. 0 means the connector’s default. Each connector then applies its own ceiling:

   • Databricks: default 25 rows. Anything above 1000 is refused.
   • Snowflake: default 10 rows. Anything above 100 is reduced to 100.

   In both cases the bound actually used is reported in sample.row_limit.

3. The connection is resolved, and its connector must support sampling.

4. The server first runs a discovery on the source to find the dataset’s masked columns and row filter. This step is best-effort. If it fails, or the dataset is not in the listing (matching ignores case, and an empty qualifier matches any), the sample is still taken and sample.governance_checked is false.

5. Every part of the dataset name is checked against the identifier allowlist and quoted for the target warehouse. A name the allowlist refuses is refused with the reason. It is never escaped around.

What a sample does not establish:

• These rows are not the dataset. A null rate, a distinct count or a missing value over a sample says nothing about the table. sample.basis carries the sample size, and sample.caveats is never empty.
• A sample can be truthful and still unrepresentative. A masked column returns masked values, and a row filter silently removes rows. Show masked_columns, row_filter and governance_checked beside the rows.
• The sampling methods differ. A FIRST_ROWS read is the first rows the engine produced. On a time-clustered table, that is one slice of time.
• NULL, the empty string and the literal text “NULL” are three different cells. See SampleCell.

Request: SampleConnectionDatasetRequest

Response: SampleConnectionDatasetResponse

ListRunners

rpc ListRunners(ListRunnersRequest) returns (ListRunnersResponse);

• Kind: Unary.
• Auth: Bearer session. Service-account tokens are allowed.
• Errors: A storage failure is returned as the store’s error, which surfaces as UNKNOWN.

Returns three kinds of runner, in this order:

1. The managed runner. An entry named Runink Managed Runner is always listed first unless a stored runner already has that name. It has type CloudRun. Its state is RUNNING, with the forwarding endpoint, only when a live heartbeat from a managed runner is present in the replicated registry. Otherwise state is UNKNOWN. compute_units is 0, which means unknown: provisioned capacity is not metered.
2. Stored runners, registered with CreateRunner. These are returned exactly as stored, including their state string.
3. Self-enrolled runners that currently hold an open Enroll stream, scoped to the caller’s own tenant. Each has type Local, an empty endpoint (it has no address the control plane can dial), state RUNNING, an empty local_config, and a description that gives the time the stream opened, the time since the last message and the reported load. RUNNING here means that the stream is open. Nothing has probed the runner. These entries are not persisted and disappear when the stream closes.

Request: ListRunnersRequest

No fields.

Response: ListRunnersResponse

CreateRunner

rpc CreateRunner(CreateRunnerRequest) returns (CreateRunnerResponse);

• Kind: Unary.
• Auth: Bearer session. Service-account tokens are refused.
• Errors: None as gRPC status. Returns success: false (with no message) when the runner cannot be stored.

Stores a runner definition on the instance. The server generates runner_id. When runner.name is empty, the generated id is used as the name. When runner is omitted, a runner named Unknown is stored. A compute_units of 0 is stored as 1. Registering a runner dials nothing and does not check the endpoint.

Request: CreateRunnerRequest

Response: CreateRunnerResponse

GetRunnerHealth

rpc GetRunnerHealth(GetRunnerHealthRequest) returns (GetRunnerHealthResponse);

• Kind: Unary.
• Auth: Bearer session. Service-account tokens are refused.
• Errors: None.

Reports the health of the FACE server process that answers the call. It takes two CPU samples about 120 ms apart, so expect that much latency. Only some fields are measured. unmeasured names every field this build does not measure, and those fields are zero or empty. Show them as unknown, never as values. Currently request_rate, latency_p95, error_rate, raft_status, raft_index and active_nodes are always listed, and cpu_usage is listed as well when the host CPU cannot be sampled.

Request: GetRunnerHealthRequest

No fields.

Response: GetRunnerHealthResponse

ListResources

rpc ListResources(ListResourcesRequest) returns (ListResourcesResponse);

• Kind: Unary.
• Auth: Bearer session. Service-account tokens are refused.
• Errors: FAILED_PRECONDITION when the deployment’s bundled agent-resource catalogue is not available, which is a packaging fault and not an empty catalogue. INTERNAL when listing the catalogue fails part-way.

Lists the agent resources bundled with the deployment. These are JSON grammar files (type grammar) and prompt templates (type template). For a template, content is the extracted system prompt, not the raw template file. A template with no extractable system prompt is left out, and so is any resource that cannot be read.

Request: ListResourcesRequest

No fields.

Response: ListResourcesResponse

CreateDatabricksCluster

rpc CreateDatabricksCluster(CreateDatabricksClusterRequest) returns (CreateDatabricksClusterResponse);

• Kind: Unary.
• Auth: Bearer session. Service-account tokens are refused. It is refused with PERMISSION_DENIED on the LITE subscription tier, because the feature requires the Dedicated or Enterprise tier.
• Errors: When Databricks rejects the cluster-creation request itself, the call fails with that error, which surfaces as UNKNOWN. Every other failure (client setup, listing Spark versions or node types, choosing defaults, or the cluster failing to start) returns success: false with error_message.

Creates a cluster directly in the Databricks workspace at databricks_host, using databricks_token. The token is used for this call only and is not stored. The call waits until the cluster is running before it answers. Defaults:

• spark_version: the latest LTS runtime.
• node_type_id: the smallest node type with local disk.
• num_workers: 1 when 0.
• autotermination_minutes: 15 when 0.

Request: CreateDatabricksClusterRequest

Response: CreateDatabricksClusterResponse

RunDatabricksJob

rpc RunDatabricksJob(RunDatabricksJobRequest) returns (RunDatabricksJobResponse);

• Kind: Unary.
• Auth: Bearer session. Service-account tokens are refused.
• Errors: None as gRPC status. Returns success: false with error_message when the client cannot be created, the job cannot be created, the run cannot be started, or the run’s status cannot be obtained.

Creates a single-task notebook job in the Databricks workspace at databricks_host and runs it on existing_cluster_id. The call waits for the run to finish before it answers. The token is used for this call only and is not stored.

Request: RunDatabricksJobRequest

Response: RunDatabricksJobResponse

GetIntegrationConfig

rpc GetIntegrationConfig(GetIntegrationConfigRequest) returns (GetIntegrationConfigResponse);

• Kind: Unary.
• Auth: Bearer session. Service-account tokens are refused.
• Errors: INTERNAL when the integration settings cannot be read.

Returns the instance’s integration settings. No secret is ever returned. The Stripe secret key and the Google service-account credentials appear only as the booleans stripe_configured and google_credentials_configured. The response carries no prefix, suffix or length of either secret. An unset contact number is returned empty, and the server substitutes no default.

Request: GetIntegrationConfigRequest

No fields.

Response: GetIntegrationConfigResponse

Reserved: fields 1 (stripe_api_key) and 5 (google_credentials). They are never reused.

SetIntegrationConfig

rpc SetIntegrationConfig(SetIntegrationConfigRequest) returns (SetIntegrationConfigResponse);

• Kind: Unary.
• Auth: Bearer session. Service-account tokens are refused.
• Errors: None as gRPC status. Returns success: false with message when the current settings cannot be read or the new settings cannot be saved.

Saves the integration settings. Every non-secret field is a full replacement: an empty value clears it, and partners replaces the whole list. The two secrets work differently because they are write-only. An empty or blank value keeps the stored secret, a non-blank value (trimmed) replaces it, and only the matching remove_* flag erases it. A client can therefore load the settings, change a phone number and save them without resending, or accidentally erasing, the secrets it never received. On success message is “Configuration saved successfully”.

Request: SetIntegrationConfigRequest

Response: SetIntegrationConfigResponse

RunnerEnrollmentService

Full name semantics.v1.RunnerEnrollmentService.

This is outbound runner enrolment. A runner that the control plane cannot reach, because it is behind NAT or on a network the control plane cannot address, dials out, holds one stream open and receives fetch work down that same stream. An enrolled runner is not a mesh peer. It holds no mesh certificate, takes no part in consensus and receives no replicated state. Everything it needs travels in the assignment.

Enroll

rpc Enroll(stream EnrollRequest) returns (stream EnrollResponse);

• Kind: Bidirectional streaming. This needs native gRPC over HTTP/2. Browser gRPC-web cannot carry it.
• Auth: Bearer token in the stream metadata, and it must be a service-account token. An org admin mints one for their own tenant with IdentityService/GenerateServiceAccountKey (see Identity). A user’s session token cannot enrol a runner, including an admin’s. A client certificate alone is not enough.
• Errors:
  • PERMISSION_DENIED: the token is not a service-account token, or the session carries no verified tenant.
  • INVALID_ARGUMENT: the stream closed before a first message, the first message is not a hello, a second hello arrives on an established stream, or a message of an unrecognised kind arrives.

Protocol:

1. The runner opens the stream and sends EnrollRequest{hello} first. Anything else is refused and nothing is registered.
2. The server registers the runner under the caller’s verified tenant and answers EnrollResponse{accepted}.
3. The runner sends heartbeat messages with its current load, and the server may send assignment messages at any time. Each assignment carries a dispatch_id and a RunFetchRequest. The runner answers with EnrollRequest{result}, quoting the same dispatch_id. A result whose dispatch_id matches no in-flight dispatch is dropped.
4. Closing the stream, whether by a clean end, cancellation or a transport error, de-registers the runner. There is no separate deregistration call. When the stream ends, the server closes its side without an error.

Behaviour worth knowing:

• Registration key. The server sanitises runner_id: it keeps only letters, digits, -, _ and ., and caps the id at 64 characters. If nothing survives, the server generates an id. The runner is keyed by (verified tenant, id), so it cannot collide with or impersonate another tenant’s runner. If a new stream enrols with an id that is already held in the same tenant, the new stream takes over the registration (last writer wins). This lets a restarted runner reclaim its slot.
• Claims are not verified. name, version and capabilities are the runner’s own statements. Nothing probes the runner, checks its build or refuses an old version, and there is no approval step.
• How work arrives. When FetchService/RunFetch runs for a tenant that has enrolled runners, the fetch goes down one of their streams. A runner_id that names an enrolled runner selects that runner and is never redirected. With no runner_id, the least-loaded enrolled runner is chosen. With no matching enrolled runner, the platform uses its normal path. If the result carries error, the fetch fails with INTERNAL. If it carries neither error nor fetch, that is a protocol fault and is reported as INTERNAL. If the runner does not answer within 10 minutes, the fetch returns DEADLINE_EXCEEDED, and the run may still be in progress on the runner. A runner that disconnects before the work is sent causes UNAVAILABLE. See Fetch for RunFetchRequest and RunFetchResponse.
• Visibility. An enrolled runner appears in ListRunners for its tenant only, and only while the stream is open.
• Heartbeats are advisory. The server advises an interval of 15 seconds but evicts nobody for missing heartbeats. Only the stream closing de-registers a runner.

Request stream: EnrollRequest

Response stream: EnrollResponse

Messages

Connection

A stored connection. Exactly one member of the config oneof is set. For a given type it is the member listed in Connection types and credential keys. Secret-valued fields inside the config message are accepted on create, moved to the credential store and always empty on read.

Connection types and credential keys

Put credentials in CreateConnectionRequest.credentials under these keys. Fields in the table that are marked secret are also accepted on the config message and moved into the credential bundle. Types marked “none” need no secret. Their credential_state is NONE_NEEDED, which is a normal state.

ExcelConnectionConfig

SharePointConnectionConfig

MySqlConnectionConfig

PostgresConnectionConfig

BigQueryConnectionConfig

DatabricksConnectionConfig

The runner-deploy settings are all optional and none of them is secret. When set, each is checked for format on create, and a value that looks like a credential is refused.

SnowflakeConnectionConfig

The runner-deploy settings are all optional and none of them is secret. When set, each is checked for format on create.

HubspotConnectionConfig

SalesforceConnectionConfig

GuidewireConnectionConfig

SAPConnectionConfig

InventoryConnectionConfig

Used by both inventory and ims.

OMSConnectionConfig

WHSConnectionConfig

TMSConnectionConfig

YMSConnectionConfig

IoTConnectionConfig

CctvConnectionConfig

A video feed that the CCTV extractor samples frames from.

DocumentConnectionConfig

ObjectStoreConnectionConfig

A customer’s own bucket: GCS, S3 (or any S3-compatible endpoint) or Azure Blob. This message has no credential fields. Credentials go in the credentials map.

D365ConnectionConfig

ServiceNowConnectionConfig

MQTTConnectionConfig

A sensor bus: the broker that pallet probes, reefer controllers and dock readers publish to. This message has no secret fields. The password goes in credentials["password"].

RFIDConnectionConfig

A pallet or case reader: a dock-door portal, handheld sled or conveyor tunnel.

GPSConnectionConfig

Vehicle or trailer position and the sensor channels attached to it.

SensorGatewayConnectionConfig

A fixed probe or camera on a gateway: temperature, infrared, humidity or shock channels.

SensorChannel

One physical measurement mapped onto one register or path, with its scaling stated.

LogisticsAPIConnectionConfig

The shared shape for the OMS, WMS, WHS, YMS, TMS and IMS system-of-record connectors. This message has no secret fields. The API key, bearer token, basic-auth password or OAuth2 client secret goes in credentials.

KafkaConnectionConfig

An event bus reached over the Kafka wire protocol. The brokers publish topic names, partitions and replicas but no schema. Field structure comes from a separate Schema Registry, if there is one. This message has no secret fields. The SASL password goes in credentials["password"] and the registry password in credentials["schema_registry_password"].

Runner

A runner definition. Stored runners are returned exactly as they were created.

LocalRunnerConfig

CloudRunRunnerConfig

SnowflakeRunnerConfig

DatabricksRunnerConfig

ContainerDeploymentConfig

Resource

Partner

SourceDescription

A source’s answer to “what is behind this connection”. Figures that could be defaulted travel with a *_stated boolean, and figures that claim to measure something travel with a *_basis string. Always read the pair together. No confidences, most-common values, histograms or example rows are ever carried.

DescribedDataset

One table, object type, topic, sheet, endpoint or stream within a source.

DescribedColumn

DiscoveryAspect

One question asked of the source’s catalogue, and what came back.

DeclaredRelationship

A constraint that the source declares. It says how the schema’s author meant the tables to join. It is not evidence that any row satisfies it.

DatasetSample

A bounded read of real rows. This is the only message on this page that carries customer content. Never present it as the dataset.

SampleRow

SampleCell

Keeps NULL distinguishable from the empty string and from the literal text “NULL”. Render is_null in a way that an empty value cannot produce.

RunnerHello

RunnerHeartbeat

RunnerWorkResult

EnrollmentAccepted

RunnerWorkAssignment

Enums

CredentialState

What this instance knows about a connection’s credential bundle, computed without dialling anything. This is a different question from TestConnection, and the two should be shown as separate marks.

SourceBacking

What stands behind a connection on this instance. Computed from the connection’s address, never from its name, and without dialling anything. This is a different question from environment.

DeleteConnectionOutcome