52 lines
2.4 KiB
Markdown
52 lines
2.4 KiB
Markdown
# Connectors
|
|
|
|
## V1
|
|
|
|
### Upload
|
|
Menselijke of API-upload. Vereist filename, content length en target space. Upload is nooit automatisch trusted.
|
|
|
|
### Read-only folder
|
|
Scant een expliciet gemounte root. Path traversal en symlinks buiten root worden geweigerd. De connector schrijft nooit naar de bronmap.
|
|
|
|
### Git repository
|
|
Leest een pinned commit/ref uit lokale checkout of toegestane remote. Registreert repository, commit, path en language. Secrets/binaries worden uitgesloten volgens policy.
|
|
|
|
### Website/sitemap
|
|
Optioneel late V1. Alleen expliciet toegestane domains, robots/politeness, size/time limits en SSRF-beveiligde fetcher.
|
|
|
|
## Connector contract
|
|
|
|
`scan(cursor) -> items + next_cursor`; `acquire(item) -> byte stream + metadata`; `fingerprint(item)`. Connectors bevatten geen parsing- of publicationlogica.
|
|
|
|
## Deletion semantics
|
|
|
|
Een volledige succesvolle scan mag ontbrekende items als source-deleted markeren. Een partiële/mislukte scan mag nooit massaal verwijderen.
|
|
|
|
## Source Registry en synchronisatie (1.2.0)
|
|
|
|
Iedere bron is een persistent record in `content.sources` (id, workspace, knowledge
|
|
space, naam, type, status, secret-vrije configuratie, sync-state, laatste sync,
|
|
laatste succesvolle sync, laatste revisie). Iedere ingest registreert zijn bron
|
|
bij eerste gebruik; ad-hoc uploads zonder `source_id` horen bij de ingebouwde
|
|
*Uploads*-bron van hun space (`upload_source_id(space_id)`, deterministisch).
|
|
|
|
De `source_id` is **één identiteit** door de hele keten: document → chunk →
|
|
Qdrant-payload → provenance → citation (`ragcore://source/<id>`) → `source_ids`-filter
|
|
→ Control Plane. De `source_key`/`external_id`-dedupsleutel van documenten blijft
|
|
ongewijzigd (sync-clients via de upload-API merken niets).
|
|
|
|
Synchronisatie (`SourceSyncService`, worker-job `sync_source`, alleen folder/Git):
|
|
|
|
```
|
|
discover (alle pagina's) → vergelijk fingerprint met registry-items
|
|
→ nieuw/gewijzigd: acquire → blob → ingest_upload-job (zelfde pipeline als uploads)
|
|
→ ongewijzigd: niets
|
|
→ verdwenen (alleen bij complete scan): document retiren
|
|
→ persist run: discovered / new / changed / unchanged / removed / failed
|
|
```
|
|
|
|
Git-items krijgen het commit als `source_revision` op de documentversie; het
|
|
stabiele document-id van een item is zijn pad (`locator`), niet `<commit>:<pad>`.
|
|
Er is geen scheduler: een sync start vanuit de Control Plane ("Sync now") of door
|
|
een `sync_source`-job te enqueuen. Website-bronnen zijn nog niet aan te maken.
|