fix: align workspace diagnostic contracts
This commit is contained in:
@@ -163,6 +163,7 @@ diagnostics:
|
||||
method: POST
|
||||
path: /vector/diagnostic-probe
|
||||
auth: bearer
|
||||
response: { operation: operation }
|
||||
embedding:
|
||||
method: GET
|
||||
path: /models
|
||||
@@ -219,7 +220,8 @@ the model/dimensions response fields. Only `GET` and `POST`, `none`/`bearer`/`x-
|
||||
authentication, origin-relative paths without a query or fragment, and identifier-shaped response
|
||||
field names are accepted.
|
||||
|
||||
`vector_rest.reversible_probe`, when present, is POST-only. It is called with a generated
|
||||
`vector_rest.reversible_probe`, when present, is an authenticated POST with a declared response
|
||||
field that must echo each requested `create`/`remove` operation. It is called with a generated
|
||||
diagnostic record create request and a matching remove request, with cleanup retried in `finally`.
|
||||
An upsert-only service cannot be declared as this probe. All ordinary diagnostics remain read-only.
|
||||
The complete request, response, timeout, reader-only fallback, SSH, and private-CA limitations are
|
||||
@@ -310,7 +312,10 @@ Transport behavior is encapsulated behind connector adapters.
|
||||
|
||||
### 8.1 Direct
|
||||
|
||||
Direct adapters connect to the configured host and port with the native protocol. PostgreSQL direct access supports TLS modes and CA files. Vector direct access uses the native vector-store protocol or database driver.
|
||||
Direct adapters connect to the configured host and port with the native protocol. PostgreSQL
|
||||
direct access uses a supplied CA file when present and otherwise requires runtime system trust;
|
||||
certificate verification is never disabled. Vector direct access uses the native vector-store
|
||||
protocol or database driver.
|
||||
|
||||
### 8.2 REST API
|
||||
|
||||
@@ -323,7 +328,9 @@ trusted TLS-termination boundary.
|
||||
|
||||
### 8.3 SSH tunnel
|
||||
|
||||
SSH adapters verify the remote host against an explicit known-hosts file, open a temporary local tunnel, and pass the resulting endpoint to the corresponding direct adapter. Host-key checking cannot be disabled by the form.
|
||||
SSH adapters verify the remote host against an explicit known-hosts file, open a temporary local
|
||||
tunnel, and pass the resulting endpoint to the corresponding direct adapter, including its
|
||||
verified private-CA-or-system-trust policy. Host-key checking cannot be disabled by the form.
|
||||
|
||||
Transport selection is installation-specific because a production server may connect directly while a laptop reaches the same logical resource through REST or SSH.
|
||||
|
||||
@@ -592,6 +599,8 @@ Legacy sessions without workspace revision use the existing compatibility resolu
|
||||
- Git SSH uses explicit known-hosts verification.
|
||||
- REST and direct TLS validation cannot be disabled silently.
|
||||
- Diagnostics sanitize provider errors before returning them to the browser.
|
||||
- `auth: none` diagnostics neither require nor read an API-key file; authenticated REST
|
||||
diagnostics still require the declared local secret file.
|
||||
- Production CORS remains same-origin; absence of embedded authentication does not imply cross-origin write access.
|
||||
- The first release allows every user who can access the ThothII application to publish workspace changes. This limitation is documented until an authorization layer is introduced.
|
||||
|
||||
|
||||
@@ -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