mirror of https://github.com/trustgraph-ai/trustgraph.git synced 2026-04-25 00:16:23 +02:00

cybermaggedon d35473f7f7 feat: workspace-based multi-tenancy, replacing user as tenancy axis (#840 ) Introduces `workspace` as the isolation boundary for config, flows, library, and knowledge data. Removes `user` as a schema-level field throughout the code, API specs, and tests; workspace provides the same separation more cleanly at the trusted flow.workspace layer rather than through client-supplied message fields. Design ------ - IAM tech spec (docs/tech-specs/iam.md) documents current state, proposed auth/access model, and migration direction. - Data ownership model (docs/tech-specs/data-ownership-model.md) captures the workspace/collection/flow hierarchy. Schema + messaging ------------------ - Drop `user` field from AgentRequest/Step, GraphRagQuery, DocumentRagQuery, Triples/Graph/Document/Row EmbeddingsRequest, Sparql/Rows/Structured QueryRequest, ToolServiceRequest. - Keep collection/workspace routing via flow.workspace at the service layer. - Translators updated to not serialise/deserialise user. API specs --------- - OpenAPI schemas and path examples cleaned of user fields. - Websocket async-api messages updated. - Removed the unused parameters/User.yaml. Services + base --------------- - Librarian, collection manager, knowledge, config: all operations scoped by workspace. Config client API takes workspace as first positional arg. - `flow.workspace` set at flow start time by the infrastructure; no longer pass-through from clients. - Tool service drops user-personalisation passthrough. CLI + SDK --------- - tg-init-workspace and workspace-aware import/export. - All tg-* commands drop user args; accept --workspace. - Python API/SDK (flow, socket_client, async_, explainability, library) drop user kwargs from every method signature. MCP server ---------- - All tool endpoints drop user parameters; socket_manager no longer keyed per user. Flow service ------------ - Closure-based topic cleanup on flow stop: only delete topics whose blueprint template was parameterised AND no remaining live flow (across all workspaces) still resolves to that topic. Three scopes fall out naturally from template analysis: {id} -> per-flow, deleted on stop * {blueprint} -> per-blueprint, kept while any flow of the same blueprint exists * {workspace} -> per-workspace, kept while any flow in the workspace exists * literal -> global, never deleted (e.g. tg.request.librarian) Fixes a bug where stopping a flow silently destroyed the global librarian exchange, wedging all library operations until manual restart. RabbitMQ backend ---------------- - heartbeat=60, blocked_connection_timeout=300. Catches silently dead connections (broker restart, orphaned channels, network partitions) within ~2 heartbeat windows, so the consumer reconnects and re-binds its queue rather than sitting forever on a zombie connection. Tests ----- - Full test refresh: unit, integration, contract, provenance. - Dropped user-field assertions and constructor kwargs across ~100 test files. - Renamed user-collection isolation tests to workspace-collection.		2026-04-21 23:23:01 +01:00
..
api	feat: workspace-based multi-tenancy, replacing user as tenancy axis (#840 )	2026-04-21 23:23:01 +01:00
ontology	Add agent explainability instrumentation and unify envelope field naming (#795 )	2026-04-13 16:16:42 +01:00
websocket	feat: workspace-based multi-tenancy, replacing user as tenancy axis (#840 )	2026-04-21 23:23:01 +01:00
build-docs.sh	Update API specs for 2.1 (#699 )	2026-03-17 20:36:31 +00:00
README.md	Add AsyncAPI spec for websocket (#613 )	2026-01-15 11:57:16 +00:00

README.md

TrustGraph API Specifications

This directory contains formal specifications for the TrustGraph API Gateway.

Directory Structure

specs/
├── api/              # OpenAPI 3.1.0 specification for REST API
│   ├── openapi.yaml  # Main entry point
│   ├── paths/        # Endpoint definitions
│   ├── components/   # Reusable schemas, responses, parameters
│   └── security/     # Security scheme definitions
│
├── websocket/        # AsyncAPI 3.0.0 specification for WebSocket API
│   ├── asyncapi.yaml # Main entry point
│   ├── channels/     # Channel definitions
│   ├── components/   # Message and schema definitions
│   └── STREAMING.md  # Streaming patterns documentation
│
└── README.md         # This file

Specifications

REST API (OpenAPI 3.1.0)

Location: specs/api/openapi.yaml

The REST API specification documents:

5 Global Services: config, flow, librarian, knowledge, collection-management
16 Flow-Hosted Services: agent, RAG, embeddings, queries, loading, tools
Import/Export: Bulk data operations
Metrics: Prometheus monitoring

Features:

Modular structure with $ref to external files
Comprehensive request/response schemas
Authentication via Bearer tokens
Field naming in kebab-case

WebSocket API (AsyncAPI 3.0.0)

Location: specs/websocket/asyncapi.yaml

The WebSocket API specification documents:

Multiplexed async communication protocol
Request/response message envelopes with ID correlation
All services accessible via single WebSocket connection
Streaming response patterns

Features:

References REST API schemas (single source of truth)
Message-based routing (service + optional flow parameters)
Comprehensive streaming documentation
Full async/multiplexing behavior

Building Documentation

Prerequisites

npm install -g @redocly/cli @asyncapi/cli

Or use npx (no installation required).

Generate REST API Documentation

Using Redocly (HTML):

cd specs/api
npx @redocly/cli build-docs openapi.yaml -o ../../docs/api.html

Preview in browser:

cd specs/api
npx @redocly/cli preview-docs openapi.yaml

Opens interactive documentation at http://localhost:8080

Validate:

cd specs/api
npx @redocly/cli lint openapi.yaml

Generate WebSocket API Documentation

Using AsyncAPI (HTML):

cd specs/websocket
npx -p @asyncapi/cli asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template@3.0.0 --use-new-generator -o /tmp/asyncapi-build -p singleFile=true --force-write
mv /tmp/asyncapi-build/index.html ../../docs/websocket.html
rm -rf /tmp/asyncapi-build

Notes:

The generator must run from the specs/websocket directory to properly resolve relative $ref paths to OpenAPI schemas
--use-new-generator flag enables generator v2 compatibility
-p singleFile=true parameter generates a single standalone HTML file

Validate:

cd specs/websocket
npx @asyncapi/cli validate asyncapi.yaml

Build All Documentation

Use the provided build script:

./specs/build-docs.sh

This generates:

docs/api.html - REST API documentation
docs/websocket.html - WebSocket API documentation

Viewing Documentation

After building:

REST API:

xdg-open docs/api.html
# or
firefox docs/api.html

WebSocket API:

xdg-open docs/websocket.html
# or
firefox docs/websocket.html

Schema Reuse

The WebSocket API specification references the REST API schemas using relative paths:

# In specs/websocket/components/messages/requests/AgentRequest.yaml
request:
  $ref: '../../../../api/components/schemas/agent/AgentRequest.yaml'

This ensures:

Single source of truth for all schemas
Consistency between REST and WebSocket APIs
Easy maintenance - update schemas in one place

Validation Status

Both specifications are validated and error-free:

✅ OpenAPI: Validated with Redocly CLI
✅ AsyncAPI: Validated with AsyncAPI CLI

Maintenance

Adding a New Service

Create schemas in specs/api/components/schemas/{service-name}/
- {ServiceName}Request.yaml
- {ServiceName}Response.yaml
Create path definition in specs/api/paths/ or specs/api/paths/flow/
Add path to main spec in specs/api/openapi.yaml
Create WebSocket message in specs/websocket/components/messages/requests/
- Reference the OpenAPI request schema
Add to ServiceRequest message in specs/websocket/components/messages/ServiceRequest.yaml

Validate both specs:

cd specs/api && npx @redocly/cli lint openapi.yaml
cd specs/websocket && npx @asyncapi/cli validate asyncapi.yaml

Modifying an Existing Service

Update schema in specs/api/components/schemas/{service-name}/
Changes automatically apply to WebSocket spec via $ref
Validate both specs to ensure consistency

Tools and Resources

OpenAPI Tools:

Redocly CLI - Linting, docs generation
Swagger Editor - Online editor
OpenAPI Generator - Client/server code generation

AsyncAPI Tools:

AsyncAPI CLI - Validation, docs generation
AsyncAPI Studio - Online editor
AsyncAPI Generator - Template-based generation

Online Validators:

OpenAPI: https://editor.swagger.io/
AsyncAPI: https://studio.asyncapi.com/

API Version

Current version: 1.8.0

Version is specified in both:

specs/api/openapi.yaml → info.version
specs/websocket/asyncapi.yaml → info.version

Update both when releasing a new API version.