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.
Files changed (58) hide show
  1. {unitysvc_core-0.3.6/src/unitysvc_core.egg-info → unitysvc_core-0.3.7}/PKG-INFO +18 -1
  2. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/README.md +17 -0
  3. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/pyproject.toml +2 -2
  4. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/models/__init__.py +4 -0
  5. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/models/channel.py +110 -0
  6. unitysvc_core-0.3.7/src/unitysvc_core/rules.py +301 -0
  7. unitysvc_core-0.3.7/src/unitysvc_core/rules_conformance.json +91 -0
  8. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/schema/offering_v1.json +127 -0
  9. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7/src/unitysvc_core.egg-info}/PKG-INFO +18 -1
  10. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core.egg-info/SOURCES.txt +3 -0
  11. unitysvc_core-0.3.7/tests/test_request_rules.py +220 -0
  12. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/tests/test_validate_service.py +31 -0
  13. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/LICENSE +0 -0
  14. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/setup.cfg +0 -0
  15. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/__init__.py +0 -0
  16. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/grants.py +0 -0
  17. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/models/base.py +0 -0
  18. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/models/documents.py +0 -0
  19. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/models/listing_data.py +0 -0
  20. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/models/listing_v1.py +0 -0
  21. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/models/offering_data.py +0 -0
  22. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/models/offering_v1.py +0 -0
  23. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/models/pricing.py +0 -0
  24. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/models/promotion_data.py +0 -0
  25. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/models/provider_data.py +0 -0
  26. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/models/provider_v1.py +0 -0
  27. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/models/service.py +0 -0
  28. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/models/service_group_data.py +0 -0
  29. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/models/validators.py +0 -0
  30. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/parameter_usage.py +0 -0
  31. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/py.typed +0 -0
  32. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/schema/base.json +0 -0
  33. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/schema/listing_v1.json +0 -0
  34. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/schema/promotion_v1.json +0 -0
  35. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/schema/provider_v1.json +0 -0
  36. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/schema/service_group_v1.json +0 -0
  37. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/utils.py +0 -0
  38. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core/validator.py +0 -0
  39. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core.egg-info/dependency_links.txt +0 -0
  40. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core.egg-info/requires.txt +0 -0
  41. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/src/unitysvc_core.egg-info/top_level.txt +0 -0
  42. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/tests/test_access_interface_routing.py +0 -0
  43. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/tests/test_canonical_interfaces.py +0 -0
  44. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/tests/test_channel.py +0 -0
  45. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/tests/test_effective_price.py +0 -0
  46. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/tests/test_external_apps.py +0 -0
  47. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/tests/test_grants.py +0 -0
  48. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/tests/test_hidden_path_skip.py +0 -0
  49. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/tests/test_listing_audience.py +0 -0
  50. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/tests/test_offering_data.py +0 -0
  51. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/tests/test_parameter_usage.py +0 -0
  52. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/tests/test_pricing.py +0 -0
  53. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/tests/test_provider_account_rate_limits.py +0 -0
  54. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/tests/test_service_group.py +0 -0
  55. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/tests/test_service_status.py +0 -0
  56. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/tests/test_utils.py +0 -0
  57. {unitysvc_core-0.3.6 → unitysvc_core-0.3.7}/tests/test_validator.py +0 -0
  58. {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.6
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.6"
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