unitysvc-core 0.3.6__tar.gz → 0.3.7__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.
- {unitysvc_core-0.3.6/src/unitysvc_core.egg-info → unitysvc_core-0.3.7}/PKG-INFO +18 -1
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/README.md +17 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/pyproject.toml +2 -2
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/models/__init__.py +4 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/models/channel.py +110 -0
- unitysvc_core-0.3.7/src/unitysvc_core/rules.py +301 -0
- unitysvc_core-0.3.7/src/unitysvc_core/rules_conformance.json +91 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/schema/offering_v1.json +127 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7/src/unitysvc_core.egg-info}/PKG-INFO +18 -1
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core.egg-info/SOURCES.txt +3 -0
- unitysvc_core-0.3.7/tests/test_request_rules.py +220 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/tests/test_validate_service.py +31 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/LICENSE +0 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/setup.cfg +0 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/__init__.py +0 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/grants.py +0 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/models/base.py +0 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/models/documents.py +0 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/models/listing_data.py +0 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/models/listing_v1.py +0 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/models/offering_data.py +0 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/models/offering_v1.py +0 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/models/pricing.py +0 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/models/promotion_data.py +0 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/models/provider_data.py +0 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/models/provider_v1.py +0 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/models/service.py +0 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/models/service_group_data.py +0 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/models/validators.py +0 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/parameter_usage.py +0 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/py.typed +0 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/schema/base.json +0 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/schema/listing_v1.json +0 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/schema/promotion_v1.json +0 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/schema/provider_v1.json +0 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/schema/service_group_v1.json +0 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/utils.py +0 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/validator.py +0 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core.egg-info/dependency_links.txt +0 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core.egg-info/requires.txt +0 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core.egg-info/top_level.txt +0 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/tests/test_access_interface_routing.py +0 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/tests/test_canonical_interfaces.py +0 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/tests/test_channel.py +0 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/tests/test_effective_price.py +0 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/tests/test_external_apps.py +0 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/tests/test_grants.py +0 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/tests/test_hidden_path_skip.py +0 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/tests/test_listing_audience.py +0 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/tests/test_offering_data.py +0 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/tests/test_parameter_usage.py +0 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/tests/test_pricing.py +0 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/tests/test_provider_account_rate_limits.py +0 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/tests/test_service_group.py +0 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/tests/test_service_status.py +0 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/tests/test_utils.py +0 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/tests/test_validator.py +0 -0
- {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/tests/test_validators.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: unitysvc-core
|
|
3
|
-
Version: 0.3.
|
|
3
|
+
Version: 0.3.7
|
|
4
4
|
Summary: Shared data models and validation helpers for UnitySVC packages
|
|
5
5
|
Author-email: Bo Peng <bo.peng@unitysvc.com>
|
|
6
6
|
Maintainer-email: Bo Peng <bo.peng@unitysvc.com>
|
|
@@ -266,12 +266,29 @@ A policy has three kinds of entry (unitysvc/unitysvc#2770):
|
|
|
266
266
|
| `rate_limit_refs` | the provider rate limits it consumes |
|
|
267
267
|
| `customer_access_requests` | what the enrolling customer is asked to approve (see above) |
|
|
268
268
|
| `params` | the enrollment parameters (below) |
|
|
269
|
+
| `request_rules` | `http` channels only: rules the gateway answers itself before dispatch (below) |
|
|
269
270
|
| `servers` | the connection: `HttpServer`, `SmtpServer`, `S3Server` or `McpServer` |
|
|
270
271
|
|
|
271
272
|
The common one-server case writes the connection fields directly on the channel; they are read as `servers[0]`. When a channel has both, each server inherits the direct fields it does not set. Any string may be a template (`{{ params.X }}`, `${ secrets.X }`, `${ customer_secrets.X ?? default }`), so numeric and boolean connection fields also accept strings.
|
|
272
273
|
|
|
273
274
|
Unknown keys are refused. Retired keys are refused with what to do instead (`RETIRED_CHANNEL_KEYS`): `raw`, `is_primary`, the listing-style parameter trio, `grants`, `rate_limits` (nothing reads it; use `rate_limit_refs`), `storage_type` (use `access_method: s3`), `response_rules`, `timeout_ms`, `transport`, and the platform-derived `customer_secrets_required` / `customer_secrets_optional`.
|
|
274
275
|
|
|
276
|
+
### Request rules
|
|
277
|
+
|
|
278
|
+
An `http` channel may list up to 32 `request_rules` (unitysvc/unitysvc#2947). The gateway checks them in order after authentication, channel selection and rate limiting and before anything is dispatched. The first rule whose `when` holds answers with its static `respond`, and the request goes no further; when none holds, the request continues unchanged. A rule without `when` answers every request.
|
|
279
|
+
|
|
280
|
+
```json
|
|
281
|
+
"request_rules": [
|
|
282
|
+
{"name": "github-ping", "when": "header['x-github-event'] == 'ping'", "respond": {"status": 200}},
|
|
283
|
+
{"name": "own-echo", "when": "body.user_id == '${ customer_secrets.DISCORD_WEBHOOK_ID ?? }'", "respond": {"status": 204}},
|
|
284
|
+
{"when": "'[bot]' in body.sender.login", "respond": {"status": 204}}
|
|
285
|
+
]
|
|
286
|
+
```
|
|
287
|
+
|
|
288
|
+
A condition is one string comparison: `ref == 'lit'`, `ref in 'lit'` (the request value is a non-empty substring of the literal) or `'lit' in ref` (the literal is a non-empty substring of the request value). `ref` is `body.<key>…` (the JSON body), `header['name']`, `query['name']` or `method`; a request value that is not a string never matches. A literal whose whole content is one reference (`'${ customer_secrets.X ?? }'`, `'${ secrets.X }'`, `'{{ params.X }}'`, `'{{ enrollment.code }}'`) is filled with the resolved value at evaluation, never spliced into the text; unset or empty, it never matches. A secret may only be compared with `==`, since a substring test would reveal it one character at a time.
|
|
289
|
+
|
|
290
|
+
`respond` takes a `status` (200–599), an optional `body` (an object or array is sent as JSON; a string needs `content_type`), and optional `headers` (not the gateway-managed or hop-by-hop ones). `unitysvc_core.rules` parses conditions; `rules_conformance.json`, shipped in the package, holds the cases the gateway's evaluator must also pass.
|
|
291
|
+
|
|
275
292
|
### External apps and product links
|
|
276
293
|
|
|
277
294
|
An offering that declares no channel (`upstream_access_config` omitted or `{}`) is an **external app**: customers reach it at its own site, not through the gateway (unitysvc/unitysvc#2873). `external` is not a channel type. An external app:
|
|
@@ -231,12 +231,29 @@ A policy has three kinds of entry (unitysvc/unitysvc#2770):
|
|
|
231
231
|
| `rate_limit_refs` | the provider rate limits it consumes |
|
|
232
232
|
| `customer_access_requests` | what the enrolling customer is asked to approve (see above) |
|
|
233
233
|
| `params` | the enrollment parameters (below) |
|
|
234
|
+
| `request_rules` | `http` channels only: rules the gateway answers itself before dispatch (below) |
|
|
234
235
|
| `servers` | the connection: `HttpServer`, `SmtpServer`, `S3Server` or `McpServer` |
|
|
235
236
|
|
|
236
237
|
The common one-server case writes the connection fields directly on the channel; they are read as `servers[0]`. When a channel has both, each server inherits the direct fields it does not set. Any string may be a template (`{{ params.X }}`, `${ secrets.X }`, `${ customer_secrets.X ?? default }`), so numeric and boolean connection fields also accept strings.
|
|
237
238
|
|
|
238
239
|
Unknown keys are refused. Retired keys are refused with what to do instead (`RETIRED_CHANNEL_KEYS`): `raw`, `is_primary`, the listing-style parameter trio, `grants`, `rate_limits` (nothing reads it; use `rate_limit_refs`), `storage_type` (use `access_method: s3`), `response_rules`, `timeout_ms`, `transport`, and the platform-derived `customer_secrets_required` / `customer_secrets_optional`.
|
|
239
240
|
|
|
241
|
+
### Request rules
|
|
242
|
+
|
|
243
|
+
An `http` channel may list up to 32 `request_rules` (unitysvc/unitysvc#2947). The gateway checks them in order after authentication, channel selection and rate limiting and before anything is dispatched. The first rule whose `when` holds answers with its static `respond`, and the request goes no further; when none holds, the request continues unchanged. A rule without `when` answers every request.
|
|
244
|
+
|
|
245
|
+
```json
|
|
246
|
+
"request_rules": [
|
|
247
|
+
{"name": "github-ping", "when": "header['x-github-event'] == 'ping'", "respond": {"status": 200}},
|
|
248
|
+
{"name": "own-echo", "when": "body.user_id == '${ customer_secrets.DISCORD_WEBHOOK_ID ?? }'", "respond": {"status": 204}},
|
|
249
|
+
{"when": "'[bot]' in body.sender.login", "respond": {"status": 204}}
|
|
250
|
+
]
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
A condition is one string comparison: `ref == 'lit'`, `ref in 'lit'` (the request value is a non-empty substring of the literal) or `'lit' in ref` (the literal is a non-empty substring of the request value). `ref` is `body.<key>…` (the JSON body), `header['name']`, `query['name']` or `method`; a request value that is not a string never matches. A literal whose whole content is one reference (`'${ customer_secrets.X ?? }'`, `'${ secrets.X }'`, `'{{ params.X }}'`, `'{{ enrollment.code }}'`) is filled with the resolved value at evaluation, never spliced into the text; unset or empty, it never matches. A secret may only be compared with `==`, since a substring test would reveal it one character at a time.
|
|
254
|
+
|
|
255
|
+
`respond` takes a `status` (200–599), an optional `body` (an object or array is sent as JSON; a string needs `content_type`), and optional `headers` (not the gateway-managed or hop-by-hop ones). `unitysvc_core.rules` parses conditions; `rules_conformance.json`, shipped in the package, holds the cases the gateway's evaluator must also pass.
|
|
256
|
+
|
|
240
257
|
### External apps and product links
|
|
241
258
|
|
|
242
259
|
An offering that declares no channel (`upstream_access_config` omitted or `{}`) is an **external app**: customers reach it at its own site, not through the gateway (unitysvc/unitysvc#2873). `external` is not a channel type. An external app:
|
|
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "unitysvc-core"
|
|
7
|
-
version = "0.3.
|
|
7
|
+
version = "0.3.7"
|
|
8
8
|
description = "Shared data models and validation helpers for UnitySVC packages"
|
|
9
9
|
readme = "README.md"
|
|
10
10
|
authors = [{ name = "Bo Peng", email = "bo.peng@unitysvc.com" }]
|
|
@@ -80,7 +80,7 @@ package = true
|
|
|
80
80
|
include-package-data = true
|
|
81
81
|
|
|
82
82
|
[tool.setuptools.package-data]
|
|
83
|
-
unitysvc_core = ["schema/*.json", "py.typed"]
|
|
83
|
+
unitysvc_core = ["schema/*.json", "py.typed", "rules_conformance.json"]
|
|
84
84
|
|
|
85
85
|
[tool.pytest.ini_options]
|
|
86
86
|
testpaths = ["tests"]
|
|
@@ -34,7 +34,9 @@ from .channel import (
|
|
|
34
34
|
HttpServer,
|
|
35
35
|
McpChannel,
|
|
36
36
|
McpServer,
|
|
37
|
+
RequestRule,
|
|
37
38
|
RequestTransformer,
|
|
39
|
+
RuleResponse,
|
|
38
40
|
S3Channel,
|
|
39
41
|
S3Server,
|
|
40
42
|
SmtpChannel,
|
|
@@ -131,7 +133,9 @@ __all__ = [
|
|
|
131
133
|
"SmtpServer",
|
|
132
134
|
"S3Server",
|
|
133
135
|
"McpServer",
|
|
136
|
+
"RequestRule",
|
|
134
137
|
"RequestTransformer",
|
|
138
|
+
"RuleResponse",
|
|
135
139
|
"RETIRED_CHANNEL_KEYS",
|
|
136
140
|
# Data models (for API/backend use)
|
|
137
141
|
"ProviderAccountRateLimit",
|
|
@@ -28,6 +28,8 @@ field also accepts a string.
|
|
|
28
28
|
"""
|
|
29
29
|
|
|
30
30
|
import builtins
|
|
31
|
+
import json
|
|
32
|
+
import re
|
|
31
33
|
from typing import Annotated, Any, ClassVar, Literal
|
|
32
34
|
|
|
33
35
|
from pydantic import (
|
|
@@ -44,6 +46,7 @@ from pydantic import (
|
|
|
44
46
|
from pydantic.json_schema import JsonSchemaValue
|
|
45
47
|
from pydantic_core import CoreSchema
|
|
46
48
|
|
|
49
|
+
from ..rules import MAX_RULES, parse_condition
|
|
47
50
|
from .validators import validate_channel_name
|
|
48
51
|
|
|
49
52
|
# A string field that is a value or a template rendering to one.
|
|
@@ -83,6 +86,99 @@ class RequestTransformer(BaseModel):
|
|
|
83
86
|
set_body: str | None = Field(default=None, description="Replace the request body with this template")
|
|
84
87
|
|
|
85
88
|
|
|
89
|
+
# Response headers a request rule may not set: the gateway manages them, they
|
|
90
|
+
# are hop-by-hop, or the response's content type has its own field.
|
|
91
|
+
_REFUSED_RULE_HEADERS = frozenset(
|
|
92
|
+
{
|
|
93
|
+
"connection",
|
|
94
|
+
"content-length",
|
|
95
|
+
"content-type",
|
|
96
|
+
"date",
|
|
97
|
+
"keep-alive",
|
|
98
|
+
"server",
|
|
99
|
+
"set-cookie",
|
|
100
|
+
"te",
|
|
101
|
+
"trailer",
|
|
102
|
+
"transfer-encoding",
|
|
103
|
+
"upgrade",
|
|
104
|
+
}
|
|
105
|
+
)
|
|
106
|
+
_HEADER_NAME_RE = re.compile(r"^[!#$%&'*+.^_`|~0-9A-Za-z-]+$")
|
|
107
|
+
_CONTENT_TYPE_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]*/[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]*([ \t]*;[ -~]*)?$")
|
|
108
|
+
_MAX_RULE_BODY_BYTES = 8192
|
|
109
|
+
_MAX_RULE_HEADERS = 16
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
class RuleResponse(BaseModel):
|
|
113
|
+
"""The static response a request rule answers with (unitysvc/unitysvc#2947)."""
|
|
114
|
+
|
|
115
|
+
model_config = ConfigDict(extra="forbid")
|
|
116
|
+
|
|
117
|
+
status: int = Field(ge=200, le=599, description="HTTP status, 200-599")
|
|
118
|
+
body: dict[str, Any] | list[Any] | str | None = Field(
|
|
119
|
+
default=None,
|
|
120
|
+
description="An object or array is sent as JSON; a string is sent as is, with content_type",
|
|
121
|
+
)
|
|
122
|
+
content_type: str | None = Field(default=None, description="Content type of a string body, e.g. text/plain")
|
|
123
|
+
headers: dict[str, str] | None = Field(default=None, description="Extra response headers")
|
|
124
|
+
|
|
125
|
+
@model_validator(mode="after")
|
|
126
|
+
def _check_response(self) -> "RuleResponse":
|
|
127
|
+
if self.body is not None and self.status in (204, 205, 304):
|
|
128
|
+
raise ValueError(f"a {self.status} response has no body")
|
|
129
|
+
if isinstance(self.body, str):
|
|
130
|
+
if self.content_type is None:
|
|
131
|
+
raise ValueError("a string body needs content_type")
|
|
132
|
+
size = len(self.body.encode())
|
|
133
|
+
else:
|
|
134
|
+
if self.content_type is not None:
|
|
135
|
+
raise ValueError("content_type is only for a string body; an object or array is sent as JSON")
|
|
136
|
+
size = len(json.dumps(self.body, ensure_ascii=False).encode()) if self.body is not None else 0
|
|
137
|
+
if size > _MAX_RULE_BODY_BYTES:
|
|
138
|
+
raise ValueError(f"the body is larger than {_MAX_RULE_BODY_BYTES} bytes")
|
|
139
|
+
if self.content_type is not None and not _CONTENT_TYPE_RE.fullmatch(self.content_type):
|
|
140
|
+
raise ValueError(f"content_type {self.content_type!r} is not a media type")
|
|
141
|
+
headers = self.headers or {}
|
|
142
|
+
if len(headers) > _MAX_RULE_HEADERS:
|
|
143
|
+
raise ValueError(f"at most {_MAX_RULE_HEADERS} headers")
|
|
144
|
+
for name, value in headers.items():
|
|
145
|
+
lower = name.lower()
|
|
146
|
+
if not _HEADER_NAME_RE.fullmatch(name):
|
|
147
|
+
raise ValueError(f"header name {name!r} is not valid")
|
|
148
|
+
if lower in _REFUSED_RULE_HEADERS or lower.startswith(("proxy-", "x-unitysvc-")):
|
|
149
|
+
raise ValueError(f"header {name!r} is managed by the gateway and cannot be set by a rule")
|
|
150
|
+
if "\r" in value or "\n" in value or len(value) > 1024:
|
|
151
|
+
raise ValueError(f"header {name!r} must be one line of at most 1024 characters")
|
|
152
|
+
return self
|
|
153
|
+
|
|
154
|
+
|
|
155
|
+
class RequestRule(BaseModel):
|
|
156
|
+
"""A condition the gateway checks before dispatch, and the response it answers with when it holds.
|
|
157
|
+
|
|
158
|
+
See :mod:`unitysvc_core.rules` for the condition language.
|
|
159
|
+
"""
|
|
160
|
+
|
|
161
|
+
model_config = ConfigDict(extra="forbid")
|
|
162
|
+
|
|
163
|
+
name: str | None = Field(
|
|
164
|
+
default=None,
|
|
165
|
+
pattern=r"^[a-z0-9][a-z0-9-]{0,47}$",
|
|
166
|
+
description="Shown in logs and the X-UnitySVC-Rule response header",
|
|
167
|
+
)
|
|
168
|
+
when: str | None = Field(
|
|
169
|
+
default=None,
|
|
170
|
+
description="The condition, e.g. header['x-github-event'] == 'ping'; absent means every request",
|
|
171
|
+
)
|
|
172
|
+
respond: RuleResponse
|
|
173
|
+
|
|
174
|
+
@field_validator("when")
|
|
175
|
+
@classmethod
|
|
176
|
+
def _check_condition(cls, value: str | None) -> str | None:
|
|
177
|
+
if value is not None:
|
|
178
|
+
parse_condition(value)
|
|
179
|
+
return value
|
|
180
|
+
|
|
181
|
+
|
|
86
182
|
class _Server(BaseModel):
|
|
87
183
|
"""Fields every server has, whatever its protocol."""
|
|
88
184
|
|
|
@@ -252,6 +348,20 @@ class HttpChannel(_ChannelBase):
|
|
|
252
348
|
server_model: ClassVar[builtins.type[_Server]] = HttpServer
|
|
253
349
|
access_method: Literal["http"] = "http"
|
|
254
350
|
servers: list[HttpServer] = Field(default_factory=list)
|
|
351
|
+
request_rules: list[RequestRule] | None = Field(
|
|
352
|
+
default=None,
|
|
353
|
+
min_length=1,
|
|
354
|
+
max_length=MAX_RULES,
|
|
355
|
+
description="Rules the gateway checks in order before dispatch; the first that holds answers the request",
|
|
356
|
+
)
|
|
357
|
+
|
|
358
|
+
@field_validator("request_rules")
|
|
359
|
+
@classmethod
|
|
360
|
+
def _unique_rule_names(cls, rules: list[RequestRule] | None) -> list[RequestRule] | None:
|
|
361
|
+
names = [rule.name for rule in rules or [] if rule.name is not None]
|
|
362
|
+
if duplicates := sorted({name for name in names if names.count(name) > 1}):
|
|
363
|
+
raise ValueError(f"rule names must be unique: {', '.join(duplicates)}")
|
|
364
|
+
return rules
|
|
255
365
|
|
|
256
366
|
|
|
257
367
|
class SmtpChannel(_ChannelBase):
|
|
@@ -0,0 +1,301 @@
|
|
|
1
|
+
"""Request rules: conditions a channel's gateway answers itself (unitysvc/unitysvc#2947).
|
|
2
|
+
|
|
3
|
+
A channel's ``request_rules`` lists rules the gateway checks, in order, after
|
|
4
|
+
authentication, channel selection and rate limiting and before anything is
|
|
5
|
+
dispatched. The first rule whose condition holds answers the request with its
|
|
6
|
+
static response; when none holds the request continues unchanged::
|
|
7
|
+
|
|
8
|
+
"request_rules": [
|
|
9
|
+
{"name": "github-ping", "when": "header['x-github-event'] == 'ping'",
|
|
10
|
+
"respond": {"status": 200}},
|
|
11
|
+
{"when": "body.user_id == '${ customer_secrets.DISCORD_WEBHOOK_ID ?? }'",
|
|
12
|
+
"respond": {"status": 204}}
|
|
13
|
+
]
|
|
14
|
+
|
|
15
|
+
A condition is one string comparison between a request value and a literal::
|
|
16
|
+
|
|
17
|
+
when := ref "==" literal | ref "in" literal | literal "in" ref
|
|
18
|
+
ref := root ( "." ident | "[" string "]" )*
|
|
19
|
+
root := "body" | "header" | "query" | "method"
|
|
20
|
+
literal := a quoted string ('...' or "...", escapes \\\\ \\' \\")
|
|
21
|
+
|
|
22
|
+
``ref in 'lit'`` holds when the request value is a non-empty substring of the
|
|
23
|
+
literal, ``'lit' in ref`` when the literal is a non-empty substring of the
|
|
24
|
+
request value. A request value that is not a string never matches.
|
|
25
|
+
|
|
26
|
+
A literal whose whole content is one reference is a **slot**:
|
|
27
|
+
``'${ customer_secrets.X }'``, ``'${ customer_secrets.X ?? default }'``,
|
|
28
|
+
``'${ secrets.X }'``, ``'{{ params.X }}'`` or ``'{{ enrollment.code }}'``. The
|
|
29
|
+
gateway fills a slot with the resolved value when it evaluates the condition;
|
|
30
|
+
the value is never spliced into the condition's text. A slot that is unset or
|
|
31
|
+
resolves to an empty string never matches. A secret slot may only be compared
|
|
32
|
+
with ``==``: in ``ref in '${ secret }'`` the caller controls ``ref`` and would
|
|
33
|
+
learn the secret one character at a time.
|
|
34
|
+
|
|
35
|
+
The gateway evaluates conditions (apisix-gateways ``lib/rules.lua``); this
|
|
36
|
+
module validates them at upload. :func:`evaluate` exists to run the shared
|
|
37
|
+
conformance cases (``rules_conformance.json``) that keep the two in step.
|
|
38
|
+
"""
|
|
39
|
+
|
|
40
|
+
from __future__ import annotations
|
|
41
|
+
|
|
42
|
+
import hmac
|
|
43
|
+
import re
|
|
44
|
+
from collections.abc import Mapping
|
|
45
|
+
from dataclasses import dataclass
|
|
46
|
+
from typing import Any, Literal
|
|
47
|
+
|
|
48
|
+
ROOTS = ("body", "header", "query", "method")
|
|
49
|
+
MAX_RULES = 32
|
|
50
|
+
MAX_CONDITION_LENGTH = 1024
|
|
51
|
+
MAX_LITERAL_LENGTH = 1024
|
|
52
|
+
MAX_REF_DEPTH = 16
|
|
53
|
+
|
|
54
|
+
_SECRET_NAMESPACES = ("secrets", "customer_secrets")
|
|
55
|
+
# Match Lua's %s, including when stripping a suffix with no next token.
|
|
56
|
+
_WHITESPACE = " \t\n\r\f\v"
|
|
57
|
+
_SECRET_SLOT_RE = re.compile(
|
|
58
|
+
r"^\$\{\s*(secrets|customer_secrets)\.([A-Za-z_][A-Za-z0-9_]*)\s*(?:\?\?\s*(.*?))?\s*\}$", re.DOTALL | re.ASCII
|
|
59
|
+
)
|
|
60
|
+
_PARAM_SLOT_RE = re.compile(r"^\{\{\s*(params\.[A-Za-z_][A-Za-z0-9_]*|enrollment\.code)\s*\}\}$", re.ASCII)
|
|
61
|
+
_IDENT_RE = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
|
|
62
|
+
_TOKEN_RE = re.compile(r"\s*(?:(==)|(\[)|(\])|(\.)|('|\")|([A-Za-z_][A-Za-z0-9_]*))", re.ASCII)
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
class RuleSyntaxError(ValueError):
|
|
66
|
+
"""A request-rule condition does not parse, or breaks a rule of the language."""
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
@dataclass(frozen=True)
|
|
70
|
+
class Ref:
|
|
71
|
+
"""A request value: a root and the keys looked up under it."""
|
|
72
|
+
|
|
73
|
+
root: str
|
|
74
|
+
keys: tuple[str, ...] = ()
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
@dataclass(frozen=True)
|
|
78
|
+
class Slot:
|
|
79
|
+
"""A literal that is one reference, filled when the gateway evaluates the condition."""
|
|
80
|
+
|
|
81
|
+
namespace: str # secrets, customer_secrets, params or enrollment
|
|
82
|
+
name: str
|
|
83
|
+
default: str | None = None # the ``?? default`` of a secret reference
|
|
84
|
+
|
|
85
|
+
@property
|
|
86
|
+
def key(self) -> str:
|
|
87
|
+
"""The reference without braces, e.g. ``customer_secrets.X``."""
|
|
88
|
+
return f"{self.namespace}.{self.name}"
|
|
89
|
+
|
|
90
|
+
@property
|
|
91
|
+
def is_secret(self) -> bool:
|
|
92
|
+
return self.namespace in _SECRET_NAMESPACES
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
@dataclass(frozen=True)
|
|
96
|
+
class Condition:
|
|
97
|
+
"""A parsed condition: ``ref == literal``, ``ref in literal`` or ``literal in ref``."""
|
|
98
|
+
|
|
99
|
+
op: Literal["==", "in"]
|
|
100
|
+
ref: Ref
|
|
101
|
+
literal: str | Slot
|
|
102
|
+
literal_first: bool = False # True for ``literal in ref``
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
def _literal(content: str) -> str | Slot:
|
|
106
|
+
"""A literal's value, or the slot it names. A reference mixed with other text is an error."""
|
|
107
|
+
if match := _SECRET_SLOT_RE.fullmatch(content):
|
|
108
|
+
return Slot(match.group(1), match.group(2), match.group(3))
|
|
109
|
+
if match := _PARAM_SLOT_RE.fullmatch(content):
|
|
110
|
+
namespace, name = match.group(1).split(".", 1)
|
|
111
|
+
return Slot(namespace, name)
|
|
112
|
+
if "${" in content or "{{" in content:
|
|
113
|
+
raise RuleSyntaxError(
|
|
114
|
+
f"'{content}' is not a valid reference literal: a reference must be the whole literal, one of "
|
|
115
|
+
"'${ customer_secrets.NAME }', '${ customer_secrets.NAME ?? default }', '${ secrets.NAME }', "
|
|
116
|
+
"'{{ params.NAME }}' or '{{ enrollment.code }}'"
|
|
117
|
+
)
|
|
118
|
+
if len(content.encode()) > MAX_LITERAL_LENGTH:
|
|
119
|
+
raise RuleSyntaxError(f"a literal is longer than {MAX_LITERAL_LENGTH} bytes")
|
|
120
|
+
return content
|
|
121
|
+
|
|
122
|
+
|
|
123
|
+
class _Parser:
|
|
124
|
+
def __init__(self, text: str) -> None:
|
|
125
|
+
self.text = text
|
|
126
|
+
self.pos = 0
|
|
127
|
+
|
|
128
|
+
def fail(self, message: str) -> RuleSyntaxError:
|
|
129
|
+
return RuleSyntaxError(f"{message} at position {self.pos} in {self.text!r}")
|
|
130
|
+
|
|
131
|
+
def peek(self) -> tuple[str, str] | None:
|
|
132
|
+
"""The next token as (kind, text) without consuming it; None at the end."""
|
|
133
|
+
match = _TOKEN_RE.match(self.text, self.pos)
|
|
134
|
+
if not match:
|
|
135
|
+
if self.text[self.pos :].strip(_WHITESPACE):
|
|
136
|
+
raise self.fail("unexpected character")
|
|
137
|
+
return None
|
|
138
|
+
kinds = ("op", "lbracket", "rbracket", "dot", "quote", "ident")
|
|
139
|
+
index = next(i for i, group in enumerate(match.groups()) if group is not None)
|
|
140
|
+
return kinds[index], match.group(index + 1)
|
|
141
|
+
|
|
142
|
+
def take(self) -> tuple[str, str] | None:
|
|
143
|
+
token = self.peek()
|
|
144
|
+
if token is not None:
|
|
145
|
+
match = _TOKEN_RE.match(self.text, self.pos)
|
|
146
|
+
assert match is not None
|
|
147
|
+
self.pos = match.end()
|
|
148
|
+
return token
|
|
149
|
+
|
|
150
|
+
def string(self) -> str:
|
|
151
|
+
"""Read a quoted string; the opening quote is the next token."""
|
|
152
|
+
token = self.take()
|
|
153
|
+
assert token is not None and token[0] == "quote"
|
|
154
|
+
quote, out = token[1], list[str]()
|
|
155
|
+
while self.pos < len(self.text):
|
|
156
|
+
char = self.text[self.pos]
|
|
157
|
+
self.pos += 1
|
|
158
|
+
if char == quote:
|
|
159
|
+
return "".join(out)
|
|
160
|
+
if char == "\\":
|
|
161
|
+
if self.pos >= len(self.text) or self.text[self.pos] not in "\\'\"":
|
|
162
|
+
raise self.fail("unsupported escape (only \\\\, \\' and \\\")")
|
|
163
|
+
char = self.text[self.pos]
|
|
164
|
+
self.pos += 1
|
|
165
|
+
out.append(char)
|
|
166
|
+
raise self.fail("unterminated string")
|
|
167
|
+
|
|
168
|
+
def ref(self) -> Ref:
|
|
169
|
+
token = self.take()
|
|
170
|
+
assert token is not None and token[0] == "ident"
|
|
171
|
+
root, keys = token[1], []
|
|
172
|
+
if root not in ROOTS:
|
|
173
|
+
raise self.fail(f"unknown root '{root}' (expected one of {', '.join(ROOTS)})")
|
|
174
|
+
while (token := self.peek()) is not None and token[0] in ("dot", "lbracket"):
|
|
175
|
+
self.take()
|
|
176
|
+
if token[0] == "dot":
|
|
177
|
+
ident = self.take()
|
|
178
|
+
if ident is None or ident[0] != "ident":
|
|
179
|
+
raise self.fail("expected a name after '.'")
|
|
180
|
+
keys.append(ident[1])
|
|
181
|
+
else:
|
|
182
|
+
if self.text[self.pos :].lstrip(_WHITESPACE)[:1] not in ("'", '"'):
|
|
183
|
+
raise self.fail("expected a quoted key inside [ ]")
|
|
184
|
+
keys.append(self.string())
|
|
185
|
+
if (self.take() or ("", ""))[0] != "rbracket":
|
|
186
|
+
raise self.fail("expected ']'")
|
|
187
|
+
if len(keys) > MAX_REF_DEPTH:
|
|
188
|
+
raise self.fail(f"a reference is deeper than {MAX_REF_DEPTH} keys")
|
|
189
|
+
if root == "method" and keys:
|
|
190
|
+
raise self.fail("'method' takes no keys")
|
|
191
|
+
if root in ("header", "query") and len(keys) != 1:
|
|
192
|
+
raise self.fail(f"'{root}' takes exactly one key, e.g. {root}['name']")
|
|
193
|
+
if root == "header":
|
|
194
|
+
keys = [keys[0].lower()]
|
|
195
|
+
return Ref(root, tuple(keys))
|
|
196
|
+
|
|
197
|
+
def operand(self) -> Ref | str | Slot:
|
|
198
|
+
token = self.peek()
|
|
199
|
+
if token is None:
|
|
200
|
+
raise self.fail("expected a request value or a quoted literal")
|
|
201
|
+
if token[0] == "quote":
|
|
202
|
+
return _literal(self.string())
|
|
203
|
+
if token[0] == "ident":
|
|
204
|
+
if token[1] == "in":
|
|
205
|
+
raise self.fail("expected a request value or a quoted literal")
|
|
206
|
+
return self.ref()
|
|
207
|
+
raise self.fail("expected a request value or a quoted literal")
|
|
208
|
+
|
|
209
|
+
def operator(self) -> Literal["==", "in"]:
|
|
210
|
+
token = self.take()
|
|
211
|
+
if token == ("op", "=="):
|
|
212
|
+
return "=="
|
|
213
|
+
if token == ("ident", "in"):
|
|
214
|
+
return "in"
|
|
215
|
+
raise self.fail("expected '==' or 'in'")
|
|
216
|
+
|
|
217
|
+
|
|
218
|
+
def parse_condition(text: str) -> Condition:
|
|
219
|
+
"""Parse and check one condition.
|
|
220
|
+
|
|
221
|
+
Raises:
|
|
222
|
+
RuleSyntaxError: anything outside the language, a secret slot under
|
|
223
|
+
``in``, or a condition longer than :data:`MAX_CONDITION_LENGTH` bytes.
|
|
224
|
+
"""
|
|
225
|
+
if not isinstance(text, str) or not text.strip(_WHITESPACE):
|
|
226
|
+
raise RuleSyntaxError("a condition must be a non-empty string")
|
|
227
|
+
if len(text.encode()) > MAX_CONDITION_LENGTH:
|
|
228
|
+
raise RuleSyntaxError(f"a condition is longer than {MAX_CONDITION_LENGTH} bytes (UTF-8)")
|
|
229
|
+
parser = _Parser(text)
|
|
230
|
+
left = parser.operand()
|
|
231
|
+
op = parser.operator()
|
|
232
|
+
right = parser.operand()
|
|
233
|
+
if parser.peek() is not None:
|
|
234
|
+
raise parser.fail("unexpected text after the condition")
|
|
235
|
+
|
|
236
|
+
if isinstance(left, Ref) and not isinstance(right, Ref):
|
|
237
|
+
condition = Condition(op, left, right)
|
|
238
|
+
elif not isinstance(left, Ref) and isinstance(right, Ref):
|
|
239
|
+
if op == "==":
|
|
240
|
+
raise RuleSyntaxError(f"write the request value first: '{text}' compares a literal == a request value")
|
|
241
|
+
condition = Condition(op, right, left, literal_first=True)
|
|
242
|
+
else:
|
|
243
|
+
raise RuleSyntaxError(f"'{text}' must compare one request value with one quoted literal")
|
|
244
|
+
|
|
245
|
+
if isinstance(condition.literal, Slot) and condition.literal.is_secret and op != "==":
|
|
246
|
+
raise RuleSyntaxError(
|
|
247
|
+
f"'{text}': a secret may only be compared with '==' (a substring test would reveal it "
|
|
248
|
+
"one character at a time)"
|
|
249
|
+
)
|
|
250
|
+
return condition
|
|
251
|
+
|
|
252
|
+
|
|
253
|
+
# ---------------------------------------------------------------------------
|
|
254
|
+
# Evaluation, for the conformance cases. The gateway is the real evaluator.
|
|
255
|
+
# ---------------------------------------------------------------------------
|
|
256
|
+
|
|
257
|
+
_MISSING = object()
|
|
258
|
+
|
|
259
|
+
|
|
260
|
+
def _request_value(ref: Ref, request: Mapping[str, Any]) -> Any:
|
|
261
|
+
if ref.root == "method":
|
|
262
|
+
return request.get("method", _MISSING)
|
|
263
|
+
if ref.root in ("header", "query"):
|
|
264
|
+
table = request.get("headers" if ref.root == "header" else "query") or {}
|
|
265
|
+
if ref.root == "header":
|
|
266
|
+
table = {str(name).lower(): value for name, value in table.items()}
|
|
267
|
+
return table.get(ref.keys[0], _MISSING)
|
|
268
|
+
value = request.get("body", _MISSING)
|
|
269
|
+
for key in ref.keys:
|
|
270
|
+
if not isinstance(value, dict) or key not in value:
|
|
271
|
+
return _MISSING
|
|
272
|
+
value = value[key]
|
|
273
|
+
return value
|
|
274
|
+
|
|
275
|
+
|
|
276
|
+
def _literal_value(literal: str | Slot, slots: Mapping[str, str]) -> Any:
|
|
277
|
+
if isinstance(literal, str):
|
|
278
|
+
return literal
|
|
279
|
+
value = slots.get(literal.key)
|
|
280
|
+
if value is None:
|
|
281
|
+
value = literal.default
|
|
282
|
+
return value if isinstance(value, str) and value != "" else _MISSING
|
|
283
|
+
|
|
284
|
+
|
|
285
|
+
def evaluate(condition: Condition, request: Mapping[str, Any], slots: Mapping[str, str] | None = None) -> bool:
|
|
286
|
+
"""Whether ``condition`` holds for ``request``.
|
|
287
|
+
|
|
288
|
+
``request`` has ``body`` (the decoded JSON body; absent when the body is
|
|
289
|
+
not JSON), ``headers``, ``query`` and ``method``. ``slots`` maps a slot's
|
|
290
|
+
:attr:`Slot.key` to its resolved value; an absent key uses the slot's
|
|
291
|
+
``?? default``.
|
|
292
|
+
"""
|
|
293
|
+
value = _request_value(condition.ref, request)
|
|
294
|
+
literal = _literal_value(condition.literal, slots or {})
|
|
295
|
+
if not isinstance(value, str) or literal is _MISSING:
|
|
296
|
+
return False
|
|
297
|
+
if condition.op == "==":
|
|
298
|
+
return hmac.compare_digest(value.encode(), literal.encode())
|
|
299
|
+
if condition.literal_first:
|
|
300
|
+
return literal != "" and literal in value
|
|
301
|
+
return value != "" and value in literal
|