5.1 KiB
govoplan-connectors
Repository type: connector (connector-hub).
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:
/mnt/DATA/git/govoplan/.venv/bin/python -m pip install -e .
/mnt/DATA/git/govoplan/.venv/bin/python -m unittest discover -s tests
See: