mptyl/ThothII
1
0
Fork 0
Code Issues 25 Pull Requests Actions Packages Projects Releases 1 Wiki Activity

fix: harden workspace schema contracts

Browse Source
This commit is contained in:
marcopan
2026-08-03 21:40:58 +02:00
parent 92cb0545be
commit 5a654939a5
4 changed files with 152 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files
backend/src/workspaces/contracts.ts
+51 -13
View File
@@ -1,3 +1,4 @@
import { validateCanonicalWorkspace } from "./schema.js";
import type { CanonicalWorkspace, DwhTransport, VectorTransport } from "./schema.js";
export type InstallationRole = "DWH" | "VECTOR" | "EMBEDDING";
@@ -34,15 +35,24 @@ export interface InstallationContract {
variables: InstallationVariable[];
}
const CONNECTOR_SUFFIXES: readonly InstallationSuffix[] = [
"TRANSPORT",
const DIRECT_SUFFIXES: readonly InstallationSuffix[] = [
"HOST",
"PORT",
"BASE_URL",
"USER",
"PASSWORD_FILE",
"TLS_CA_FILE",
];
const REST_SUFFIXES: readonly InstallationSuffix[] = [
"BASE_URL",
"API_KEY_FILE",
"TLS_CA_FILE",
];
const SSH_SUFFIXES: readonly InstallationSuffix[] = [
"USER",
"PASSWORD_FILE",
"TLS_CA_FILE",
"SSH_HOST",
"SSH_PORT",
"SSH_USER",
@@ -82,21 +92,46 @@ function connectorVariables(
role: "DWH" | "VECTOR",
transports: readonly ConnectorTransport[],
): InstallationVariable[] {
return CONNECTOR_SUFFIXES.map((suffix) => createVariable(namespace, role, suffix, transports));
const suffixTransports = new Map<InstallationSuffix, ConnectorTransport[]>();
const add = (suffixes: readonly InstallationSuffix[], transport: ConnectorTransport) => {
for (const suffix of suffixes) {
const applicable = suffixTransports.get(suffix) ?? [];
applicable.push(transport);
suffixTransports.set(suffix, applicable);
}
};
for (const transport of transports) {
if (transport === "postgres_direct" || transport === "pgvector_direct") {
add(DIRECT_SUFFIXES, transport);
} else if (transport === "rest_api") {
add(REST_SUFFIXES, transport);
} else {
add(SSH_SUFFIXES, transport);
}
}
return [
createVariable(namespace, role, "TRANSPORT", transports),
...[...suffixTransports.entries()].map(([suffix, applicable]) => (
createVariable(namespace, role, suffix, applicable)
)),
];
}
export function buildInstallationContract(workspace: CanonicalWorkspace): InstallationContract {
const namespace = namespaceFor(workspace);
const canonical = validateCanonicalWorkspace(workspace);
const namespace = namespaceFor(canonical);
return {
workspaceId: workspace.workspace.id,
workspaceId: canonical.workspace.id,
namespace,
variables: [
...connectorVariables(namespace, "DWH", workspace.dwh.supported_transports),
...connectorVariables(namespace, "DWH", canonical.dwh.supported_transports),
...connectorVariables(
namespace,
"VECTOR",
workspace.semantic_index.vector_store.supported_transports,
canonical.semantic_index.vector_store.supported_transports,
),
...EMBEDDING_SUFFIXES.map((suffix) => createVariable(namespace, "EMBEDDING", suffix)),
],
@@ -110,7 +145,8 @@ function localizedIntroduction(workspace: CanonicalWorkspace): string {
}
export function renderWorkspaceDocs(workspace: CanonicalWorkspace): { envExample: string; markdown: string } {
const contract = buildInstallationContract(workspace);
const canonical = validateCanonicalWorkspace(workspace);
const contract = buildInstallationContract(canonical);
const variablesByRole = new Map<InstallationRole, InstallationVariable[]>();
for (const variable of contract.variables) {
const variables = variablesByRole.get(variable.role) ?? [];
@@ -119,7 +155,7 @@ export function renderWorkspaceDocs(workspace: CanonicalWorkspace): { envExample
}
const envExample = [
`# Generated installation bindings for ${workspace.workspace.id}`,
`# Generated installation bindings for ${canonical.workspace.id}`,
"# Provide secret file paths only; never paste secret values here.",
...contract.variables.map((variable) => `${variable.name}=`),
"",
@@ -128,16 +164,18 @@ export function renderWorkspaceDocs(workspace: CanonicalWorkspace): { envExample
const markdown = [
"# Installation requirements",
"",
`**Workspace:** ${workspace.workspace.name}`,
`**Workspace:** ${canonical.workspace.name}`,
"",
localizedIntroduction(workspace),
localizedIntroduction(canonical),
"",
"Use the following UI fields as installation bindings. Secret fields always contain file paths, never secret values.",
"",
...(["DWH", "VECTOR", "EMBEDDING"] as const).flatMap((role) => [
`## ${role === "DWH" ? "Data warehouse" : role === "VECTOR" ? "Vector store" : "Embedding service"}`,
"",
...(variablesByRole.get(role) ?? []).map((variable) => `- \`${variable.name}\``),
...(variablesByRole.get(role) ?? []).map((variable) => (
`- \`${variable.name}\`${variable.transports ? ` (for: ${variable.transports.join(", ")})` : ""}`
)),
"",
]),
].join("\n");
backend/src/workspaces/schema.ts
+18 -2
View File
@@ -19,6 +19,8 @@ export interface CanonicalWorkspace {
engine: "postgres";
database: string;
schema: string;
port?: number;
timeout_ms?: number;
supported_transports: DwhTransport[];
};
semantic_index: {
@@ -27,12 +29,15 @@ export interface CanonicalWorkspace {
collection: string;
dimensions: number;
distance: "cosine" | "l2" | "inner_product";
port?: number;
timeout_ms?: number;
supported_transports: VectorTransport[];
};
embedding: {
provider: "ollama_compatible" | "openai_compatible";
model: string;
dimensions: number;
timeout_ms?: number;
};
};
llm_policy: {
@@ -48,6 +53,8 @@ const identifier = z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/, {
message: "database identifiers must start with a letter or underscore",
});
const dimensions = z.number().int().positive().max(32_768);
const port = z.number().int().min(1).max(65_535);
const timeoutMs = z.number().int().positive();
const modelReference = z.string().regex(/^[^/\s]+\/[^/\s]+$/, {
message: "model must use provider/model syntax",
});
@@ -70,6 +77,8 @@ const WorkspaceSchema = z.object({
engine: z.literal("postgres"),
database: identifier,
schema: identifier,
port: port.optional(),
timeout_ms: timeoutMs.optional(),
supported_transports: z.array(z.enum(DWH_TRANSPORTS)).min(1),
}).strict(),
semantic_index: z.object({
@@ -78,12 +87,15 @@ const WorkspaceSchema = z.object({
collection: identifier,
dimensions,
distance: z.enum(["cosine", "l2", "inner_product"]),
port: port.optional(),
timeout_ms: timeoutMs.optional(),
supported_transports: z.array(z.enum(VECTOR_TRANSPORTS)).min(1),
}).strict(),
embedding: z.object({
provider: z.enum(["ollama_compatible", "openai_compatible"]),
model: z.string().trim().min(1),
dimensions,
timeout_ms: timeoutMs.optional(),
}).strict(),
}).strict(),
llm_policy: z.object({
@@ -127,11 +139,15 @@ export function parseWorkspaceYaml(source: string): CanonicalWorkspace {
throw new Error(`Invalid workspace YAML: ${document.errors.map((error) => error.message).join("; ")}`);
}
return WorkspaceSchema.parse(document.toJSON()) as CanonicalWorkspace;
return validateCanonicalWorkspace(document.toJSON());
}
export function validateCanonicalWorkspace(workspace: unknown): CanonicalWorkspace {
return WorkspaceSchema.parse(workspace) as CanonicalWorkspace;
}
export function serializeWorkspaceYaml(workspace: CanonicalWorkspace): string {
const canonical = WorkspaceSchema.parse(workspace) as CanonicalWorkspace;
const canonical = validateCanonicalWorkspace(workspace);
return stringify(canonical, { lineWidth: 0, sortMapEntries: true });
}