naaudit_pgsql/
lib.rs

1//! PostgreSQL Outbox 审计适配器：审计事实与业务写必须共享同一 ambient transaction。
2
3#![forbid(unsafe_code)]
4
5use naaudit::{AuditEvent, AuditWriteError, TransactionalAuditSink};
6use naoutbox_pgsql::PgOutbox;
7
8/// PostgreSQL 事务审计 sink；全部审计写固定进入底层 Outbox 绑定的 datasource。
9#[derive(Debug, Clone)]
10pub struct PgOutboxAuditSink {
11    outbox: PgOutbox,
12}
13
14impl Default for PgOutboxAuditSink {
15    /// 业务作用：创建绑定默认 PostgreSQL datasource 的审计适配器。
16    ///
17    /// 参数说明: 无。
18    ///
19    /// 返回：与 [`PgOutboxAuditSink::new`] 相同的轻量句柄。
20    fn default() -> Self {
21        Self::new()
22    }
23}
24
25impl PgOutboxAuditSink {
26    /// 业务作用：创建绑定默认 datasource 的审计适配器，不建立独立连接池。
27    ///
28    /// 参数说明: 无。
29    ///
30    /// 返回：审计事件固定写入默认 datasource Outbox 的轻量句柄。
31    pub fn new() -> Self {
32        Self {
33            outbox: PgOutbox::new(),
34        }
35    }
36
37    /// 业务作用：创建绑定命名 PostgreSQL datasource 的审计适配器。
38    ///
39    /// 参数说明：
40    /// - `datasource`：启动期已登记的稳定 datasource 名称。
41    ///
42    /// 返回：名称合法时返回固定绑定句柄；非法名称在网络 I/O 前失败。
43    pub fn with_datasource(
44        datasource: impl AsRef<str>,
45    ) -> Result<Self, naoutbox_pgsql::OutboxStoreError> {
46        Ok(Self {
47            outbox: PgOutbox::with_datasource(datasource)?,
48        })
49    }
50
51    /// 业务作用：读取审计事件最终写入的 PostgreSQL datasource 身份。
52    ///
53    /// 参数说明: 无。
54    ///
55    /// 返回：底层 Outbox 固定使用且不含连接信息的 qualifier。
56    pub fn datasource_ref(&self) -> &natx_pgsql::DatasourceRef {
57        self.outbox.datasource_ref()
58    }
59}
60
61#[async_trait::async_trait]
62impl TransactionalAuditSink for PgOutboxAuditSink {
63    /// 业务作用：在当前同源 PostgreSQL ambient transaction 内写入审计 Outbox 事实。
64    ///
65    /// 参数说明：
66    /// - `event`：已经完成 actor、资源、结局与脱敏 context 归因的业务审计事件。
67    ///
68    /// 返回：Outbox append 与 after-commit 登记成功时完成；事务、路由或数据库失败返回脱敏错误。
69    async fn record_transactional(&self, event: AuditEvent) -> Result<(), AuditWriteError> {
70        self.outbox
71            .append_transactional(&event.into_outbox_event())
72            .await
73            .map_err(|_| AuditWriteError::new("transactional PostgreSQL outbox append failed"))
74    }
75}
naaudit_pgsql/lib.rs

naaudit_pgsql/
lib.rs
