unitysvc-core 0.3.5__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.5/src/unitysvc_core.egg-info → unitysvc_core-0.3.7}/PKG-INFO +19 -2
  2. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/README.md +18 -1
  3. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/pyproject.toml +2 -2
  4. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/src/unitysvc_core/grants.py +12 -4
  5. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/src/unitysvc_core/models/__init__.py +4 -0
  6. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/src/unitysvc_core/models/channel.py +110 -0
  7. unitysvc_core-0.3.7/src/unitysvc_core/rules.py +301 -0
  8. unitysvc_core-0.3.7/src/unitysvc_core/rules_conformance.json +91 -0
  9. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/src/unitysvc_core/schema/offering_v1.json +127 -0
  10. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7/src/unitysvc_core.egg-info}/PKG-INFO +19 -2
  11. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/src/unitysvc_core.egg-info/SOURCES.txt +3 -0
  12. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/tests/test_grants.py +25 -0
  13. unitysvc_core-0.3.7/tests/test_request_rules.py +220 -0
  14. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/tests/test_validate_service.py +31 -0
  15. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/LICENSE +0 -0
  16. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/setup.cfg +0 -0
  17. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/src/unitysvc_core/__init__.py +0 -0
  18. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/src/unitysvc_core/models/base.py +0 -0
  19. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/src/unitysvc_core/models/documents.py +0 -0
  20. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/src/unitysvc_core/models/listing_data.py +0 -0
  21. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/src/unitysvc_core/models/listing_v1.py +0 -0
  22. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/src/unitysvc_core/models/offering_data.py +0 -0
  23. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/src/unitysvc_core/models/offering_v1.py +0 -0
  24. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/src/unitysvc_core/models/pricing.py +0 -0
  25. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/src/unitysvc_core/models/promotion_data.py +0 -0
  26. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/src/unitysvc_core/models/provider_data.py +0 -0
  27. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/src/unitysvc_core/models/provider_v1.py +0 -0
  28. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/src/unitysvc_core/models/service.py +0 -0
  29. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/src/unitysvc_core/models/service_group_data.py +0 -0
  30. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/src/unitysvc_core/models/validators.py +0 -0
  31. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/src/unitysvc_core/parameter_usage.py +0 -0
  32. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/src/unitysvc_core/py.typed +0 -0
  33. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/src/unitysvc_core/schema/base.json +0 -0
  34. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/src/unitysvc_core/schema/listing_v1.json +0 -0
  35. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/src/unitysvc_core/schema/promotion_v1.json +0 -0
  36. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/src/unitysvc_core/schema/provider_v1.json +0 -0
  37. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/src/unitysvc_core/schema/service_group_v1.json +0 -0
  38. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/src/unitysvc_core/utils.py +0 -0
  39. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/src/unitysvc_core/validator.py +0 -0
  40. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/src/unitysvc_core.egg-info/dependency_links.txt +0 -0
  41. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/src/unitysvc_core.egg-info/requires.txt +0 -0
  42. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/src/unitysvc_core.egg-info/top_level.txt +0 -0
  43. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/tests/test_access_interface_routing.py +0 -0
  44. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/tests/test_canonical_interfaces.py +0 -0
  45. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/tests/test_channel.py +0 -0
  46. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/tests/test_effective_price.py +0 -0
  47. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/tests/test_external_apps.py +0 -0
  48. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/tests/test_hidden_path_skip.py +0 -0
  49. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/tests/test_listing_audience.py +0 -0
  50. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/tests/test_offering_data.py +0 -0
  51. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/tests/test_parameter_usage.py +0 -0
  52. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/tests/test_pricing.py +0 -0
  53. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/tests/test_provider_account_rate_limits.py +0 -0
  54. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/tests/test_service_group.py +0 -0
  55. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/tests/test_service_status.py +0 -0
  56. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/tests/test_utils.py +0 -0
  57. {unitysvc_core-0.3.5 → unitysvc_core-0.3.7}/tests/test_validator.py +0 -0
  58. {unitysvc_core-0.3.5 → 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.5
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>
@@ -214,7 +214,7 @@ Three stages (unitysvc/unitysvc#2720): a target service's **`exports`** (what it
214
214
  - **A request's `options` are fixed.** Every option it declares is in the policy of an approved request, with the declared value; the customer may repeat it but not change or drop it. An option the request does not declare is the customer's to set at enrollment (a form rendered from the target's `options` schema). So `{"object": "service:ai", ...}` lets the customer pick the AI service, and `"options": "service=labs/llm-balanced"` pins it.
215
215
  - Several requests may name one object (two kinds of room) only if each fixes some option to a different value (`kind=chat`, `kind=feed`), so an approval says which one it is.
216
216
  - `limits` (`validate_limits`): `count_per_hour` / `count_per_day` / `count_per_month` / `count_total` (positive integer) and the same for `amount_` (finite positive decimal, as a number or a string). Limits are universal: the platform meters every call, so any service can be limited without exporting anything. The seller's limits only pre-fill the form; the customer sets them at enrollment, and an enrollment's own limits (unitysvc/unitysvc#2687) use the same shape. They are counted per policy entry (the enrollment's calls to that service) from the usage stream (counters keyed by scope, metric and window bucket), and the gateway refuses calls once one is exceeded.
217
- - **A room the platform provisions** (unitysvc/unitysvc#2830) is asked for with `resource:room`: `{"object": "resource:room", "permissions": ["create"], "required": true, "justification": "Creates your chat room", "options": "kind=chat&max_members=100"}`. Core knows the resource, so no catalog is consulted. The request must fix `kind`, the room's identity; each kind bounds the permissions (`chat`: `create`, a room the customer owns; `support`: `join`, `read`, `post`, the seller's private room with the customer; `announcement`: `join`, `read`; `discussion`: `join`, `read`, `post`). `max_members` (a positive integer) caps only a room the customer creates. A channel requests each kind at most once, and a resource takes no limits.
217
+ - **A room the platform provisions** (unitysvc/unitysvc#2830) is asked for with `resource:room`: `{"object": "resource:room", "permissions": ["create"], "required": true, "justification": "Creates your chat room", "options": "kind=chat&max_members=100"}`. Core knows the resource, so no catalog is consulted. The request must fix `kind`, the room's identity; each kind bounds the permissions (`chat`: `create`, a room the customer owns; `support`: `join`, `read`, `post`, the seller's private room with the customer; `announcement`: `join`, `read`; `discussion`: `join`, `read`, `post`). `max_members` (a positive integer) caps only a room the customer creates; `max_retention` (seconds, 0 or more) caps how long any provisioned room keeps messages, within the platform's own ceiling for the kind, and the room's owner may keep less. A channel requests each kind at most once, and a resource takes no limits.
218
218
  - **A longer-lived leased key** is asked for with one `apikey` entry: `{"object": "apikey", "required": false, "limits": {"api_key_lifespan": 14400}, "justification": "Batch runs take up to four hours"}`. It names the key itself, so it takes only `limits` (exactly `api_key_lifespan`, whole seconds from 1 to 86400), `required` and a `justification`, needs no catalog lookup, and grants nothing. Without it, a key the seller leases for the enrollment lives `DEFAULT_API_KEY_LIFESPAN` (3600 s). `api_key_lifespan` is valid only on this entry.
219
219
 
220
220
  **3. How options reach the service.** Not through the upstream URL: the gateway never changes a target's `base_url` or query to carry policy. How an option is applied is up to the service's implementation:
@@ -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:
@@ -179,7 +179,7 @@ Three stages (unitysvc/unitysvc#2720): a target service's **`exports`** (what it
179
179
  - **A request's `options` are fixed.** Every option it declares is in the policy of an approved request, with the declared value; the customer may repeat it but not change or drop it. An option the request does not declare is the customer's to set at enrollment (a form rendered from the target's `options` schema). So `{"object": "service:ai", ...}` lets the customer pick the AI service, and `"options": "service=labs/llm-balanced"` pins it.
180
180
  - Several requests may name one object (two kinds of room) only if each fixes some option to a different value (`kind=chat`, `kind=feed`), so an approval says which one it is.
181
181
  - `limits` (`validate_limits`): `count_per_hour` / `count_per_day` / `count_per_month` / `count_total` (positive integer) and the same for `amount_` (finite positive decimal, as a number or a string). Limits are universal: the platform meters every call, so any service can be limited without exporting anything. The seller's limits only pre-fill the form; the customer sets them at enrollment, and an enrollment's own limits (unitysvc/unitysvc#2687) use the same shape. They are counted per policy entry (the enrollment's calls to that service) from the usage stream (counters keyed by scope, metric and window bucket), and the gateway refuses calls once one is exceeded.
182
- - **A room the platform provisions** (unitysvc/unitysvc#2830) is asked for with `resource:room`: `{"object": "resource:room", "permissions": ["create"], "required": true, "justification": "Creates your chat room", "options": "kind=chat&max_members=100"}`. Core knows the resource, so no catalog is consulted. The request must fix `kind`, the room's identity; each kind bounds the permissions (`chat`: `create`, a room the customer owns; `support`: `join`, `read`, `post`, the seller's private room with the customer; `announcement`: `join`, `read`; `discussion`: `join`, `read`, `post`). `max_members` (a positive integer) caps only a room the customer creates. A channel requests each kind at most once, and a resource takes no limits.
182
+ - **A room the platform provisions** (unitysvc/unitysvc#2830) is asked for with `resource:room`: `{"object": "resource:room", "permissions": ["create"], "required": true, "justification": "Creates your chat room", "options": "kind=chat&max_members=100"}`. Core knows the resource, so no catalog is consulted. The request must fix `kind`, the room's identity; each kind bounds the permissions (`chat`: `create`, a room the customer owns; `support`: `join`, `read`, `post`, the seller's private room with the customer; `announcement`: `join`, `read`; `discussion`: `join`, `read`, `post`). `max_members` (a positive integer) caps only a room the customer creates; `max_retention` (seconds, 0 or more) caps how long any provisioned room keeps messages, within the platform's own ceiling for the kind, and the room's owner may keep less. A channel requests each kind at most once, and a resource takes no limits.
183
183
  - **A longer-lived leased key** is asked for with one `apikey` entry: `{"object": "apikey", "required": false, "limits": {"api_key_lifespan": 14400}, "justification": "Batch runs take up to four hours"}`. It names the key itself, so it takes only `limits` (exactly `api_key_lifespan`, whole seconds from 1 to 86400), `required` and a `justification`, needs no catalog lookup, and grants nothing. Without it, a key the seller leases for the enrollment lives `DEFAULT_API_KEY_LIFESPAN` (3600 s). `api_key_lifespan` is valid only on this entry.
184
184
 
185
185
  **3. How options reach the service.** Not through the upstream URL: the gateway never changes a target's `base_url` or query to carry policy. How an option is applied is up to the service's implementation:
@@ -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.5"
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"]
@@ -81,7 +81,9 @@ customer consent and key issuance establish its *authority*.
81
81
  A request's ``object`` is ``service:<name>``; or ``resource:room``, a room the
82
82
  platform provisions for the enrollment (unitysvc/unitysvc#2830), whose
83
83
  ``kind`` (``chat``, ``support``, ``announcement``, ``discussion``) the
84
- request fixes and whose permissions the kind bounds (:data:`ROOM_KINDS`); or
84
+ request fixes and whose permissions the kind bounds (:data:`ROOM_KINDS`),
85
+ with optional caps on its members (``max_members``) and on how long it keeps
86
+ messages (``max_retention``, seconds); or
85
87
  ``apikey``: how long a key leased for the enrollment lives
86
88
  (``limits.api_key_lifespan``, up to a day, with a justification), which grants
87
89
  nothing. :func:`build_policy` turns a customer's approvals into the policy an
@@ -199,6 +201,10 @@ ROOM_KINDS: dict[str, frozenset[str]] = {
199
201
  }
200
202
  ROOM_KIND = "kind"
201
203
  ROOM_MAX_MEMBERS = "max_members"
204
+ # The longest the provisioned room keeps messages, in seconds (0: never
205
+ # stored); the platform's own ceiling for the kind still applies, and the
206
+ # room's owner may keep less (unitysvc/unitysvc#2907).
207
+ ROOM_MAX_RETENTION = "max_retention"
202
208
  RESOURCES: dict[str, Exports] = {
203
209
  "room": Exports(
204
210
  {name: () for name in ("create", "join", "read", "post")},
@@ -208,6 +214,7 @@ RESOURCES: dict[str, Exports] = {
208
214
  "properties": {
209
215
  ROOM_KIND: {"type": "string", "enum": list(ROOM_KINDS)},
210
216
  ROOM_MAX_MEMBERS: {"type": "integer", "minimum": 1},
217
+ ROOM_MAX_RETENTION: {"type": "integer", "minimum": 0},
211
218
  },
212
219
  },
213
220
  ),
@@ -617,9 +624,10 @@ def check_resource(where: str, obj: str, permissions: list[str], options: dict[s
617
624
  not allow, for a request and for a policy entry alike.
618
625
 
619
626
  A room claim names its ``kind`` in its options; its permissions are some
620
- of those the kind allows, and ``max_members`` (a positive integer) only
621
- caps a room the customer creates. A resource is provisioned, not called,
622
- so it takes no limits.
627
+ of those the kind allows, ``max_members`` (a positive integer) only caps
628
+ a room the customer creates, and ``max_retention`` (seconds, 0 or more)
629
+ caps how long any provisioned room keeps messages. A resource is
630
+ provisioned, not called, so it takes no limits.
623
631
  """
624
632
  check_claim(where, obj, permissions, options, RESOURCES[obj.removeprefix(RESOURCE_PREFIX)])
625
633
  if limits:
@@ -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