fix: align workspace diagnostic contracts
This commit is contained in:
@@ -19,7 +19,8 @@ belongs in the descriptor, this document, a generated `.env.example`, or diagnos
|
||||
fragment. The client may use only the declared method, path, auth mode, and response-field names.
|
||||
- `auth: none` sends no credential; `auth: bearer` reads a local file and sends
|
||||
`Authorization: Bearer <file-content>`; `auth: x-api-key` sends `x-api-key: <file-content>`.
|
||||
The file content is never logged or returned.
|
||||
The resolver does not require or read an API-key file for an `auth: none` diagnostic. File
|
||||
content is never logged or returned.
|
||||
|
||||
## Canonical descriptor additions
|
||||
|
||||
@@ -55,6 +56,7 @@ diagnostics:
|
||||
method: POST
|
||||
path: /vector/diagnostic-probe
|
||||
auth: bearer
|
||||
response: { operation: operation }
|
||||
embedding:
|
||||
method: GET
|
||||
path: /models
|
||||
@@ -63,8 +65,9 @@ diagnostics:
|
||||
```
|
||||
|
||||
`diagnostics.dwh_rest` requires DWH `rest_api`; `diagnostics.vector_rest` requires vector
|
||||
`rest_api`. `reversible_probe` is optional, but when present it must be `POST`. Response-map
|
||||
values are JSON object field names, not values to be put in Git.
|
||||
`rest_api`. `reversible_probe` is optional, but when present it must be authenticated `POST` and
|
||||
declare the response field that echoes the requested `operation`. Response-map values are JSON
|
||||
object field names, not values to be put in Git.
|
||||
|
||||
## Installation-local variable contract
|
||||
|
||||
@@ -77,11 +80,11 @@ approved local secret root; it is never the secret itself.
|
||||
| --- | --- |
|
||||
| DWH selection | `THT_WS_<NAMESPACE>_DWH_TRANSPORT` |
|
||||
| DWH `postgres_direct` | `THT_WS_<NAMESPACE>_DWH_HOST`, `THT_WS_<NAMESPACE>_DWH_PORT`, `THT_WS_<NAMESPACE>_DWH_USER`, `THT_WS_<NAMESPACE>_DWH_PASSWORD_FILE`; optional `THT_WS_<NAMESPACE>_DWH_TLS_CA_FILE` |
|
||||
| DWH `rest_api` | `THT_WS_<NAMESPACE>_DWH_BASE_URL`, `THT_WS_<NAMESPACE>_DWH_API_KEY_FILE`; optional `THT_WS_<NAMESPACE>_DWH_TLS_CA_FILE` |
|
||||
| DWH `rest_api` | `THT_WS_<NAMESPACE>_DWH_BASE_URL`; `THT_WS_<NAMESPACE>_DWH_API_KEY_FILE` only for `bearer`/`x-api-key`; optional `THT_WS_<NAMESPACE>_DWH_TLS_CA_FILE` |
|
||||
| DWH `ssh_tunnel` | `THT_WS_<NAMESPACE>_DWH_USER`, `THT_WS_<NAMESPACE>_DWH_PASSWORD_FILE`, `THT_WS_<NAMESPACE>_DWH_SSH_HOST`, `THT_WS_<NAMESPACE>_DWH_SSH_PORT`, `THT_WS_<NAMESPACE>_DWH_SSH_USER`, `THT_WS_<NAMESPACE>_DWH_SSH_PRIVATE_KEY_FILE`, `THT_WS_<NAMESPACE>_DWH_SSH_KNOWN_HOSTS_FILE`, `THT_WS_<NAMESPACE>_DWH_SSH_TARGET_HOST`, `THT_WS_<NAMESPACE>_DWH_SSH_TARGET_PORT`; optional `THT_WS_<NAMESPACE>_DWH_TLS_CA_FILE` |
|
||||
| Vector selection | `THT_WS_<NAMESPACE>_VECTOR_TRANSPORT` |
|
||||
| Vector `pgvector_direct` | `THT_WS_<NAMESPACE>_VECTOR_HOST`, `THT_WS_<NAMESPACE>_VECTOR_PORT`, `THT_WS_<NAMESPACE>_VECTOR_USER`, `THT_WS_<NAMESPACE>_VECTOR_PASSWORD_FILE`; optional `THT_WS_<NAMESPACE>_VECTOR_TLS_CA_FILE` |
|
||||
| Vector `rest_api` | `THT_WS_<NAMESPACE>_VECTOR_BASE_URL`, `THT_WS_<NAMESPACE>_VECTOR_API_KEY_FILE`; optional `THT_WS_<NAMESPACE>_VECTOR_TLS_CA_FILE` |
|
||||
| Vector `rest_api` | `THT_WS_<NAMESPACE>_VECTOR_BASE_URL`; `THT_WS_<NAMESPACE>_VECTOR_API_KEY_FILE` only for `bearer`/`x-api-key`; optional `THT_WS_<NAMESPACE>_VECTOR_TLS_CA_FILE` |
|
||||
| Vector `ssh_tunnel` | `THT_WS_<NAMESPACE>_VECTOR_USER`, `THT_WS_<NAMESPACE>_VECTOR_PASSWORD_FILE`, `THT_WS_<NAMESPACE>_VECTOR_SSH_HOST`, `THT_WS_<NAMESPACE>_VECTOR_SSH_PORT`, `THT_WS_<NAMESPACE>_VECTOR_SSH_USER`, `THT_WS_<NAMESPACE>_VECTOR_SSH_PRIVATE_KEY_FILE`, `THT_WS_<NAMESPACE>_VECTOR_SSH_KNOWN_HOSTS_FILE`, `THT_WS_<NAMESPACE>_VECTOR_SSH_TARGET_HOST`, `THT_WS_<NAMESPACE>_VECTOR_SSH_TARGET_PORT`; optional `THT_WS_<NAMESPACE>_VECTOR_TLS_CA_FILE` |
|
||||
| Optional vector writer | `THT_WS_<NAMESPACE>_VECTOR_WRITER_API_KEY_FILE` |
|
||||
| Embedding service | `THT_WS_<NAMESPACE>_EMBEDDING_BASE_URL`; optional `THT_WS_<NAMESPACE>_EMBEDDING_API_KEY_FILE`, `THT_WS_<NAMESPACE>_EMBEDDING_TLS_CA_FILE` |
|
||||
@@ -110,6 +113,10 @@ SELECT current_database() AS database, current_schema() AS schema
|
||||
|
||||
Both returned values must equal the descriptor's DWH database and schema.
|
||||
|
||||
`*_TLS_CA_FILE` is optional for direct and SSH PostgreSQL diagnostics. When provided, it is used
|
||||
with certificate verification; when absent, the native client still requires a valid certificate
|
||||
chain from the runtime system trust store. Absence never disables TLS verification.
|
||||
|
||||
For REST, the descriptor above declares the exact ping:
|
||||
|
||||
```text
|
||||
@@ -134,6 +141,9 @@ identity. They inspect the declared collection's vector column and index and mus
|
||||
collection, integer `dimensions`, and `distance` (`cosine`, `l2`, or `inner_product`) declared in
|
||||
`semantic_index.vector_store`.
|
||||
|
||||
Their optional `*_TLS_CA_FILE` follows the same verified private-CA-or-system-trust rule as the
|
||||
DWH diagnostic.
|
||||
|
||||
For REST, the exact descriptor-declared request is, for example:
|
||||
|
||||
```text
|
||||
@@ -152,7 +162,8 @@ Ordinary validation is reader-only. A write probe runs only when all of the foll
|
||||
|
||||
1. The operator explicitly requests it.
|
||||
2. The descriptor has `semantic_index.vector_writer: {}`.
|
||||
3. The descriptor declares `diagnostics.vector_rest.reversible_probe`.
|
||||
3. The descriptor declares an authenticated `diagnostics.vector_rest.reversible_probe` with an
|
||||
`operation` response field.
|
||||
4. The selected vector transport is `rest_api`.
|
||||
5. `THT_WS_<NAMESPACE>_VECTOR_WRITER_API_KEY_FILE` exists locally and is distinct from the reader
|
||||
API-key file.
|
||||
@@ -169,8 +180,9 @@ then:
|
||||
{ "operation": "remove", "id": "diagnostic:<same UUID>", "collection": "<declared collection>" }
|
||||
```
|
||||
|
||||
Both requests require a 2xx response. Cleanup is attempted in `finally`, including after a write
|
||||
timeout or error. The endpoint must implement both operations as a bounded, reversible diagnostic
|
||||
Both requests require a 2xx JSON response whose declared `operation` field equals the requested
|
||||
`create` or `remove` operation. Cleanup is attempted in `finally`, including after a write timeout
|
||||
or error. The endpoint must implement both operations as a bounded, reversible diagnostic
|
||||
operation; an upsert-only endpoint is prohibited. It must not retain, index, or expose diagnostic
|
||||
records. If the writer capability or its local binding is absent, validation remains reader-only
|
||||
and no write request is sent.
|
||||
|
||||
Reference in New Issue
Block a user