teaql 0.2.7__tar.gz → 0.2.9__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {teaql-0.2.7 → teaql-0.2.9}/PKG-INFO +26 -1
- {teaql-0.2.7 → teaql-0.2.9}/README.md +25 -0
- {teaql-0.2.7 → teaql-0.2.9}/pyproject.toml +1 -1
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql/core/dynamic_search.py +2 -2
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql/core/meta.py +10 -1
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql/data_service/__init__.py +14 -0
- teaql-0.2.9/src/teaql/provider/mysql/dialect.py +13 -0
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql/provider/mysql/transport.py +47 -2
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql/provider/postgres/dialect.py +1 -1
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql/provider/postgres/transport.py +46 -2
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql/provider/tfp_client/__init__.py +26 -21
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql/runtime/__init__.py +32 -0
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql/runtime/audit.py +12 -8
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql/runtime/context.py +76 -10
- teaql-0.2.9/src/teaql/runtime/log_privacy.py +195 -0
- teaql-0.2.9/src/teaql/runtime/mutation_policy.py +607 -0
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql/sql/dialect.py +58 -22
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql/sql/executor.py +216 -100
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql/sql/types.py +62 -5
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql.egg-info/PKG-INFO +26 -1
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql.egg-info/SOURCES.txt +1 -0
- teaql-0.2.7/src/teaql/provider/mysql/dialect.py +0 -31
- teaql-0.2.7/src/teaql/runtime/log_privacy.py +0 -93
- {teaql-0.2.7 → teaql-0.2.9}/LICENSE +0 -0
- {teaql-0.2.7 → teaql-0.2.9}/setup.cfg +0 -0
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql/__init__.py +0 -0
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql/core/__init__.py +0 -0
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql/core/entity.py +0 -0
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql/core/eval.py +0 -0
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql/core/expr.py +0 -0
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql/core/graph.py +0 -0
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql/core/list.py +0 -0
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql/core/mutation.py +0 -0
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql/core/query.py +0 -0
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql/core/safe_expression.py +0 -0
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql/core/value.py +0 -0
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql/core/xls.py +0 -0
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql/provider/__init__.py +0 -0
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql/provider/mysql/__init__.py +0 -0
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql/provider/postgres/__init__.py +0 -0
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql/provider/redis/__init__.py +0 -0
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql/provider/redis/remote.py +0 -0
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql/provider/redis/store.py +0 -0
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql/provider/sqlite/__init__.py +0 -0
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql/provider/sqlite/dialect.py +0 -0
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql/provider/sqlite/transport.py +0 -0
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql/py.typed +0 -0
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql/runtime/_schema_capability.py +0 -0
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql/runtime/builtin-messages-v1.json +0 -0
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql/runtime/env.py +0 -0
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql/runtime/i18n.py +0 -0
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql/runtime/module.py +0 -0
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql/runtime/opentelemetry.py +0 -0
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql/runtime/store.py +0 -0
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql/runtime/telemetry.py +0 -0
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql/runtime/tools.py +0 -0
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql/runtime/wire_fields.py +0 -0
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql/sql/__init__.py +0 -0
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql/web_integration/__init__.py +0 -0
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql/web_integration/fastapi/__init__.py +0 -0
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql.egg-info/dependency_links.txt +0 -0
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql.egg-info/requires.txt +0 -0
- {teaql-0.2.7 → teaql-0.2.9}/src/teaql.egg-info/top_level.txt +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: teaql
|
|
3
|
-
Version: 0.2.
|
|
3
|
+
Version: 0.2.9
|
|
4
4
|
Summary: TeaQL Runtime and Data Service for Python
|
|
5
5
|
Author: TeaQL
|
|
6
6
|
License-Expression: Apache-2.0
|
|
@@ -104,6 +104,11 @@ The SDK's organizational architecture strictly mirrors the Rust version:
|
|
|
104
104
|
* **Facet Aggregation & Grouping**: Out-of-the-box support for multi-dimensional facet aggregations, group-bys, and hierarchical data processing.
|
|
105
105
|
* **Provider Support**: Highly extensible asynchronous database connectivity (integrating third-party async drivers like `aiosqlite` through a unified Transport layer).
|
|
106
106
|
* **Context & Logging Management**: Built-in support for lifecycle context passing, end-to-end tracing, and SQL execution log interception and dispatch.
|
|
107
|
+
* **Governed Mutation Policy**: An application-owned policy can review an
|
|
108
|
+
immutable whole-graph plan after Checker/Fix and before the first provider
|
|
109
|
+
mutation. Exact policy identity and approval state are retained with audit
|
|
110
|
+
evidence. Missing customer policy or approval emits stable warnings without
|
|
111
|
+
changing persistence semantics; an explicit denial fails closed.
|
|
107
112
|
* **TeaQL Federal Protocol Client**: `TeaQLFederalClient` and `TfpHttpProvider`
|
|
108
113
|
execute governed canonical TFP v1 queries and audited mutations against a
|
|
109
114
|
remote TeaQL endpoint such as Rust. Direct query execution returns
|
|
@@ -143,5 +148,25 @@ development-only acknowledgement are maintained in the canonical
|
|
|
143
148
|
Opaque tokens never replace the backend's authorization, tenant, ownership,
|
|
144
149
|
role, or optimistic-version checks.
|
|
145
150
|
|
|
151
|
+
### Mutation Policy installation
|
|
152
|
+
|
|
153
|
+
Policy implementations are installed from trusted application startup through
|
|
154
|
+
`UserContext`; request JSON cannot select or replace them. Built-in SQL and TFP
|
|
155
|
+
providers enter the same governed boundary.
|
|
156
|
+
|
|
157
|
+
```python
|
|
158
|
+
context = (
|
|
159
|
+
UserContext.new()
|
|
160
|
+
.with_mutation_policy_registry(policy_registry)
|
|
161
|
+
.with_mutation_policy_approval_provider(approval_provider)
|
|
162
|
+
.with_mutation_governance_sink(warning_sink)
|
|
163
|
+
)
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
Generated graph saves call `preflight_mutation(...)` for every operation before
|
|
167
|
+
the first provider write. See the repeatable
|
|
168
|
+
[`examples/mutation-policy`](examples/mutation-policy) example for allow,
|
|
169
|
+
approval, audit propagation, and zero-write denial evidence.
|
|
170
|
+
|
|
146
171
|
---
|
|
147
172
|
To run test validations and business logic simulations locally, simply run `pytest` in the project root.
|
|
@@ -65,6 +65,11 @@ The SDK's organizational architecture strictly mirrors the Rust version:
|
|
|
65
65
|
* **Facet Aggregation & Grouping**: Out-of-the-box support for multi-dimensional facet aggregations, group-bys, and hierarchical data processing.
|
|
66
66
|
* **Provider Support**: Highly extensible asynchronous database connectivity (integrating third-party async drivers like `aiosqlite` through a unified Transport layer).
|
|
67
67
|
* **Context & Logging Management**: Built-in support for lifecycle context passing, end-to-end tracing, and SQL execution log interception and dispatch.
|
|
68
|
+
* **Governed Mutation Policy**: An application-owned policy can review an
|
|
69
|
+
immutable whole-graph plan after Checker/Fix and before the first provider
|
|
70
|
+
mutation. Exact policy identity and approval state are retained with audit
|
|
71
|
+
evidence. Missing customer policy or approval emits stable warnings without
|
|
72
|
+
changing persistence semantics; an explicit denial fails closed.
|
|
68
73
|
* **TeaQL Federal Protocol Client**: `TeaQLFederalClient` and `TfpHttpProvider`
|
|
69
74
|
execute governed canonical TFP v1 queries and audited mutations against a
|
|
70
75
|
remote TeaQL endpoint such as Rust. Direct query execution returns
|
|
@@ -104,5 +109,25 @@ development-only acknowledgement are maintained in the canonical
|
|
|
104
109
|
Opaque tokens never replace the backend's authorization, tenant, ownership,
|
|
105
110
|
role, or optimistic-version checks.
|
|
106
111
|
|
|
112
|
+
### Mutation Policy installation
|
|
113
|
+
|
|
114
|
+
Policy implementations are installed from trusted application startup through
|
|
115
|
+
`UserContext`; request JSON cannot select or replace them. Built-in SQL and TFP
|
|
116
|
+
providers enter the same governed boundary.
|
|
117
|
+
|
|
118
|
+
```python
|
|
119
|
+
context = (
|
|
120
|
+
UserContext.new()
|
|
121
|
+
.with_mutation_policy_registry(policy_registry)
|
|
122
|
+
.with_mutation_policy_approval_provider(approval_provider)
|
|
123
|
+
.with_mutation_governance_sink(warning_sink)
|
|
124
|
+
)
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
Generated graph saves call `preflight_mutation(...)` for every operation before
|
|
128
|
+
the first provider write. See the repeatable
|
|
129
|
+
[`examples/mutation-policy`](examples/mutation-policy) example for allow,
|
|
130
|
+
approval, audit propagation, and zero-write denial evidence.
|
|
131
|
+
|
|
107
132
|
---
|
|
108
133
|
To run test validations and business logic simulations locally, simply run `pytest` in the project root.
|
|
@@ -17,8 +17,8 @@ def _reject_json_constant(_):
|
|
|
17
17
|
|
|
18
18
|
|
|
19
19
|
def _warning(warning):
|
|
20
|
-
_LOG.warning('%s entity=%s clause=%s fieldPath
|
|
21
|
-
warning['entity'], warning['clause']
|
|
20
|
+
_LOG.warning('%s entity=%s clause=%s fieldPath=<omitted>', warning['code'],
|
|
21
|
+
warning['entity'], warning['clause'])
|
|
22
22
|
|
|
23
23
|
|
|
24
24
|
def normalize_dynamic_search(source, entity, models, warn=_warning, max_clauses=100):
|
|
@@ -6,6 +6,13 @@ class PropertyDescriptor:
|
|
|
6
6
|
self._is_id = False
|
|
7
7
|
self._is_version = False
|
|
8
8
|
self.nullable = True
|
|
9
|
+
self.log_policy_val = 'unknown'
|
|
10
|
+
def log_policy(self, policy):
|
|
11
|
+
"""Trusted schema policy; incoming requests cannot override it."""
|
|
12
|
+
if policy not in ('plain', 'masked', 'credential', 'unknown'):
|
|
13
|
+
raise ValueError('invalid SQL parameter log policy')
|
|
14
|
+
self.log_policy_val = policy
|
|
15
|
+
return self
|
|
9
16
|
def column_name(self, name):
|
|
10
17
|
self.column_name_val = name
|
|
11
18
|
return self
|
|
@@ -46,6 +53,7 @@ class EntityDescriptor:
|
|
|
46
53
|
self.properties = []
|
|
47
54
|
self.relations = []
|
|
48
55
|
self.audit_mask_fields_val = []
|
|
56
|
+
self.audit_mask_fields_declared = False
|
|
49
57
|
self.audit_value_max_len_val = None
|
|
50
58
|
def table_name(self, name):
|
|
51
59
|
self.table_name_val = name
|
|
@@ -65,7 +73,8 @@ class EntityDescriptor:
|
|
|
65
73
|
return next((prop for prop in self.properties if prop.name == name), None)
|
|
66
74
|
|
|
67
75
|
def audit_mask_fields(self, fields):
|
|
68
|
-
self.audit_mask_fields_val = list(fields)
|
|
76
|
+
self.audit_mask_fields_val = list(fields) if fields is not None else []
|
|
77
|
+
self.audit_mask_fields_declared = fields is not None
|
|
69
78
|
return self
|
|
70
79
|
|
|
71
80
|
def audit_value_max_len(self, max_len):
|
|
@@ -32,6 +32,15 @@ class QueryRequest:
|
|
|
32
32
|
_comment: Optional[str] = None
|
|
33
33
|
_purpose: Optional[str] = None
|
|
34
34
|
|
|
35
|
+
def __post_init__(self) -> None:
|
|
36
|
+
# Older generated wrappers store intent on SelectQuery but construct
|
|
37
|
+
# QueryRequest(query) without forwarding it. Keep the explicit request
|
|
38
|
+
# values authoritative while preserving their diagnostic intent.
|
|
39
|
+
if self._comment is None:
|
|
40
|
+
self._comment = getattr(self.query, 'comment_text', None)
|
|
41
|
+
if self._purpose is None:
|
|
42
|
+
self._purpose = getattr(self.query, 'purpose_text', None)
|
|
43
|
+
|
|
35
44
|
def comment(self, text: str) -> 'QueryRequest':
|
|
36
45
|
if not text:
|
|
37
46
|
raise ValueError("comment cannot be empty")
|
|
@@ -71,6 +80,11 @@ class ExecutionMetadata:
|
|
|
71
80
|
audit_reason: Optional[str] = None
|
|
72
81
|
backend_request_id: Optional[str] = None
|
|
73
82
|
debug_query: Optional[str] = None
|
|
83
|
+
database_kind: Any = None
|
|
84
|
+
parameter_log_policies: Optional[List[str]] = None
|
|
85
|
+
sql_origin: Optional[str] = None
|
|
86
|
+
# Statement/cursor termination only, not transaction commit.
|
|
87
|
+
execution_outcome: Optional[str] = None
|
|
74
88
|
|
|
75
89
|
|
|
76
90
|
@dataclass
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
from teaql.sql.dialect import SqlDialect, quote_identifier_if_needed
|
|
2
|
+
from teaql.sql.types import DatabaseKind
|
|
3
|
+
|
|
4
|
+
|
|
5
|
+
class MysqlDialect(SqlDialect):
|
|
6
|
+
def kind(self) -> DatabaseKind:
|
|
7
|
+
return DatabaseKind.MySql
|
|
8
|
+
|
|
9
|
+
def quote_ident(self, ident: str) -> str:
|
|
10
|
+
return quote_identifier_if_needed(ident, "`")
|
|
11
|
+
|
|
12
|
+
def placeholder(self, index: int) -> str:
|
|
13
|
+
return "%s"
|
|
@@ -3,11 +3,11 @@ import aiomysql
|
|
|
3
3
|
from decimal import Decimal
|
|
4
4
|
from datetime import date, datetime, timezone
|
|
5
5
|
from typing import List, Dict, Any, Optional, AsyncIterator
|
|
6
|
-
from teaql.sql.executor import
|
|
6
|
+
from teaql.sql.executor import SqlTransactionTransport, SqlTransactionTransportTx
|
|
7
7
|
from teaql.sql.types import CompiledQuery
|
|
8
8
|
from teaql.core.value import Value, DataType, Timestamp
|
|
9
9
|
|
|
10
|
-
class MysqlTransport(
|
|
10
|
+
class MysqlTransport(SqlTransactionTransport):
|
|
11
11
|
def __init__(self, db_url: str):
|
|
12
12
|
self.db_url = db_url
|
|
13
13
|
|
|
@@ -99,3 +99,48 @@ class MysqlTransport(SqlTransport):
|
|
|
99
99
|
return cur.rowcount, cur.lastrowid
|
|
100
100
|
finally:
|
|
101
101
|
conn.close()
|
|
102
|
+
|
|
103
|
+
async def begin_sql(self) -> SqlTransactionTransportTx:
|
|
104
|
+
user, password, host, port, db = self._parse_url()
|
|
105
|
+
conn = await aiomysql.connect(
|
|
106
|
+
host=host, port=port, user=user, password=password, db=db,
|
|
107
|
+
cursorclass=aiomysql.DictCursor, autocommit=False,
|
|
108
|
+
)
|
|
109
|
+
try:
|
|
110
|
+
await conn.begin()
|
|
111
|
+
return _MysqlTransaction(conn, self)
|
|
112
|
+
except BaseException:
|
|
113
|
+
conn.close()
|
|
114
|
+
raise
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
class _MysqlTransaction(SqlTransactionTransportTx):
|
|
118
|
+
def __init__(self, conn, owner: MysqlTransport):
|
|
119
|
+
self._conn = conn
|
|
120
|
+
self._owner = owner
|
|
121
|
+
|
|
122
|
+
async def fetch_all_sql(self, query: CompiledQuery) -> List[Dict[str, Any]]:
|
|
123
|
+
async with self._conn.cursor() as cursor:
|
|
124
|
+
await cursor.execute(query.sql_with_comment(), self._owner._bind_values(query.params))
|
|
125
|
+
rows = await cursor.fetchall()
|
|
126
|
+
return [
|
|
127
|
+
{key: self._owner._decode_value(value) for key, value in row.items()}
|
|
128
|
+
for row in rows
|
|
129
|
+
]
|
|
130
|
+
|
|
131
|
+
async def execute_sql(self, query: CompiledQuery) -> tuple[int, int]:
|
|
132
|
+
async with self._conn.cursor() as cursor:
|
|
133
|
+
await cursor.execute(query.sql_with_comment(), self._owner._bind_values(query.params))
|
|
134
|
+
return cursor.rowcount, cursor.lastrowid
|
|
135
|
+
|
|
136
|
+
async def commit_sql(self) -> None:
|
|
137
|
+
try:
|
|
138
|
+
await self._conn.commit()
|
|
139
|
+
finally:
|
|
140
|
+
self._conn.close()
|
|
141
|
+
|
|
142
|
+
async def rollback_sql(self) -> None:
|
|
143
|
+
try:
|
|
144
|
+
await self._conn.rollback()
|
|
145
|
+
finally:
|
|
146
|
+
self._conn.close()
|
|
@@ -5,7 +5,7 @@ from teaql.core.meta import PropertyDescriptor
|
|
|
5
5
|
|
|
6
6
|
class PostgresDialect(SqlDialect):
|
|
7
7
|
def kind(self) -> DatabaseKind:
|
|
8
|
-
return DatabaseKind.
|
|
8
|
+
return DatabaseKind.PostgreSql
|
|
9
9
|
|
|
10
10
|
def quote_ident(self, ident: str) -> str:
|
|
11
11
|
return quote_identifier_if_needed(ident, '"')
|
|
@@ -3,11 +3,11 @@ import asyncpg
|
|
|
3
3
|
from decimal import Decimal
|
|
4
4
|
from datetime import date, datetime, timezone
|
|
5
5
|
from typing import List, Dict, Any, Optional, AsyncIterator
|
|
6
|
-
from teaql.sql.executor import
|
|
6
|
+
from teaql.sql.executor import SqlTransactionTransport, SqlTransactionTransportTx
|
|
7
7
|
from teaql.sql.types import CompiledQuery
|
|
8
8
|
from teaql.core.value import Value, DataType, Timestamp
|
|
9
9
|
|
|
10
|
-
class PostgresTransport(
|
|
10
|
+
class PostgresTransport(SqlTransactionTransport):
|
|
11
11
|
def __init__(self, db_url: str):
|
|
12
12
|
self.db_url = db_url
|
|
13
13
|
|
|
@@ -88,3 +88,47 @@ class PostgresTransport(SqlTransport):
|
|
|
88
88
|
return affected_rows, 0
|
|
89
89
|
finally:
|
|
90
90
|
await conn.close()
|
|
91
|
+
|
|
92
|
+
async def begin_sql(self) -> SqlTransactionTransportTx:
|
|
93
|
+
conn = await asyncpg.connect(self.db_url)
|
|
94
|
+
try:
|
|
95
|
+
transaction = conn.transaction()
|
|
96
|
+
await transaction.start()
|
|
97
|
+
return _PostgresTransaction(conn, transaction, self)
|
|
98
|
+
except BaseException:
|
|
99
|
+
await conn.close()
|
|
100
|
+
raise
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
class _PostgresTransaction(SqlTransactionTransportTx):
|
|
104
|
+
def __init__(self, conn, transaction, owner: PostgresTransport):
|
|
105
|
+
self._conn = conn
|
|
106
|
+
self._transaction = transaction
|
|
107
|
+
self._owner = owner
|
|
108
|
+
|
|
109
|
+
async def fetch_all_sql(self, query: CompiledQuery) -> List[Dict[str, Any]]:
|
|
110
|
+
rows = await self._conn.fetch(query.sql_with_comment(), *self._owner._bind_values(query.params))
|
|
111
|
+
return [
|
|
112
|
+
{key: self._owner._decode_value(value) for key, value in row.items()}
|
|
113
|
+
for row in rows
|
|
114
|
+
]
|
|
115
|
+
|
|
116
|
+
async def execute_sql(self, query: CompiledQuery) -> tuple[int, int]:
|
|
117
|
+
status = await self._conn.execute(query.sql_with_comment(), *self._owner._bind_values(query.params))
|
|
118
|
+
if status.startswith("INSERT "):
|
|
119
|
+
return int(status.split()[-1]), 0
|
|
120
|
+
if status.startswith(("UPDATE ", "DELETE ")):
|
|
121
|
+
return int(status.split()[-1]), 0
|
|
122
|
+
return 0, 0
|
|
123
|
+
|
|
124
|
+
async def commit_sql(self) -> None:
|
|
125
|
+
try:
|
|
126
|
+
await self._transaction.commit()
|
|
127
|
+
finally:
|
|
128
|
+
await self._conn.close()
|
|
129
|
+
|
|
130
|
+
async def rollback_sql(self) -> None:
|
|
131
|
+
try:
|
|
132
|
+
await self._transaction.rollback()
|
|
133
|
+
finally:
|
|
134
|
+
await self._conn.close()
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
from __future__ import annotations
|
|
2
2
|
|
|
3
|
+
from contextlib import nullcontext
|
|
3
4
|
from dataclasses import dataclass, field
|
|
4
5
|
from datetime import datetime
|
|
5
6
|
from typing import Any, Awaitable, Callable, Dict, Mapping, Optional
|
|
@@ -164,27 +165,31 @@ class TfpHttpProvider(DataService):
|
|
|
164
165
|
)
|
|
165
166
|
|
|
166
167
|
async def mutate(self, context: Any, request: MutationRequest) -> MutationResult:
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
"
|
|
175
|
-
|
|
176
|
-
"
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
168
|
+
if context is not None and not context.consume_mutation_checked(request._data):
|
|
169
|
+
context.check_and_fix_mutation(request._data)
|
|
170
|
+
scope = context.mutation_policy_execution(request) if context is not None else nullcontext()
|
|
171
|
+
with scope:
|
|
172
|
+
started_at = datetime.now()
|
|
173
|
+
federal = _mutation_request(request)
|
|
174
|
+
data = await self.federal_client.execute_mutation(federal)
|
|
175
|
+
records = data.get("data") or []
|
|
176
|
+
generated = records[0] if records else {}
|
|
177
|
+
affected = int(data.get("affectedRows", 0))
|
|
178
|
+
operation = {
|
|
179
|
+
"Create": DataServiceOperation.Insert,
|
|
180
|
+
"Update": DataServiceOperation.Update,
|
|
181
|
+
"Delete": DataServiceOperation.Delete,
|
|
182
|
+
"Recover": DataServiceOperation.Recover,
|
|
183
|
+
}[federal.action]
|
|
184
|
+
return MutationResult(
|
|
185
|
+
affected_rows=affected, generated_values=generated,
|
|
186
|
+
persisted_record=generated or None,
|
|
187
|
+
metadata=ExecutionMetadata(
|
|
188
|
+
backend="teaql-federal", operation=operation,
|
|
189
|
+
started_at=started_at, ended_at=datetime.now(), affected_rows=affected,
|
|
190
|
+
comment=federal.comment,
|
|
191
|
+
),
|
|
192
|
+
)
|
|
188
193
|
|
|
189
194
|
|
|
190
195
|
def _federal_query_payload(query: FederalQuery) -> Dict[str, Any]:
|
|
@@ -10,12 +10,44 @@ from .tools import (
|
|
|
10
10
|
from .module import RuntimeModule, DefaultEntityDataServiceBehavior
|
|
11
11
|
from .store import DataStore
|
|
12
12
|
from .audit import RawAuditEvent, SafeAuditEvent, MutationAuditKind
|
|
13
|
+
from .mutation_policy import (
|
|
14
|
+
MISSING_APPROVAL,
|
|
15
|
+
MISSING_POLICY,
|
|
16
|
+
DelegatingMutationGovernanceSink,
|
|
17
|
+
DelegatingMutationPolicyApprovalProvider,
|
|
18
|
+
DelegatingMutationPolicyRegistry,
|
|
19
|
+
MutationDecision,
|
|
20
|
+
MutationGovernanceEvent,
|
|
21
|
+
MutationGovernanceSnapshot,
|
|
22
|
+
MutationOperation,
|
|
23
|
+
MutationOperationKind,
|
|
24
|
+
MutationOperationSummary,
|
|
25
|
+
MutationPlan,
|
|
26
|
+
MutationPolicyApproval,
|
|
27
|
+
MutationPolicyApprovalStatus,
|
|
28
|
+
MutationPolicyError,
|
|
29
|
+
MutationPolicyIdentity,
|
|
30
|
+
MutationPolicySource,
|
|
31
|
+
MutationVerdict,
|
|
32
|
+
)
|
|
13
33
|
from .i18n import CheckException, CheckResult, I18nCatalog, JsonFieldNamingProfile, Locale, ObjectLocation, UnsupportedLocaleError
|
|
14
34
|
from .wire_fields import NormalizedWireInput, WireEntityMetadata, WireFieldMetadata, WireInputError, create_wire_entity_metadata, encode_wire_output, normalize_wire_input, retain_submitted_paths
|
|
15
35
|
from teaql.core.entity import EntityKey, EntityChangeSet, EntityRoot
|
|
16
36
|
|
|
17
37
|
__all__ = ["WireFieldMetadata", "WireEntityMetadata", "NormalizedWireInput", "WireInputError", "create_wire_entity_metadata", "normalize_wire_input", "encode_wire_output", "retain_submitted_paths", "EntityKey", "EntityChangeSet", "EntityRoot", "ContextEntityRef", "ContextRootError", "CheckException", "CheckResult", "I18nCatalog", "JsonFieldNamingProfile", "Locale", "ObjectLocation", "UnsupportedLocaleError", "UserContext", "TeaqlRuntime", "SqlLogEntry", "SqlLogOperation", "DiagnosticSqlLogSink", "TextDiagnosticSqlLogSink", "ServiceRuntimeFromEnv", "RuntimeModule", "DataStore", "RawAuditEvent", "SafeAuditEvent", "MutationAuditKind", "ContextTools", "ExecutableHttpTool", "HTTP_TOOL", "HttpIntentPhase", "HttpTool", "HttpToolProvider", "ToolDeniedError", "ToolError", "ToolPolicy", "ToolRisk", "Tools", "ToolToken", "ToolUnavailableError"]
|
|
18
38
|
|
|
39
|
+
__all__ += [
|
|
40
|
+
"MISSING_APPROVAL", "MISSING_POLICY",
|
|
41
|
+
"DelegatingMutationGovernanceSink",
|
|
42
|
+
"DelegatingMutationPolicyApprovalProvider",
|
|
43
|
+
"DelegatingMutationPolicyRegistry", "MutationDecision",
|
|
44
|
+
"MutationGovernanceEvent", "MutationGovernanceSnapshot",
|
|
45
|
+
"MutationOperation", "MutationOperationKind", "MutationOperationSummary",
|
|
46
|
+
"MutationPlan", "MutationPolicyApproval", "MutationPolicyApprovalStatus",
|
|
47
|
+
"MutationPolicyError", "MutationPolicyIdentity", "MutationPolicySource",
|
|
48
|
+
"MutationVerdict",
|
|
49
|
+
]
|
|
50
|
+
|
|
19
51
|
|
|
20
52
|
def __getattr__(name):
|
|
21
53
|
# Keep provider construction lazy: importing a SQL provider loads runtime
|
|
@@ -27,6 +27,7 @@ class RawAuditEvent:
|
|
|
27
27
|
trace_chain: tuple[Any, ...] = field(default_factory=tuple)
|
|
28
28
|
actor: Optional[str] = None
|
|
29
29
|
category: Optional[str] = None
|
|
30
|
+
mutation_governance: Any = None
|
|
30
31
|
|
|
31
32
|
def safe(self, mask_fields: List[str], max_length: Optional[int]) -> "SafeAuditEvent":
|
|
32
33
|
from .log_privacy import REDACTED, credential_name, payload_has_credentials, plaintext_enabled, scrub, value_strings
|
|
@@ -35,22 +36,23 @@ class RawAuditEvent:
|
|
|
35
36
|
fields = []
|
|
36
37
|
for change in self.changes:
|
|
37
38
|
value = None if change.new_value is None else str(getattr(change.new_value, "val", change.new_value))
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
39
|
+
credential = (credential_name(change.field)
|
|
40
|
+
or payload_has_credentials(change.new_value)
|
|
41
|
+
or payload_has_credentials(change.old_value))
|
|
42
|
+
masked = credential or (change.field in mask_fields and not allow)
|
|
42
43
|
if masked:
|
|
43
44
|
secrets.extend(value_strings(change.old_value))
|
|
44
45
|
secrets.extend(value_strings(change.new_value))
|
|
45
46
|
if value is not None and masked:
|
|
46
|
-
value = REDACTED
|
|
47
|
+
value = REDACTED if credential else _mask(value)
|
|
47
48
|
truncated = value is not None and max_length is not None and len(value) > max_length
|
|
48
49
|
if truncated:
|
|
49
50
|
value = "*" * max_length if max_length <= 3 else value[:max_length - 3] + "..."
|
|
50
51
|
fields.append(SafeAuditField(change.field, value, masked, truncated))
|
|
52
|
+
intent_values = secrets + value_strings(self.entity_id)
|
|
51
53
|
return SafeAuditEvent(
|
|
52
|
-
self.kind, self.entity, self.entity_id, scrub(tuple(fields), secrets), scrub(self.trace_chain,
|
|
53
|
-
scrub(self.actor,
|
|
54
|
+
self.kind, self.entity, self.entity_id, scrub(tuple(fields), secrets), scrub(self.trace_chain, intent_values),
|
|
55
|
+
scrub(self.actor, intent_values), self.category, self.mutation_governance,
|
|
54
56
|
)
|
|
55
57
|
|
|
56
58
|
|
|
@@ -71,10 +73,12 @@ class SafeAuditEvent:
|
|
|
71
73
|
trace_chain: tuple[Any, ...] = field(default_factory=tuple)
|
|
72
74
|
actor: Optional[str] = None
|
|
73
75
|
category: Optional[str] = None
|
|
76
|
+
mutation_governance: Any = None
|
|
74
77
|
|
|
75
78
|
|
|
76
79
|
def _mask(value: str) -> str:
|
|
77
|
-
|
|
80
|
+
# Unicode scalar length, ASCII digits: the same contract as Rust and Go.
|
|
81
|
+
if len(value) < 8 or (value.isascii() and value.isdigit()):
|
|
78
82
|
return "*" * len(value)
|
|
79
83
|
return value[:2] + "*" * (len(value) - 4) + value[-2:]
|
|
80
84
|
|
|
@@ -105,6 +105,8 @@ class UserContext:
|
|
|
105
105
|
self._fix_evidence_current: List[FixEvidence] = []
|
|
106
106
|
self._fix_evidence_last: List[FixEvidence] = []
|
|
107
107
|
self._checked_mutations = set()
|
|
108
|
+
from .mutation_policy import MutationPolicyRuntimeState
|
|
109
|
+
self._mutation_policy = MutationPolicyRuntimeState()
|
|
108
110
|
|
|
109
111
|
def begin_fix_evidence(self):
|
|
110
112
|
self._fix_evidence_current = []
|
|
@@ -159,6 +161,7 @@ class UserContext:
|
|
|
159
161
|
transaction = await begin()
|
|
160
162
|
owner_token = self._graph_save_owner.set(object())
|
|
161
163
|
self._graph_save_active = True
|
|
164
|
+
self._mutation_policy.begin_graph()
|
|
162
165
|
self._graph_commit_actions = []
|
|
163
166
|
self._graph_rollback_actions = []
|
|
164
167
|
self.insert_resource("fix_time", datetime.now())
|
|
@@ -175,6 +178,7 @@ class UserContext:
|
|
|
175
178
|
raise
|
|
176
179
|
else:
|
|
177
180
|
try:
|
|
181
|
+
self._mutation_policy.ensure_graph_complete()
|
|
178
182
|
await self._finish_graph_transaction(transaction, "commit")
|
|
179
183
|
except BaseException:
|
|
180
184
|
try:
|
|
@@ -189,6 +193,7 @@ class UserContext:
|
|
|
189
193
|
finally:
|
|
190
194
|
self.insert_resource("dataService", provider)
|
|
191
195
|
self._graph_save_active = False
|
|
196
|
+
self._mutation_policy.end_graph()
|
|
192
197
|
self._graph_commit_actions = []
|
|
193
198
|
self._graph_rollback_actions = []
|
|
194
199
|
self._resources.pop("fix_time", None)
|
|
@@ -639,6 +644,41 @@ class UserContext:
|
|
|
639
644
|
self._app_audit_sink = sink
|
|
640
645
|
return self
|
|
641
646
|
|
|
647
|
+
def with_mutation_policy_registry(self, registry: Any) -> 'UserContext':
|
|
648
|
+
if registry is None or not callable(getattr(registry, "resolve", None)):
|
|
649
|
+
raise TypeError("mutation policy registry must expose resolve(request_key)")
|
|
650
|
+
self._mutation_policy.registry = registry
|
|
651
|
+
return self
|
|
652
|
+
|
|
653
|
+
def with_mutation_policy_approval_provider(self, provider: Any) -> 'UserContext':
|
|
654
|
+
if provider is None or not callable(getattr(provider, "find_approval", None)):
|
|
655
|
+
raise TypeError(
|
|
656
|
+
"mutation policy approval provider must expose find_approval(identity)"
|
|
657
|
+
)
|
|
658
|
+
self._mutation_policy.approval_provider = provider
|
|
659
|
+
return self
|
|
660
|
+
|
|
661
|
+
def with_mutation_governance_sink(self, sink: Any) -> 'UserContext':
|
|
662
|
+
if sink is None or not callable(getattr(sink, "on_warning", None)):
|
|
663
|
+
raise TypeError("mutation governance sink must expose on_warning(context, event)")
|
|
664
|
+
self._mutation_policy.warning_sink = sink
|
|
665
|
+
return self
|
|
666
|
+
|
|
667
|
+
def current_mutation_governance(self):
|
|
668
|
+
return self._mutation_policy.current
|
|
669
|
+
|
|
670
|
+
def review_mutation_plan(self, plan: Any):
|
|
671
|
+
return self._mutation_policy.review(self, plan)
|
|
672
|
+
|
|
673
|
+
def preflight_mutation(self, mutation: Any) -> None:
|
|
674
|
+
"""Check/fix and snapshot one operation for whole-graph policy review."""
|
|
675
|
+
self.check_and_fix_mutation(mutation)
|
|
676
|
+
self._mutation_policy.record_preflight(mutation)
|
|
677
|
+
|
|
678
|
+
def mutation_policy_execution(self, request: Any):
|
|
679
|
+
"""Provider boundary scope; entered after validation and before mutation."""
|
|
680
|
+
return self._mutation_policy.enter_mutation(self, request)
|
|
681
|
+
|
|
642
682
|
def with_sql_log_options(self, options: 'SqlLogOptions') -> 'UserContext':
|
|
643
683
|
self.insert_resource("sql_log_options", options)
|
|
644
684
|
return self
|
|
@@ -705,6 +745,10 @@ class UserContext:
|
|
|
705
745
|
return self.get_resource("locale") or Locale.ENGLISH
|
|
706
746
|
|
|
707
747
|
def record_metadata_log(self, metadata: Any):
|
|
748
|
+
self._record_metadata_log(metadata)
|
|
749
|
+
|
|
750
|
+
def _record_metadata_log(self, metadata: Any, *, intent_source=None, intent_values=()):
|
|
751
|
+
"""Internal statement plumbing: source bindings never reach sinks/buffers."""
|
|
708
752
|
op = SqlLogOperation.Select
|
|
709
753
|
op_str = str(getattr(metadata, 'operation', '')).lower()
|
|
710
754
|
if 'insert' in op_str: op = SqlLogOperation.Insert
|
|
@@ -726,6 +770,10 @@ class UserContext:
|
|
|
726
770
|
params=list(getattr(metadata, 'parameters', [])),
|
|
727
771
|
debug_sql=getattr(metadata, 'debug_query', '') or '',
|
|
728
772
|
pretty_sql=getattr(metadata, 'debug_query', '') or '',
|
|
773
|
+
database_kind=getattr(metadata, 'database_kind', None),
|
|
774
|
+
parameter_log_policies=getattr(metadata, 'parameter_log_policies', None),
|
|
775
|
+
sql_origin=getattr(metadata, 'sql_origin', None),
|
|
776
|
+
execution_outcome=getattr(metadata, 'execution_outcome', None),
|
|
729
777
|
started_at=started_at,
|
|
730
778
|
ended_at=ended_at,
|
|
731
779
|
elapsed=ended_at - started_at,
|
|
@@ -740,13 +788,11 @@ class UserContext:
|
|
|
740
788
|
entry.result_summary = f"{entry.affected_rows} rows affected"
|
|
741
789
|
|
|
742
790
|
from .log_privacy import sql_log_projection
|
|
743
|
-
entry = sql_log_projection(entry)
|
|
791
|
+
entry = sql_log_projection(entry, _intent_source=intent_source, _intent_values=intent_values)
|
|
744
792
|
logs = self.sql_logs()
|
|
745
793
|
logs.append(entry)
|
|
746
794
|
self._resources["sql_logs"] = logs
|
|
747
|
-
|
|
748
|
-
if sink is not None:
|
|
749
|
-
sink.write(entry)
|
|
795
|
+
self._write_diagnostic_sql_log(entry)
|
|
750
796
|
buf = self.get_resource("UnifiedLogBuffer")
|
|
751
797
|
if buf:
|
|
752
798
|
buf.entries.append(UnifiedLogEntry(
|
|
@@ -760,7 +806,8 @@ class UserContext:
|
|
|
760
806
|
if not self.sql_log_options().enabled_for(operation):
|
|
761
807
|
return
|
|
762
808
|
|
|
763
|
-
|
|
809
|
+
# Projection renders only safe values. Never materialize plaintext first.
|
|
810
|
+
debug_sql = ''
|
|
764
811
|
|
|
765
812
|
entry = SqlLogEntry(
|
|
766
813
|
operation=operation,
|
|
@@ -772,6 +819,9 @@ class UserContext:
|
|
|
772
819
|
params=getattr(query, 'params', []),
|
|
773
820
|
debug_sql=debug_sql,
|
|
774
821
|
pretty_sql=debug_sql,
|
|
822
|
+
database_kind=getattr(query, 'database_kind', None),
|
|
823
|
+
parameter_log_policies=getattr(query, 'parameter_log_policies', None),
|
|
824
|
+
sql_origin=getattr(query, 'sql_origin', None),
|
|
775
825
|
started_at=started_at,
|
|
776
826
|
ended_at=ended_at,
|
|
777
827
|
elapsed=elapsed,
|
|
@@ -791,9 +841,7 @@ class UserContext:
|
|
|
791
841
|
logs = self.sql_logs()
|
|
792
842
|
logs.append(entry)
|
|
793
843
|
self._resources["sql_logs"] = logs
|
|
794
|
-
|
|
795
|
-
if sink is not None:
|
|
796
|
-
sink.write(entry)
|
|
844
|
+
self._write_diagnostic_sql_log(entry)
|
|
797
845
|
|
|
798
846
|
buf = self.get_resource("UnifiedLogBuffer")
|
|
799
847
|
if buf:
|
|
@@ -804,6 +852,17 @@ class UserContext:
|
|
|
804
852
|
payload=LogPayload.Sql(entry)
|
|
805
853
|
))
|
|
806
854
|
|
|
855
|
+
def _write_diagnostic_sql_log(self, entry: 'SqlLogEntry'):
|
|
856
|
+
sink = self.get_resource("diagnostic_sql_log_sink")
|
|
857
|
+
if sink is None:
|
|
858
|
+
return
|
|
859
|
+
try:
|
|
860
|
+
sink.write(entry)
|
|
861
|
+
except Exception:
|
|
862
|
+
# An optional diagnostic destination must not change SQL outcomes.
|
|
863
|
+
# Do not print the exception: custom sinks may include raw values.
|
|
864
|
+
pass
|
|
865
|
+
|
|
807
866
|
def register_executor(self, executor: Any):
|
|
808
867
|
self.insert_resource("executor", executor)
|
|
809
868
|
|
|
@@ -1035,6 +1094,13 @@ class SqlLogEntry:
|
|
|
1035
1094
|
result_type: Optional[str]
|
|
1036
1095
|
affected_rows: Optional[int]
|
|
1037
1096
|
result_summary: str
|
|
1097
|
+
database_kind: Any = None
|
|
1098
|
+
parameter_log_policies: Optional[List[str]] = None
|
|
1099
|
+
sql_origin: Optional[str] = None
|
|
1100
|
+
masked_parameters: Optional[List[bool]] = None
|
|
1101
|
+
log_mode: Optional[str] = None
|
|
1102
|
+
omission_reason: Optional[str] = None
|
|
1103
|
+
execution_outcome: Optional[str] = None
|
|
1038
1104
|
|
|
1039
1105
|
class DiagnosticSqlLogSink:
|
|
1040
1106
|
"""Policy-projected SQL destination; the text sink is installed by default."""
|
|
@@ -1051,9 +1117,9 @@ class TextDiagnosticSqlLogSink(DiagnosticSqlLogSink):
|
|
|
1051
1117
|
elapsed_us = int(entry.elapsed.total_seconds() * 1_000_000) if entry.elapsed else 0
|
|
1052
1118
|
self._writer(
|
|
1053
1119
|
f"[TeaQL SQL][{entry.operation.name.lower()}][{elapsed_us}us] "
|
|
1054
|
-
f"{entry.result_summary} comment={entry.comment!r} purpose={entry.purpose!r} "
|
|
1120
|
+
f"{entry.result_summary} outcome={entry.execution_outcome or 'unknown'} comment={entry.comment!r} purpose={entry.purpose!r} "
|
|
1055
1121
|
f"auditReason={entry.audit_reason!r} tracePath={entry.trace_path!r}\n"
|
|
1056
|
-
f"
|
|
1122
|
+
f"SQL omission reason: {entry.omission_reason or 'none'}\n"
|
|
1057
1123
|
f"Debug SQL: {entry.debug_sql}"
|
|
1058
1124
|
)
|
|
1059
1125
|
|