# rustium-config
Versioned Rustium configuration models, validation, environment interpolation, semantic fingerprints, and Debezium-compatible `.properties` parsing for all Rustium database sources, sinks, formats, and runtime settings.
Use this crate when an embedded Rustium application needs the same strict configuration contract as the CLI. See the [project README](https://github.com/ulnit/rustium/blob/main/README.md).
`snapshot.include.collection.list` maps to native `snapshot.include_collections` with anchored, connector-qualified, snapshot-only matching.
PostgreSQL `publication.autocreate.mode` supports `disabled`, `all_tables`, `filtered`, and `no_tables`. Debezium properties default to `all_tables`; native `source.publication_autocreate_mode` defaults to `disabled` for backward-compatible ownership and fingerprints.
PostgreSQL `replica.identity.autoset.values` maps to structured native rules with `table`, `identity`, and optional `index`. Non-empty rules are fingerprinted because validation applies transactional table DDL.
PostgreSQL `publish.via.partition.root` maps to native `source.publish_via_partition_root`; existing publication metadata must match the configured value.
PostgreSQL `slot.failover` maps to native `source.slot_failover`. It defaults to false and is fingerprinted only when enabled; failover configuration is valid only for managed slots.
PostgreSQL `slot.drop.on.stop` maps to native `source.drop_slot_on_stop`. It defaults to false, is valid only for managed slots, and is excluded from fingerprints because it affects orderly lifecycle cleanup rather than event selection.
PostgreSQL `snapshot.locking.mode=none|shared` maps to native `source.snapshot_locking_mode`; `snapshot.lock.timeout.ms` maps to the 10-second native `source.snapshot_lock_timeout`. Both are operational and excluded from fingerprints. Java SPI mode `custom` and timeouts above PostgreSQL's signed 32-bit millisecond limit fail validation.
PostgreSQL `snapshot.isolation.mode` maps to native `source.snapshot_isolation_mode` and accepts `serializable`, `repeatable_read`, `read_committed`, and `read_uncommitted`. Serializable and `repeatable_read` preserve existing fingerprints because both import the same exported snapshot; the lower modes are fingerprinted because they alter snapshot consistency and slot handoff.
PostgreSQL `xmin.fetch.interval.ms` maps to native `source.xmin_fetch_interval` and defaults to zero (disabled). A non-zero interval is fingerprinted because it adds the periodically cached slot `catalog_xmin` to PostgreSQL source metadata.
PostgreSQL `lsn.flush.timeout.ms` maps to the positive, 30-second native `source.lsn_flush_timeout`; `lsn.flush.timeout.action=fail|warn|ignore` maps to `source.lsn_flush_timeout_action`. They bound real acknowledgement feedback I/O and are excluded from fingerprints as operational controls.
PostgreSQL `interval.handling.mode` accepts Debezium `numeric` and `string`; properties default to `numeric`. Native `source.interval_handling_mode` additionally accepts the backward-compatible `postgres` default, which is omitted from fingerprint material.
PostgreSQL `money.fraction.digits` maps to native `source.money_fraction_digits` and defaults to `2`. Non-default signed 16-bit scales are fingerprinted because they change MONEY schemas and values.
PostgreSQL `schema.refresh.mode` maps to native `source.schema_refresh_mode` and accepts `columns_diff` or `columns_diff_exclude_unchanged_toast`. Both are operationally equivalent with pgoutput Relation-driven schemas and are excluded from fingerprints.
PostgreSQL Debezium properties enable logical decoding messages by default and map `message.prefix.include.list` / `message.prefix.exclude.list` to anchored native filters. Native `source.logical_decoding_messages` defaults to false; enabling capture or adding filters is fingerprinted.
PostgreSQL, MySQL, and SQL Server column transformations map Debezium's `column.truncate.to.<length>.chars`, `column.mask.with.<length>.chars`, `column.mask.hash.<algorithm>.with.salt.<salt>`, and `column.mask.hash.v2.<algorithm>.with.salt.<salt>` properties to native `source.column_transformations`. Selectors are anchored and case-insensitive: PostgreSQL uses `schema.table.column`, MySQL uses `database.table.column`, and SQL Server accepts both `database.schema.table.column` and `schema.table.column`. Category priority is truncate, fixed mask, hash V1, then hash V2. Hash salts are validated as non-empty and are represented in semantic fingerprints only by SHA-256 digest.
MariaDB, Db2, Cassandra, Vitess, Spanner, Informix, CockroachDB, and YashanDB map to `DebeziumSourceConfig`. Connector properties remain under `source.properties`; secrets and command environment values are excluded from semantic fingerprints. HTTP and Kafka bridge transports reserve their durability settings so user pass-through properties cannot enable automatic acknowledgement.
## 简体中文
Rustium 的版本化配置模型、校验、环境变量插值、语义指纹，以及全部 Rustium 数据库 Source、Sink、格式和 runtime 的 Debezium 兼容 `.properties` 解析。
嵌入 Rustium 的应用需要与 CLI 相同的严格配置契约时使用此 crate。详见[项目 README](https://github.com/ulnit/rustium/blob/main/README.md)。
`snapshot.include.collection.list` 映射为原生 `snapshot.include_collections`，采用 anchored、连接器限定且仅作用于快照的匹配语义。
PostgreSQL `publication.autocreate.mode` 支持 `disabled`、`all_tables`、`filtered` 和 `no_tables`。Debezium properties 默认使用 `all_tables`；原生 `source.publication_autocreate_mode` 默认使用 `disabled`，以保持向后兼容的所有权和 fingerprint。
PostgreSQL `replica.identity.autoset.values` 映射为带 `table`、`identity` 和可选 `index` 的结构化原生规则。非空规则会进入 fingerprint，因为 validation 会执行事务化表 DDL。
PostgreSQL `publish.via.partition.root` 映射为原生 `source.publish_via_partition_root`；既有 publication metadata 必须与配置值一致。
PostgreSQL `slot.failover` 映射为原生 `source.slot_failover`。默认值为 false，只有启用时才进入 fingerprint；failover 配置只适用于 managed slot。
PostgreSQL `slot.drop.on.stop` 映射为原生 `source.drop_slot_on_stop`。默认值为 false，只适用于 managed slot；它影响有序生命周期清理而不是事件选择，因此不进入 fingerprint。
PostgreSQL `snapshot.locking.mode=none|shared` 映射为原生 `source.snapshot_locking_mode`；`snapshot.lock.timeout.ms` 映射为默认 10 秒的原生 `source.snapshot_lock_timeout`。两者都是运维参数，不进入 fingerprint。Java SPI 模式 `custom` 以及超过 PostgreSQL 有符号 32 位毫秒上限的 timeout 会校验失败。
PostgreSQL `snapshot.isolation.mode` 映射为原生 `source.snapshot_isolation_mode`，接受 `serializable`、`repeatable_read`、`read_committed` 和 `read_uncommitted`。`serializable` 与 `repeatable_read` 都导入同一 exported snapshot，因此保持既有 fingerprint；较低模式会改变 snapshot 一致性和 slot handoff，因此进入 fingerprint。
PostgreSQL `xmin.fetch.interval.ms` 映射为原生 `source.xmin_fetch_interval`，默认值为零（禁用）。非零周期会把定期缓存的 slot `catalog_xmin` 加入 PostgreSQL source metadata，因此进入 fingerprint。
PostgreSQL `lsn.flush.timeout.ms` 映射为必须为正值且默认 30 秒的原生 `source.lsn_flush_timeout`；`lsn.flush.timeout.action=fail|warn|ignore` 映射为 `source.lsn_flush_timeout_action`。它们限制真实 acknowledgement feedback I/O，属于不进入 fingerprint 的运维控制项。
PostgreSQL `interval.handling.mode` 接受 Debezium 的 `numeric` 和 `string`，properties 默认使用 `numeric`。原生 `source.interval_handling_mode` 还接受向后兼容的默认值 `postgres`，该默认值不会进入 fingerprint material。
PostgreSQL `money.fraction.digits` 映射为原生 `source.money_fraction_digits`，默认值为 `2`。非默认的有符号 16 位 scale 会改变 MONEY schema 与值，因此进入 fingerprint。
PostgreSQL `schema.refresh.mode` 映射为原生 `source.schema_refresh_mode`，接受 `columns_diff` 或 `columns_diff_exclude_unchanged_toast`。在 pgoutput Relation-driven schema 下两者运维行为等价，因此不进入 fingerprint。
PostgreSQL Debezium properties 默认启用 logical decoding message，并把 `message.prefix.include.list` / `message.prefix.exclude.list` 映射为 anchored 原生过滤器。原生 `source.logical_decoding_messages` 默认为 false；启用捕获或增加过滤器都会进入 fingerprint。
PostgreSQL、MySQL 和 SQL Server 列转换把 Debezium 的 `column.truncate.to.<length>.chars`、`column.mask.with.<length>.chars`、`column.mask.hash.<algorithm>.with.salt.<salt>` 和 `column.mask.hash.v2.<algorithm>.with.salt.<salt>` 映射为原生 `source.column_transformations`。Selector 都是 anchored、大小写不敏感正则：PostgreSQL 使用 `schema.table.column`，MySQL 使用 `database.table.column`，SQL Server 同时接受 `database.schema.table.column` 和 `schema.table.column`。类别优先级为 truncate、固定 mask、hash V1、hash V2。Hash salt 必须非空，并且在 semantic fingerprint 中只保存 SHA-256 digest。
MariaDB、Db2、Cassandra、Vitess、Spanner、Informix、CockroachDB 和 YashanDB 映射为 `DebeziumSourceConfig`。Connector 参数保留在 `source.properties`，secret 与 command environment value 不进入语义 fingerprint。HTTP/Kafka bridge 的持久性参数由 Rustium 保留，透传参数不能开启自动确认。