Skip to main content

uqa_execution/catalog/security/
system_relations.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Restore and merge independently persisted relation and attribute ACL tuples.
8
9use std::{collections::BTreeMap, ops::DerefMut};
10use uqa_core::RelationIdentity;
11use uqa_sql::catalog::{
12    roles::RoleDefinition,
13    security::system_relations::{
14        metadata_key, validate_security, SystemAcl, SystemRelationSecurities,
15        SystemRelationSecurityCatalog, METADATA_PREFIX,
16    },
17    SystemRelation,
18};
19use uqa_storage::{CatalogFacade, StorageBackendError, StorageBackendResult};
20
21mod persistence;
22
23pub trait SystemRelationSecurityState: SystemRelationSecurityCatalog {
24    fn system_relation_securities_write(
25        &self,
26    ) -> Box<dyn DerefMut<Target = SystemRelationSecurities> + '_>;
27}
28
29pub fn restore(
30    catalog: &dyn CatalogFacade,
31    roles: &BTreeMap<String, RoleDefinition>,
32    allow_migration: bool,
33) -> StorageBackendResult<SystemRelationSecurities> {
34    let mut result = SystemRelationSecurities::new();
35    let mut migrations = Vec::new();
36    for (key, json) in catalog.metadata_with_prefix(METADATA_PREFIX)? {
37        let (name, column) = key
38            .strip_prefix(METADATA_PREFIX)
39            .and_then(|suffix| suffix.split_once(':'))
40            .ok_or_else(|| StorageBackendError::Other("invalid system ACL metadata key".into()))?;
41        let relation = SystemRelation::from_qualified_name(name)
42            .ok_or_else(|| StorageBackendError::Other("unknown system ACL relation".into()))?;
43        let (entry, migrated) = persistence::decode(&json, roles, allow_migration)?;
44        if entry.revision == [0; 16] {
45            return Err(StorageBackendError::Other(
46                "invalid system ACL tuple identity".into(),
47            ));
48        }
49        if migrated {
50            migrations.push((key.clone(), persistence::encode(&entry)?));
51        }
52        let security = result
53            .entry(RelationIdentity::new(relation.namespace(), relation.name()))
54            .or_default();
55        if column.is_empty() {
56            security.table = Some(entry);
57        } else if relation.column_names().iter().any(|name| name == column) {
58            security.columns.insert(column.to_string(), entry);
59        } else {
60            return Err(StorageBackendError::Other(
61                "unknown system ACL attribute".into(),
62            ));
63        }
64    }
65    for (identity, entry) in &result {
66        let relation = SystemRelation::at(&identity.schema, &identity.name)
67            .expect("validated system identity");
68        let security = entry
69            .security(relation)
70            .resolve(roles)
71            .map_err(StorageBackendError::Other)?;
72        validate_security(relation, &security, roles).map_err(StorageBackendError::Other)?;
73    }
74    for (key, value) in migrations {
75        catalog.set_metadata(&key, &value)?;
76    }
77    Ok(result)
78}
79
80pub struct SystemPrivilegeUpdate {
81    pub relation: SystemRelation,
82    pub column: Option<String>,
83    pub entry: SystemAcl,
84}
85impl SystemPrivilegeUpdate {
86    pub fn new(
87        relation: SystemRelation,
88        column: Option<String>,
89        acl: Vec<uqa_sql::catalog::security::table_binding::BoundTableAclEntry>,
90    ) -> StorageBackendResult<Self> {
91        let revision = crate::catalog::identity::new_nonzero_catalog_identity(
92            &relation.qualified_name(),
93            "ACL tuple",
94        )?;
95        Ok(Self {
96            relation,
97            column,
98            entry: SystemAcl { revision, acl },
99        })
100    }
101    pub fn persist(&self, catalog: Option<&dyn CatalogFacade>) -> StorageBackendResult<()> {
102        if let Some(catalog) = catalog {
103            catalog.set_metadata(
104                &metadata_key(self.relation, self.column.as_deref()),
105                &persistence::encode(&self.entry)?,
106            )?;
107        }
108        Ok(())
109    }
110    pub fn publish(self, securities: &mut SystemRelationSecurities) {
111        let security = securities
112            .entry(RelationIdentity::new(
113                self.relation.namespace(),
114                self.relation.name(),
115            ))
116            .or_default();
117        if let Some(column) = self.column {
118            security.columns.insert(column, self.entry);
119        } else {
120            security.table = Some(self.entry);
121        }
122    }
123}
124
125/// Fixed data snapshots still refresh catalogs. Only records actually written by this transaction overlay that latest catalog, including empty attribute ACL replacements after REVOKE.
126pub fn merge_private(
127    catalog: Option<&dyn CatalogFacade>,
128    current: &SystemRelationSecurities,
129    mut latest: SystemRelationSecurities,
130) -> StorageBackendResult<SystemRelationSecurities> {
131    let Some(catalog) = catalog else {
132        return Ok(latest);
133    };
134    for (identity, security) in current {
135        let relation = SystemRelation::at(&identity.schema, &identity.name).ok_or_else(|| {
136            StorageBackendError::Other("non-system relation in system ACL registry".into())
137        })?;
138        if security.table.is_some()
139            && catalog.metadata_has_private_changes(&metadata_key(relation, None))?
140        {
141            latest
142                .entry(identity.clone())
143                .or_default()
144                .table
145                .clone_from(&security.table);
146        }
147        for (column, entry) in &security.columns {
148            if catalog.metadata_has_private_changes(&metadata_key(relation, Some(column)))? {
149                latest
150                    .entry(identity.clone())
151                    .or_default()
152                    .columns
153                    .insert(column.clone(), entry.clone());
154            }
155        }
156    }
157    Ok(latest)
158}
159
160pub fn tuple_revision(
161    registry: &dyn SystemRelationSecurityCatalog,
162    relation: SystemRelation,
163    column: Option<&str>,
164) -> Option<[u8; 16]> {
165    registry
166        .system_relation_securities()
167        .get(&RelationIdentity::new(
168            relation.namespace(),
169            relation.name(),
170        ))
171        .and_then(|security| security.entry(column))
172        .map(|entry| entry.revision)
173}
174
175#[cfg(test)]
176mod tests;