98 lines
5.1 KiB
Markdown
98 lines
5.1 KiB
Markdown
# govoplan-connectors
|
|
|
|
<!-- govoplan-repository-type:start -->
|
|
**Repository type:** connector (connector-hub).
|
|
<!-- govoplan-repository-type:end -->
|
|
|
|
`govoplan-connectors` owns integration catalogues and generic external system
|
|
connection patterns for GovOPlaN.
|
|
|
|
The module should make external systems discoverable, testable, and usable
|
|
without taking ownership of their business semantics. Domain-specific modules
|
|
remain responsible for case, file, workflow, payment, mail, identity, document,
|
|
or reporting behavior.
|
|
|
|
## Executable First Slice
|
|
|
|
The executable connector capability provides tenant-isolated tabular origins.
|
|
Operators can import bounded JSON or CSV snapshots, bind an exact managed Files
|
|
CSV/XLSX version, or discover a table through an active governed PostgreSQL
|
|
configuration. Every origin exposes a reviewed schema, opaque reference, and
|
|
content/discovery fingerprint through `connectors.datasource_origins@0.1.0`.
|
|
Preview reads enforce provider ceilings for rows, serialized bytes, and elapsed
|
|
time and report the effective limits and any truncation as structured
|
|
diagnostics.
|
|
|
|
Connectors owns acquisition, connection profiles, credentials, discovery, and
|
|
provider health. `govoplan-datasources` registers an origin as a governed live
|
|
or cached datasource and owns staging, materializations, frozen states, and
|
|
consumer access. Dataflow consumes that Datasources contract and never imports
|
|
connector implementations or stores connector credentials.
|
|
|
|
Each origin declares whether it is live, cached, file-backed, or static, its
|
|
structured health state, and which projection, filter, aggregation, sorting,
|
|
and pagination operations it can push down. The snapshot, managed-file, and
|
|
PostgreSQL providers currently support projection and pagination only;
|
|
consumers must keep other operations in Dataflow rather than assuming
|
|
transport-side execution.
|
|
|
|
Managed-file sources are authorized and opened through
|
|
`files.tabular_content@1.0.0`; Files remains authoritative for ownership,
|
|
shares, download permission, exact versions, integrity, quarantine, encryption,
|
|
retention, and legal holds. CSV must be UTF-8. XLSX input is protected by
|
|
compressed-entry, expanded-byte, compression-ratio, row, and column limits.
|
|
A newer current version is reported but never silently replaces the pinned
|
|
version.
|
|
|
|
The PostgreSQL adapter accepts only an active governed connector configuration
|
|
whose secret-free endpoint uses the PostgreSQL driver. Authentication is
|
|
resolved from a tenant/scope/module/server-restricted Core credential envelope.
|
|
The adapter reflects a simple schema/table identifier, uses read-only
|
|
transactions and a statement timeout, and blocks configuration, credential, or
|
|
schema drift until an operator refreshes and reviews the source. Secrets are
|
|
never copied into source metadata or diagnostics. Other database, REST/HTTP,
|
|
directory, and warehouse providers can implement the same origin contract
|
|
without changing Datasources or Dataflow.
|
|
|
|
Governed sanctions and feed snapshot acquisitions use Core recovery operations.
|
|
The source revision/cursor, redacted dry-run decision, canonical request digest,
|
|
and distributed lease are durable before network I/O. Immutable snapshot rows
|
|
and the terminal recovery checkpoint commit atomically, and an
|
|
`Idempotency-Key` replays the committed result without contacting the provider.
|
|
Current acquisition transports are read-only. The exported external-mutation
|
|
recovery contract requires stable idempotency, provider verification, and
|
|
operator reconciliation, but no connector currently claims a production write
|
|
or delete path.
|
|
|
|
RSS and Atom emission is a bounded renderer, not an authority shortcut. Every
|
|
selected entry declares whether it came from a GovOPlaN event, publication,
|
|
case, or report and carries an opaque owning-module reference and optional
|
|
revision. Public-feed permission can render only public entries. Tenant and
|
|
private audiences require a separate restricted-feed permission, and the API
|
|
derives the allowed visibility set from that audience instead of accepting a
|
|
caller-controlled allow-list. Portal or Reporting remains responsible for any
|
|
durable public or authenticated route and must re-authorize restricted access.
|
|
|
|
The governed connector runtime adds immutable definition revisions,
|
|
revision-pinned tenant configurations, protected local overrides, explicit
|
|
package-update adoption, bounded dry-runs and simulations, redacted provenance,
|
|
idempotency, and configurable ambiguity handling through review, quarantine,
|
|
or rejection. Its administration surface is contributed to the shared system
|
|
administration workspace. Provider-specific adapters still own live writes.
|
|
|
|
Development:
|
|
|
|
```bash
|
|
/mnt/DATA/git/govoplan/.venv/bin/python -m pip install -e .
|
|
/mnt/DATA/git/govoplan/.venv/bin/python -m unittest discover -s tests
|
|
```
|
|
|
|
See:
|
|
|
|
- [Connector concept](docs/CONCEPT.md)
|
|
- [Public-sector integration catalogue](docs/PUBLIC_SECTOR_INTEGRATION_CATALOGUE.md)
|
|
- [Connector source lifecycle](docs/CONNECTOR_SOURCE_LIFECYCLE.md)
|
|
- [OpenProject connector concept](docs/OPENPROJECT_CONNECTOR.md)
|
|
- [OpenDesk integration map](docs/OPENDESK_INTEGRATION_MAP.md)
|
|
- [Governed connector configuration](docs/GOVERNED_CONNECTOR_CONFIGURATION.md)
|