unitysvc-core 0.3.12__tar.gz → 0.3.14__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 (64) hide show
  1. {unitysvc_core-0.3.12/src/unitysvc_core.egg-info → unitysvc_core-0.3.14}/PKG-INFO +11 -13
  2. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/README.md +10 -12
  3. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/pyproject.toml +1 -1
  4. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/src/unitysvc_core/instance_spec.py +39 -35
  5. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/src/unitysvc_core/models/channel.py +30 -14
  6. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/src/unitysvc_core/models/documents.py +5 -3
  7. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/src/unitysvc_core/schema/offering_v1.json +20 -1
  8. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/src/unitysvc_core/validator.py +1 -3
  9. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14/src/unitysvc_core.egg-info}/PKG-INFO +11 -13
  10. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/tests/test_container.py +57 -52
  11. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/LICENSE +0 -0
  12. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/setup.cfg +0 -0
  13. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/src/unitysvc_core/__init__.py +0 -0
  14. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/src/unitysvc_core/grants.py +0 -0
  15. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/src/unitysvc_core/models/__init__.py +0 -0
  16. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/src/unitysvc_core/models/base.py +0 -0
  17. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/src/unitysvc_core/models/container.py +0 -0
  18. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/src/unitysvc_core/models/listing_data.py +0 -0
  19. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/src/unitysvc_core/models/listing_v1.py +0 -0
  20. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/src/unitysvc_core/models/manifest.py +0 -0
  21. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/src/unitysvc_core/models/offering_data.py +0 -0
  22. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/src/unitysvc_core/models/offering_v1.py +0 -0
  23. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/src/unitysvc_core/models/pricing.py +0 -0
  24. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/src/unitysvc_core/models/probes.py +0 -0
  25. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/src/unitysvc_core/models/promotion_data.py +0 -0
  26. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/src/unitysvc_core/models/provider_data.py +0 -0
  27. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/src/unitysvc_core/models/provider_v1.py +0 -0
  28. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/src/unitysvc_core/models/service.py +0 -0
  29. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/src/unitysvc_core/models/service_group_data.py +0 -0
  30. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/src/unitysvc_core/models/validators.py +0 -0
  31. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/src/unitysvc_core/parameter_usage.py +0 -0
  32. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/src/unitysvc_core/py.typed +0 -0
  33. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/src/unitysvc_core/schema/base.json +0 -0
  34. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/src/unitysvc_core/schema/listing_v1.json +0 -0
  35. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/src/unitysvc_core/schema/normalized_manifest_v1.json +0 -0
  36. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/src/unitysvc_core/schema/probes_v1.json +0 -0
  37. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/src/unitysvc_core/schema/promotion_v1.json +0 -0
  38. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/src/unitysvc_core/schema/provider_v1.json +0 -0
  39. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/src/unitysvc_core/schema/service_group_v1.json +0 -0
  40. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/src/unitysvc_core/utils.py +0 -0
  41. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/src/unitysvc_core.egg-info/SOURCES.txt +0 -0
  42. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/src/unitysvc_core.egg-info/dependency_links.txt +0 -0
  43. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/src/unitysvc_core.egg-info/requires.txt +0 -0
  44. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/src/unitysvc_core.egg-info/top_level.txt +0 -0
  45. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/tests/test_access_interface_routing.py +0 -0
  46. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/tests/test_canonical_interfaces.py +0 -0
  47. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/tests/test_channel.py +0 -0
  48. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/tests/test_documents.py +0 -0
  49. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/tests/test_effective_price.py +0 -0
  50. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/tests/test_external_apps.py +0 -0
  51. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/tests/test_grants.py +0 -0
  52. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/tests/test_hidden_path_skip.py +0 -0
  53. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/tests/test_listing_audience.py +0 -0
  54. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/tests/test_offering_data.py +0 -0
  55. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/tests/test_parameter_usage.py +0 -0
  56. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/tests/test_pricing.py +0 -0
  57. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/tests/test_provider_account_rate_limits.py +0 -0
  58. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/tests/test_request_rules.py +0 -0
  59. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/tests/test_service_group.py +0 -0
  60. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/tests/test_service_status.py +0 -0
  61. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/tests/test_utils.py +0 -0
  62. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/tests/test_validate_service.py +0 -0
  63. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/tests/test_validator.py +0 -0
  64. {unitysvc_core-0.3.12 → unitysvc_core-0.3.14}/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.12
3
+ Version: 0.3.14
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>
@@ -290,18 +290,14 @@ A `container` channel is one tier of a service that runs as instances on Kuberne
290
290
  "base": {
291
291
  "access_method": "container",
292
292
  "resources": {"limits": {"cpu": "250m", "memory": "256Mi", "ephemeral-storage": "1Gi"}},
293
- "entries": [{"name": "web", "service": "web", "port": 5678, "auth": "key"}],
294
- "customer_access_requests": [
295
- {"object": "resource:container", "permissions": ["create"], "required": true,
296
- "justification": "Run a disposable application instance for this enrollment"}
297
- ]
293
+ "entries": [{"name": "web", "service": "web", "port": 5678, "auth": "key"}]
298
294
  }
299
295
  }
300
296
  ```
301
297
 
302
298
  - There is no per-channel spec: every container channel of the offering runs the offering's one instance spec (below), so tiers differ in `resources`, not in stack. The earlier `spec` field (a Document title) is removed in 0.3.11; a channel carrying it is refused as an unknown field.
303
299
  - `resources` is the tier total, in Kubernetes' shape: `limits`, optionally `requests`, each a map from a resource name to a quantity (`250m`, `1Gi`, `1e3`, parsed as Kubernetes parses them). The names are `cpu`, `memory`, `ephemeral-storage` and `nvidia.com/gpu`; the first three limits are required; a request is at most its limit; a GPU is a whole number with a request equal to the limit. `resources.services` is an optional per-service split (`{"web": {"limits": {...}}}`) whose sums must stay within the tier (each share names `cpu`, `memory` and `ephemeral-storage`, and a resource without a request counts at its limit, as the agent resolves it); a spec with several services needs one. Quantities are at most 64 characters with an exponent of at most 30. A Compose `deploy.resources` is ignored: the channel is authoritative.
304
- - The channel is always enrollable and must request `resource:container` with `create`, marked `required` (`grants.RESOURCES` knows the resource; it has no options and no limits).
300
+ - The channel is always enrollable and needs no `customer_access_requests`: the customer runs their own instance, which grants the seller nothing (a request is for the seller to call the customer's services). A channel that does declare one is `me_bound` instead of `enrollable`.
305
301
  - `servers` is optional and has no container-specific meaning: each is an ordinary `HttpServer` the gateway reaches, for example `{"base_url": "https://{{ enrollment.code }}.unitysvc.app/"}`. A container-only service sets no `servers`. An enrollable channel is reached at `/e/<CODE>` on the API gateway, which the platform provides; a listing never declares it (see Canonical user access interfaces).
306
302
  - `entries` (`name`, `service`, `port`, optional `path`, `auth` of `login`, `key` or `app`) is **provisional** (open question 1 of #105: whether instances need URLs beyond `servers`, and which `auth` values apply; `gateway` is deliberately not accepted).
307
303
  - `params` and `customer_access_requests` are as on the other channels.
@@ -329,20 +325,22 @@ The seller tooling expands the shortcut before upload with `expand_instance_spec
329
325
  | --- | --- |
330
326
  | Honor | `image` (a tag, or a literal digest `name:tag@sha256:...`; a tag-only image warns), `command`, `entrypoint`, `environment`, `ports` (container side only), `healthcheck`, `working_dir`, `user`, `read_only` |
331
327
  | Ignore, warn | `container_name`, `restart`, `labels`, `logging`, `networks`, the host side of `ports`, `expose`, `profiles`, `links`, `x-*`, `deploy.resources`, top-level `name`, `version`, `networks` |
332
- | Ignore, warn loudly | `depends_on` (no start ordering: the app must retry; readiness keeps traffic away), `env_file` (the values it would supply are missing: provide them with `meta.environment`), named volumes (scratch space: data survives a container restart, not a replacement of the instance) |
328
+ | Ignore, warn loudly | `depends_on` (no start ordering: the app must retry; readiness keeps traffic away), `env_file` (the values it would supply are missing: provide them with the channel's `environment`), named volumes (scratch space: data survives a container restart, not a replacement of the instance) |
333
329
  | Reject | `build`, `privileged`, `cap_add`, `devices`, `network_mode`, `pid`, `ipc`, `security_opt`, `sysctls`, bind mounts and host paths, `volumes_from`, a named volume shared by two services, `runtime`, `extra_hosts`, `secrets`, `configs`, `extends`, `include`, an `image` with a malformed digest, two services that share no network, any other key |
334
330
 
335
331
  A seller can keep one file for local Docker and the platform and leave `deploy.resources` in place. **Images.** A tag-only or untagged `image` (`:latest`, `:1.4`, none) is accepted with a note (`unpinned_image`, a warning): the platform runs it as written and reports the digest it pulled, and a moving tag can change at a restart; a re-upload does not update running instances. A digest the seller writes (`name:tag@sha256:...`) is honored as written; one that is malformed is an error (`bad_digest`). Core never contacts a registry. Sibling services reach each other by name (`redis:6379`); service names must be DNS labels. `${VAR}` in an `environment` value is kept as written with a warning (how a secret or parameter binds to it is open question 4 of #105); in `image` and `ports` a variable is an error.
336
332
 
337
- **Reusing a generic Compose file.** A seller can keep one generic file (in their repo) and vary it for UnitySVC in the Document's `meta`: `meta.environment` is `{service: {NAME: "value"}}`; each service must exist in the file and each value is a string with a valid variable name. It overrides the file's own `environment` on a name conflict, and it is applied only at compile time (`compile_instance_spec(text, resources, environment=...)`), so the stored Compose bytes stay an exact copy of the seller's file and the seller's local test and the backend merge identically. `validate_instance_spec(..., environment=...)` checks it against the file (`overlay_service`). Values are plaintext in the spec; only `${UNITYSVC_INSTANCE_API_KEY}` is bound per instance (any other `${...}` only warns, open question 4 of #105). Only `environment` is supported, not a general override. `meta.sha256` is recommended with a URL, so an upstream change that breaks the overlay fails the upload.
333
+ **Reusing a generic Compose file, and the environment.** A seller keeps one generic, plain Compose file (it runs as it is with Docker) and sets the instance's environment on each container channel: `environment` is `{service: {NAME: "value"}}`; each service must exist in the file and each name is a valid variable name. A value may be, or contain, `{{ params.NAME }}`: that channel's own enrollment parameter, which the platform binds when the instance starts (any other `{{` is refused, and `{{ params` in the Compose file is a `bad_template` error). The channel's value overrides the file's own `environment` on a name conflict. It is applied only at compile time (`compile_instance_spec(text, resources, environment=...)`), so the stored Compose bytes stay an exact copy of the seller's file; `validate_instance_spec(text, channel=...)` checks the channel's environment against the file (`overlay_service`). There is no platform-issued instance key: a secret is an ordinary enrollment parameter. A Document's `meta.environment` is no longer supported. `meta.sha256` is recommended with a URL, so an upstream change that breaks the environment fails the upload.
338
334
 
339
335
  ```json
340
336
  "documents": {"Instance spec": {
341
337
  "category": "instance_spec", "mime_type": "text",
342
338
  "external_url": "https://raw.githubusercontent.com/Kadxy/weixin-ilink-gateway/<commit-sha>/docker-compose.yaml",
343
- "meta": {"format": "compose", "sha256": "<64 hex>",
344
- "environment": {"gateway": {"API_KEY": "${UNITYSVC_INSTANCE_API_KEY}"}}}
345
- }}
339
+ "meta": {"format": "compose", "sha256": "<64 hex>"}
340
+ }},
341
+ "upstream_access_config": {"base": {"access_method": "container",
342
+ "params": {"schema": {"properties": {"WEIXIN_API_KEY": {"type": "string", "default": "{{ token_urlsafe(32) }}"}}, "required": ["WEIXIN_API_KEY"]}},
343
+ "environment": {"gateway": {"API_KEY": "{{ params.WEIXIN_API_KEY }}"}}}}
346
344
  ```
347
345
 
348
346
  **Validating.** `validate_instance_spec(text, format="compose", channel=ContainerChannel | None)` returns an `InstanceSpecReport` of `errors` and `warnings`, each an `InstanceSpecIssue(code, path, message, loud)`; with the channel it also checks that every entry targets a declared service and port and that `resources.services` names the spec's services. It never raises on bad input. The seller CLI and backend ingest call it, directly or through `DataValidator`: `validate_service` / `validate_data_file` report the errors of every container channel's spec under `upstream_access_config.<channel>.instance_spec`, and `DataValidator.service_warnings(offering, service_dir)` returns the warnings (`issue.loud` for the ones a seller must not miss) for `specs validate` to print after the errors.
@@ -357,7 +355,7 @@ A seller can keep one file for local Docker and the platform and leave `deploy.r
357
355
 
358
356
  Each `entry` must name an entry of the offering's container channels. A script (any other file) is run as before. Core publishes the schema and fixtures (`tests/fixtures/probes`); the runners live in unitysvc-sellers and unitysvc-compute-k8s. The derived test is only as strict as `health`.
359
357
 
360
- Examples: `tests/example_data/hashicorp/services/echo` (one service, two tiers); `tests/example_data/kadxy/services/weixin-ilink-gateway` (secrets, scratch state, outbound traffic; its image digest is a marked placeholder); and `tests/example_data/kadxy/services/weixin-ilink-gateway-upstream` (the project's own Compose file by URL at a pinned commit with `meta.sha256`, plus a `meta.environment` overlay; `upstream-compose.yaml` is a byte-for-byte copy of that file, and `meta.sha256` is its hash, as core fetches nothing).
358
+ Examples: `tests/example_data/hashicorp/services/echo` (one service, two tiers); `tests/example_data/kadxy/services/weixin-ilink-gateway` (secrets, scratch state, outbound traffic; its image digest is a marked placeholder); and `tests/example_data/kadxy/services/weixin-ilink-gateway-upstream` (the project's own Compose file by URL at a pinned commit with `meta.sha256`, plus a channel `environment`; `upstream-compose.yaml` is a byte-for-byte copy of that file, and `meta.sha256` is its hash, as core fetches nothing).
361
359
 
362
360
  ### Request rules
363
361
 
@@ -254,18 +254,14 @@ A `container` channel is one tier of a service that runs as instances on Kuberne
254
254
  "base": {
255
255
  "access_method": "container",
256
256
  "resources": {"limits": {"cpu": "250m", "memory": "256Mi", "ephemeral-storage": "1Gi"}},
257
- "entries": [{"name": "web", "service": "web", "port": 5678, "auth": "key"}],
258
- "customer_access_requests": [
259
- {"object": "resource:container", "permissions": ["create"], "required": true,
260
- "justification": "Run a disposable application instance for this enrollment"}
261
- ]
257
+ "entries": [{"name": "web", "service": "web", "port": 5678, "auth": "key"}]
262
258
  }
263
259
  }
264
260
  ```
265
261
 
266
262
  - There is no per-channel spec: every container channel of the offering runs the offering's one instance spec (below), so tiers differ in `resources`, not in stack. The earlier `spec` field (a Document title) is removed in 0.3.11; a channel carrying it is refused as an unknown field.
267
263
  - `resources` is the tier total, in Kubernetes' shape: `limits`, optionally `requests`, each a map from a resource name to a quantity (`250m`, `1Gi`, `1e3`, parsed as Kubernetes parses them). The names are `cpu`, `memory`, `ephemeral-storage` and `nvidia.com/gpu`; the first three limits are required; a request is at most its limit; a GPU is a whole number with a request equal to the limit. `resources.services` is an optional per-service split (`{"web": {"limits": {...}}}`) whose sums must stay within the tier (each share names `cpu`, `memory` and `ephemeral-storage`, and a resource without a request counts at its limit, as the agent resolves it); a spec with several services needs one. Quantities are at most 64 characters with an exponent of at most 30. A Compose `deploy.resources` is ignored: the channel is authoritative.
268
- - The channel is always enrollable and must request `resource:container` with `create`, marked `required` (`grants.RESOURCES` knows the resource; it has no options and no limits).
264
+ - The channel is always enrollable and needs no `customer_access_requests`: the customer runs their own instance, which grants the seller nothing (a request is for the seller to call the customer's services). A channel that does declare one is `me_bound` instead of `enrollable`.
269
265
  - `servers` is optional and has no container-specific meaning: each is an ordinary `HttpServer` the gateway reaches, for example `{"base_url": "https://{{ enrollment.code }}.unitysvc.app/"}`. A container-only service sets no `servers`. An enrollable channel is reached at `/e/<CODE>` on the API gateway, which the platform provides; a listing never declares it (see Canonical user access interfaces).
270
266
  - `entries` (`name`, `service`, `port`, optional `path`, `auth` of `login`, `key` or `app`) is **provisional** (open question 1 of #105: whether instances need URLs beyond `servers`, and which `auth` values apply; `gateway` is deliberately not accepted).
271
267
  - `params` and `customer_access_requests` are as on the other channels.
@@ -293,20 +289,22 @@ The seller tooling expands the shortcut before upload with `expand_instance_spec
293
289
  | --- | --- |
294
290
  | Honor | `image` (a tag, or a literal digest `name:tag@sha256:...`; a tag-only image warns), `command`, `entrypoint`, `environment`, `ports` (container side only), `healthcheck`, `working_dir`, `user`, `read_only` |
295
291
  | Ignore, warn | `container_name`, `restart`, `labels`, `logging`, `networks`, the host side of `ports`, `expose`, `profiles`, `links`, `x-*`, `deploy.resources`, top-level `name`, `version`, `networks` |
296
- | Ignore, warn loudly | `depends_on` (no start ordering: the app must retry; readiness keeps traffic away), `env_file` (the values it would supply are missing: provide them with `meta.environment`), named volumes (scratch space: data survives a container restart, not a replacement of the instance) |
292
+ | Ignore, warn loudly | `depends_on` (no start ordering: the app must retry; readiness keeps traffic away), `env_file` (the values it would supply are missing: provide them with the channel's `environment`), named volumes (scratch space: data survives a container restart, not a replacement of the instance) |
297
293
  | Reject | `build`, `privileged`, `cap_add`, `devices`, `network_mode`, `pid`, `ipc`, `security_opt`, `sysctls`, bind mounts and host paths, `volumes_from`, a named volume shared by two services, `runtime`, `extra_hosts`, `secrets`, `configs`, `extends`, `include`, an `image` with a malformed digest, two services that share no network, any other key |
298
294
 
299
295
  A seller can keep one file for local Docker and the platform and leave `deploy.resources` in place. **Images.** A tag-only or untagged `image` (`:latest`, `:1.4`, none) is accepted with a note (`unpinned_image`, a warning): the platform runs it as written and reports the digest it pulled, and a moving tag can change at a restart; a re-upload does not update running instances. A digest the seller writes (`name:tag@sha256:...`) is honored as written; one that is malformed is an error (`bad_digest`). Core never contacts a registry. Sibling services reach each other by name (`redis:6379`); service names must be DNS labels. `${VAR}` in an `environment` value is kept as written with a warning (how a secret or parameter binds to it is open question 4 of #105); in `image` and `ports` a variable is an error.
300
296
 
301
- **Reusing a generic Compose file.** A seller can keep one generic file (in their repo) and vary it for UnitySVC in the Document's `meta`: `meta.environment` is `{service: {NAME: "value"}}`; each service must exist in the file and each value is a string with a valid variable name. It overrides the file's own `environment` on a name conflict, and it is applied only at compile time (`compile_instance_spec(text, resources, environment=...)`), so the stored Compose bytes stay an exact copy of the seller's file and the seller's local test and the backend merge identically. `validate_instance_spec(..., environment=...)` checks it against the file (`overlay_service`). Values are plaintext in the spec; only `${UNITYSVC_INSTANCE_API_KEY}` is bound per instance (any other `${...}` only warns, open question 4 of #105). Only `environment` is supported, not a general override. `meta.sha256` is recommended with a URL, so an upstream change that breaks the overlay fails the upload.
297
+ **Reusing a generic Compose file, and the environment.** A seller keeps one generic, plain Compose file (it runs as it is with Docker) and sets the instance's environment on each container channel: `environment` is `{service: {NAME: "value"}}`; each service must exist in the file and each name is a valid variable name. A value may be, or contain, `{{ params.NAME }}`: that channel's own enrollment parameter, which the platform binds when the instance starts (any other `{{` is refused, and `{{ params` in the Compose file is a `bad_template` error). The channel's value overrides the file's own `environment` on a name conflict. It is applied only at compile time (`compile_instance_spec(text, resources, environment=...)`), so the stored Compose bytes stay an exact copy of the seller's file; `validate_instance_spec(text, channel=...)` checks the channel's environment against the file (`overlay_service`). There is no platform-issued instance key: a secret is an ordinary enrollment parameter. A Document's `meta.environment` is no longer supported. `meta.sha256` is recommended with a URL, so an upstream change that breaks the environment fails the upload.
302
298
 
303
299
  ```json
304
300
  "documents": {"Instance spec": {
305
301
  "category": "instance_spec", "mime_type": "text",
306
302
  "external_url": "https://raw.githubusercontent.com/Kadxy/weixin-ilink-gateway/<commit-sha>/docker-compose.yaml",
307
- "meta": {"format": "compose", "sha256": "<64 hex>",
308
- "environment": {"gateway": {"API_KEY": "${UNITYSVC_INSTANCE_API_KEY}"}}}
309
- }}
303
+ "meta": {"format": "compose", "sha256": "<64 hex>"}
304
+ }},
305
+ "upstream_access_config": {"base": {"access_method": "container",
306
+ "params": {"schema": {"properties": {"WEIXIN_API_KEY": {"type": "string", "default": "{{ token_urlsafe(32) }}"}}, "required": ["WEIXIN_API_KEY"]}},
307
+ "environment": {"gateway": {"API_KEY": "{{ params.WEIXIN_API_KEY }}"}}}}
310
308
  ```
311
309
 
312
310
  **Validating.** `validate_instance_spec(text, format="compose", channel=ContainerChannel | None)` returns an `InstanceSpecReport` of `errors` and `warnings`, each an `InstanceSpecIssue(code, path, message, loud)`; with the channel it also checks that every entry targets a declared service and port and that `resources.services` names the spec's services. It never raises on bad input. The seller CLI and backend ingest call it, directly or through `DataValidator`: `validate_service` / `validate_data_file` report the errors of every container channel's spec under `upstream_access_config.<channel>.instance_spec`, and `DataValidator.service_warnings(offering, service_dir)` returns the warnings (`issue.loud` for the ones a seller must not miss) for `specs validate` to print after the errors.
@@ -321,7 +319,7 @@ A seller can keep one file for local Docker and the platform and leave `deploy.r
321
319
 
322
320
  Each `entry` must name an entry of the offering's container channels. A script (any other file) is run as before. Core publishes the schema and fixtures (`tests/fixtures/probes`); the runners live in unitysvc-sellers and unitysvc-compute-k8s. The derived test is only as strict as `health`.
323
321
 
324
- Examples: `tests/example_data/hashicorp/services/echo` (one service, two tiers); `tests/example_data/kadxy/services/weixin-ilink-gateway` (secrets, scratch state, outbound traffic; its image digest is a marked placeholder); and `tests/example_data/kadxy/services/weixin-ilink-gateway-upstream` (the project's own Compose file by URL at a pinned commit with `meta.sha256`, plus a `meta.environment` overlay; `upstream-compose.yaml` is a byte-for-byte copy of that file, and `meta.sha256` is its hash, as core fetches nothing).
322
+ Examples: `tests/example_data/hashicorp/services/echo` (one service, two tiers); `tests/example_data/kadxy/services/weixin-ilink-gateway` (secrets, scratch state, outbound traffic; its image digest is a marked placeholder); and `tests/example_data/kadxy/services/weixin-ilink-gateway-upstream` (the project's own Compose file by URL at a pinned commit with `meta.sha256`, plus a channel `environment`; `upstream-compose.yaml` is a byte-for-byte copy of that file, and `meta.sha256` is its hash, as core fetches nothing).
325
323
 
326
324
  ### Request rules
327
325
 
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "unitysvc-core"
7
- version = "0.3.12"
7
+ version = "0.3.14"
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" }]
@@ -95,6 +95,9 @@ _HEALTHCHECK_KEYS = frozenset({"test", "interval", "timeout", "retries", "start_
95
95
  _DIGEST_RE = re.compile(r"@sha256:[0-9a-f]{64}$")
96
96
  _ENV_NAME_RE = re.compile(r"^[-._a-zA-Z][-._a-zA-Z0-9]*$")
97
97
  _INTERPOLATION_RE = re.compile(r"\$(\{[^}]*\}|[A-Za-z_])")
98
+ # A parameter reference belongs in the channel's ``environment``, not in the portable Compose file (which
99
+ # must run as it is with Docker): ``{{ params`` anywhere in the file is refused.
100
+ _PARAM_TEMPLATE_RE = re.compile(r"\{\{\s*params\b")
98
101
  _MAX_DURATION_SECONDS = 86400.0 # far above any bound the agent accepts; keeps float overflow out of ceil()
99
102
  _DURATION_RE = re.compile(r"^(?:\d+(?:\.\d+)?(?:us|ms|s|m|h))+$")
100
103
  _DURATION_PART_RE = re.compile(r"(\d+(?:\.\d+)?)(us|ms|s|m|h)")
@@ -205,26 +208,6 @@ def snapshot_url_error(url: Any) -> str | None:
205
208
  return None
206
209
 
207
210
 
208
- def environment_overlay_error(value: Any) -> str | None:
209
- """Why ``value`` is not a ``meta.environment`` overlay (``{service: {NAME: "value"}}``), or ``None``.
210
-
211
- Shape only: that each service exists in the file is checked with the file.
212
- """
213
- if not isinstance(value, dict) or not value:
214
- return "must be a mapping of service name to a mapping of NAME to a string value"
215
- for service, values in value.items():
216
- if not isinstance(service, str) or not DNS_LABEL_RE.fullmatch(service):
217
- return f"{service!r} is not a service name (a DNS label)"
218
- if not isinstance(values, dict) or not values:
219
- return f"{service}: must be a non-empty mapping of NAME to a string value"
220
- for key, text in values.items():
221
- if not isinstance(key, str) or not _ENV_NAME_RE.fullmatch(key):
222
- return f"{service}.{key}: {key!r} is not a valid environment variable name"
223
- if not isinstance(text, str):
224
- return f"{service}.{key}: the value must be a string"
225
- return None
226
-
227
-
228
211
  def sha256_error(value: Any) -> str | None:
229
212
  if not isinstance(value, str) or not _SHA256_RE.fullmatch(value):
230
213
  return "must be 64 lowercase hexadecimal characters"
@@ -352,11 +335,33 @@ class _Checker:
352
335
  if str(service) not in services:
353
336
  self.error(
354
337
  "overlay_service",
355
- f"meta.environment.{service}",
338
+ f"environment.{service}",
356
339
  f"{service!r} is not a service of the file; its services are {', '.join(map(str, services))}",
357
340
  )
341
+ self._templates(doc)
358
342
  self._channel_context()
359
343
 
344
+ def _templates(self, doc: dict[str, Any]) -> None:
345
+ """``{{ params.NAME }}`` is not allowed in the file: the channel's ``environment`` is where it goes."""
346
+
347
+ def scan(value: Any, where: str) -> None:
348
+ if isinstance(value, str):
349
+ if _PARAM_TEMPLATE_RE.search(value):
350
+ self.error(
351
+ "bad_template",
352
+ where,
353
+ "`{{ params.NAME }}` is not allowed in the instance spec: set the value in the channel's "
354
+ "`environment`, so the file stays plain Compose",
355
+ )
356
+ elif isinstance(value, dict):
357
+ for key, item in value.items():
358
+ scan(item, f"{where}.{key}" if where else str(key))
359
+ elif isinstance(value, list):
360
+ for index, item in enumerate(value):
361
+ scan(item, f"{where}[{index}]")
362
+
363
+ scan(doc, "")
364
+
360
365
  def _top_volumes(self, volumes: Any) -> set[str]:
361
366
  if volumes is None:
362
367
  return set()
@@ -418,8 +423,8 @@ class _Checker:
418
423
  "ignored_key",
419
424
  f"{at}.env_file",
420
425
  "`env_file` is ignored: the values it would supply are missing from the instance, so the "
421
- "service may not start. Provide them with `meta.environment` on the instance_spec Document "
422
- f"(meta.environment.{name}.NAME)",
426
+ "service may not start. Provide them with `environment` on the container channel "
427
+ f"(environment.{name}.NAME)",
423
428
  loud=True,
424
429
  )
425
430
  self.drop(name, "env_file")
@@ -591,8 +596,8 @@ class _Checker:
591
596
  return None, None
592
597
  return number, published
593
598
 
594
- def _overlay(self, where: str = "meta.environment") -> dict[str, dict[str, str]]:
595
- """The ``meta.environment`` overlay, checked: ``{service: {NAME: "value"}}`` of strings."""
599
+ def _overlay(self, where: str = "environment") -> dict[str, dict[str, str]]:
600
+ """The channel's ``environment``, checked: ``{service: {NAME: "value"}}`` of strings."""
596
601
  overlay = self.overlay
597
602
  if overlay is None:
598
603
  return {}
@@ -617,8 +622,8 @@ class _Checker:
617
622
  self.warn(
618
623
  "interpolation",
619
624
  f"{at}.{key}",
620
- "contains a variable reference, kept as written; only ${UNITYSVC_INSTANCE_API_KEY} is "
621
- "bound per instance, how any other secret is bound is not decided yet "
625
+ "contains a variable reference, kept as written; only {{ params.NAME }} is bound per "
626
+ "instance, how any other secret is bound is not decided yet "
622
627
  "(unitysvc-core#105, open 4)",
623
628
  )
624
629
  result[str(service)] = clean
@@ -967,18 +972,18 @@ def validate_instance_spec(
967
972
  *,
968
973
  format: str = DEFAULT_FORMAT,
969
974
  channel: ContainerChannel | None = None,
970
- environment: dict[str, dict[str, str]] | None = None,
975
+ # (the channel's ``environment`` is read from ``channel``)
971
976
  ) -> InstanceSpecReport:
972
977
  """Validate an instance spec's content, with the channel that runs it when known.
973
978
 
974
979
  Checks the Compose allowlist and the static rules (literal digests,
975
980
  container-side ports, health checks, volumes, networks, service names). With
976
981
  ``channel``, also that every entry targets a declared service and port and
977
- that ``resources.services`` names the spec's services. ``environment`` is the
978
- Document's ``meta.environment`` overlay: each service in it must exist in the
979
- file. Never raises on bad input: the problems are in the report.
982
+ that ``resources.services`` names the spec's services, and that each service in the
983
+ channel's ``environment`` exists in the file. Never raises on bad input: the problems
984
+ are in the report.
980
985
  """
981
- return _check(text, format, channel, environment).report
986
+ return _check(text, format, channel, channel.environment if channel else None).report
982
987
 
983
988
 
984
989
  def compile_instance_spec(
@@ -994,9 +999,8 @@ def compile_instance_spec(
994
999
  are split by ``resources.services``. Raises :class:`InstanceSpecError`
995
1000
  (carrying the report) if the spec is not valid for these resources.
996
1001
 
997
- ``environment`` is the Document's ``meta.environment`` overlay, merged here
998
- and only here: a value overrides the file's own ``environment`` for that
999
- name, and the Compose bytes are never edited.
1002
+ ``environment`` is the channel's ``environment``, merged here and only here: a value
1003
+ overrides the file's own ``environment`` for that name, and the Compose bytes are never edited.
1000
1004
 
1001
1005
  PROPOSAL (unitysvc-core#105, open 3): that core compiles, rather than the
1002
1006
  agent, is not decided.
@@ -46,7 +46,7 @@ from pydantic import (
46
46
  from pydantic.json_schema import JsonSchemaValue
47
47
  from pydantic_core import CoreSchema
48
48
 
49
- from .container import ContainerEntry, ContainerResources
49
+ from .container import DNS_LABEL_RE, ContainerEntry, ContainerResources
50
50
  from .validators import validate_channel_name
51
51
 
52
52
  # A string field that is a value or a template rendering to one.
@@ -396,12 +396,17 @@ class McpChannel(_ChannelBase):
396
396
  servers: list[McpServer] = Field(default_factory=list)
397
397
 
398
398
 
399
+ _ENV_NAME_RE = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
400
+ _PARAM_REFERENCE_RE = re.compile(r"\{\{\s*params\.[A-Za-z_][A-Za-z0-9_]*\s*\}\}")
401
+
402
+
399
403
  class ContainerChannel(_ChannelBase):
400
404
  """A tier of a service that runs as instances on Kubernetes (unitysvc/unitysvc-core#105).
401
405
 
402
406
  The instance spec is the offering's single ``instance_spec`` Document (or its
403
407
  ``instance_spec`` shortcut) and every container channel runs it; ``resources``
404
- is the tier total. ``servers`` is optional and
408
+ is the tier total and ``environment`` this channel's environment values, which may read its
409
+ enrollment parameters. ``servers`` is optional and
405
410
  has no container-specific meaning: each is an ordinary ``HttpServer`` the
406
411
  gateway reaches, and the listing rule (an enrollable channel and a matching
407
412
  ``/e/{{ enrollment.code }}`` interface) is checked by the validator, which
@@ -415,23 +420,34 @@ class ContainerChannel(_ChannelBase):
415
420
  entries: list[ContainerEntry] | None = Field(
416
421
  default=None, description="PROVISIONAL (#105 open 1): the URLs the instance is reached at"
417
422
  )
423
+ environment: dict[str, dict[str, str]] | None = Field(
424
+ default=None,
425
+ description=(
426
+ "Environment values per service of the instance spec, ``{service: {NAME: value}}``. A value may "
427
+ "be, or contain, ``{{ params.NAME }}``: this channel's enrollment parameter, bound when the instance "
428
+ "starts (unitysvc/unitysvc#3023). Overrides the same name in the spec."
429
+ ),
430
+ )
431
+
432
+ @field_validator("environment")
433
+ @classmethod
434
+ def _check_environment(cls, value: dict[str, dict[str, str]] | None) -> dict[str, dict[str, str]] | None:
435
+ for service, values in (value or {}).items():
436
+ if not DNS_LABEL_RE.fullmatch(service):
437
+ raise ValueError(f"{service!r} is not a service name (a DNS label)")
438
+ if not values:
439
+ raise ValueError(f"{service}: give at least one NAME: value")
440
+ for key, text in values.items():
441
+ if not _ENV_NAME_RE.fullmatch(key):
442
+ raise ValueError(f"{service}.{key}: {key!r} is not a valid environment variable name")
443
+ if "{{" in _PARAM_REFERENCE_RE.sub("", text):
444
+ raise ValueError(f"{service}.{key}: the only template allowed is {{{{ params.NAME }}}}")
445
+ return value
418
446
 
419
447
  @model_validator(mode="after")
420
448
  def _check_container(self) -> "ContainerChannel":
421
449
  if self.type not in (None, "enrollable"):
422
450
  raise ValueError("a container channel is always enrollable: omit 'type' or set it to 'enrollable'")
423
- requests = self.customer_access_requests or []
424
- if not any(
425
- r.get("object") == "resource:container"
426
- and "create" in (r.get("permissions") or [])
427
- and r.get("required") is True
428
- for r in requests
429
- ):
430
- raise ValueError(
431
- "a container channel must request resource:container with the create permission, and mark it "
432
- 'required: customer_access_requests: [{"object": "resource:container", "permissions": ["create"], '
433
- '"required": true, "justification": "..."}]'
434
- )
435
451
  names = [entry.name for entry in self.entries or []]
436
452
  if duplicates := sorted({n for n in names if names.count(n) > 1}):
437
453
  raise ValueError(f"entry names must be unique: {', '.join(duplicates)}")
@@ -62,7 +62,6 @@ class DocumentData(BaseModel):
62
62
  if self.category == DocumentCategoryEnum.instance_spec:
63
63
  from ..instance_spec import (
64
64
  SUPPORTED_FORMATS,
65
- environment_overlay_error,
66
65
  instance_spec_format,
67
66
  sha256_error,
68
67
  snapshot_url_error,
@@ -81,6 +80,9 @@ class DocumentData(BaseModel):
81
80
  raise ValueError(f"instance_spec meta.source {problem}")
82
81
  if "sha256" in meta and (problem := sha256_error(meta["sha256"])):
83
82
  raise ValueError(f"instance_spec meta.sha256 {problem}")
84
- if "environment" in meta and (problem := environment_overlay_error(meta["environment"])):
85
- raise ValueError(f"instance_spec meta.environment {problem}")
83
+ if "environment" in meta:
84
+ raise ValueError(
85
+ "instance_spec meta.environment is not supported: set the values in the container "
86
+ "channel's `environment`"
87
+ )
86
88
  return self
@@ -285,7 +285,7 @@
285
285
  },
286
286
  "ContainerChannel": {
287
287
  "additionalProperties": false,
288
- "description": "A tier of a service that runs as instances on Kubernetes (unitysvc/unitysvc-core#105).\n\nThe instance spec is the offering's single ``instance_spec`` Document (or its\n``instance_spec`` shortcut) and every container channel runs it; ``resources``\nis the tier total. ``servers`` is optional and\nhas no container-specific meaning: each is an ordinary ``HttpServer`` the\ngateway reaches, and the listing rule (an enrollable channel and a matching\n``/e/{{ enrollment.code }}`` interface) is checked by the validator, which\nsees the listing. ``entries`` is PROVISIONAL (#105 open 1 and 2).",
288
+ "description": "A tier of a service that runs as instances on Kubernetes (unitysvc/unitysvc-core#105).\n\nThe instance spec is the offering's single ``instance_spec`` Document (or its\n``instance_spec`` shortcut) and every container channel runs it; ``resources``\nis the tier total and ``environment`` this channel's environment values, which may read its\nenrollment parameters. ``servers`` is optional and\nhas no container-specific meaning: each is an ordinary ``HttpServer`` the\ngateway reaches, and the listing rule (an enrollable channel and a matching\n``/e/{{ enrollment.code }}`` interface) is checked by the validator, which\nsees the listing. ``entries`` is PROVISIONAL (#105 open 1 and 2).",
289
289
  "properties": {
290
290
  "acceptable_formats": {
291
291
  "anyOf": [
@@ -424,6 +424,25 @@
424
424
  "description": "PROVISIONAL (#105 open 1): the URLs the instance is reached at",
425
425
  "title": "Entries"
426
426
  },
427
+ "environment": {
428
+ "anyOf": [
429
+ {
430
+ "additionalProperties": {
431
+ "additionalProperties": {
432
+ "type": "string"
433
+ },
434
+ "type": "object"
435
+ },
436
+ "type": "object"
437
+ },
438
+ {
439
+ "type": "null"
440
+ }
441
+ ],
442
+ "default": null,
443
+ "description": "Environment values per service of the instance spec, ``{service: {NAME: value}}``. A value may be, or contain, ``{{ params.NAME }}``: this channel's enrollment parameter, bound when the instance starts (unitysvc/unitysvc#3023). Overrides the same name in the spec.",
444
+ "title": "Environment"
445
+ },
427
446
  "headers": {
428
447
  "anyOf": [
429
448
  {
@@ -768,9 +768,7 @@ class DataValidator:
768
768
  continue # the channel's own errors are reported by the schema checks
769
769
  if text is None or doc.get("external_url") is not None:
770
770
  continue # a URL is validated by the backend on the snapshot; a missing file by the file checks
771
- report = validate_instance_spec(
772
- text, format=fmt, channel=channel, environment=(doc.get("meta") or {}).get("environment")
773
- )
771
+ report = validate_instance_spec(text, format=fmt, channel=channel)
774
772
  errors.extend(f"{at}.instance_spec ({title!r}): {issue}" for issue in report.errors)
775
773
  warnings.extend(issue.model_copy(update={"path": f"{at}: {issue.path}"}) for issue in report.warnings)
776
774
  return errors, warnings
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: unitysvc-core
3
- Version: 0.3.12
3
+ Version: 0.3.14
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>
@@ -290,18 +290,14 @@ A `container` channel is one tier of a service that runs as instances on Kuberne
290
290
  "base": {
291
291
  "access_method": "container",
292
292
  "resources": {"limits": {"cpu": "250m", "memory": "256Mi", "ephemeral-storage": "1Gi"}},
293
- "entries": [{"name": "web", "service": "web", "port": 5678, "auth": "key"}],
294
- "customer_access_requests": [
295
- {"object": "resource:container", "permissions": ["create"], "required": true,
296
- "justification": "Run a disposable application instance for this enrollment"}
297
- ]
293
+ "entries": [{"name": "web", "service": "web", "port": 5678, "auth": "key"}]
298
294
  }
299
295
  }
300
296
  ```
301
297
 
302
298
  - There is no per-channel spec: every container channel of the offering runs the offering's one instance spec (below), so tiers differ in `resources`, not in stack. The earlier `spec` field (a Document title) is removed in 0.3.11; a channel carrying it is refused as an unknown field.
303
299
  - `resources` is the tier total, in Kubernetes' shape: `limits`, optionally `requests`, each a map from a resource name to a quantity (`250m`, `1Gi`, `1e3`, parsed as Kubernetes parses them). The names are `cpu`, `memory`, `ephemeral-storage` and `nvidia.com/gpu`; the first three limits are required; a request is at most its limit; a GPU is a whole number with a request equal to the limit. `resources.services` is an optional per-service split (`{"web": {"limits": {...}}}`) whose sums must stay within the tier (each share names `cpu`, `memory` and `ephemeral-storage`, and a resource without a request counts at its limit, as the agent resolves it); a spec with several services needs one. Quantities are at most 64 characters with an exponent of at most 30. A Compose `deploy.resources` is ignored: the channel is authoritative.
304
- - The channel is always enrollable and must request `resource:container` with `create`, marked `required` (`grants.RESOURCES` knows the resource; it has no options and no limits).
300
+ - The channel is always enrollable and needs no `customer_access_requests`: the customer runs their own instance, which grants the seller nothing (a request is for the seller to call the customer's services). A channel that does declare one is `me_bound` instead of `enrollable`.
305
301
  - `servers` is optional and has no container-specific meaning: each is an ordinary `HttpServer` the gateway reaches, for example `{"base_url": "https://{{ enrollment.code }}.unitysvc.app/"}`. A container-only service sets no `servers`. An enrollable channel is reached at `/e/<CODE>` on the API gateway, which the platform provides; a listing never declares it (see Canonical user access interfaces).
306
302
  - `entries` (`name`, `service`, `port`, optional `path`, `auth` of `login`, `key` or `app`) is **provisional** (open question 1 of #105: whether instances need URLs beyond `servers`, and which `auth` values apply; `gateway` is deliberately not accepted).
307
303
  - `params` and `customer_access_requests` are as on the other channels.
@@ -329,20 +325,22 @@ The seller tooling expands the shortcut before upload with `expand_instance_spec
329
325
  | --- | --- |
330
326
  | Honor | `image` (a tag, or a literal digest `name:tag@sha256:...`; a tag-only image warns), `command`, `entrypoint`, `environment`, `ports` (container side only), `healthcheck`, `working_dir`, `user`, `read_only` |
331
327
  | Ignore, warn | `container_name`, `restart`, `labels`, `logging`, `networks`, the host side of `ports`, `expose`, `profiles`, `links`, `x-*`, `deploy.resources`, top-level `name`, `version`, `networks` |
332
- | Ignore, warn loudly | `depends_on` (no start ordering: the app must retry; readiness keeps traffic away), `env_file` (the values it would supply are missing: provide them with `meta.environment`), named volumes (scratch space: data survives a container restart, not a replacement of the instance) |
328
+ | Ignore, warn loudly | `depends_on` (no start ordering: the app must retry; readiness keeps traffic away), `env_file` (the values it would supply are missing: provide them with the channel's `environment`), named volumes (scratch space: data survives a container restart, not a replacement of the instance) |
333
329
  | Reject | `build`, `privileged`, `cap_add`, `devices`, `network_mode`, `pid`, `ipc`, `security_opt`, `sysctls`, bind mounts and host paths, `volumes_from`, a named volume shared by two services, `runtime`, `extra_hosts`, `secrets`, `configs`, `extends`, `include`, an `image` with a malformed digest, two services that share no network, any other key |
334
330
 
335
331
  A seller can keep one file for local Docker and the platform and leave `deploy.resources` in place. **Images.** A tag-only or untagged `image` (`:latest`, `:1.4`, none) is accepted with a note (`unpinned_image`, a warning): the platform runs it as written and reports the digest it pulled, and a moving tag can change at a restart; a re-upload does not update running instances. A digest the seller writes (`name:tag@sha256:...`) is honored as written; one that is malformed is an error (`bad_digest`). Core never contacts a registry. Sibling services reach each other by name (`redis:6379`); service names must be DNS labels. `${VAR}` in an `environment` value is kept as written with a warning (how a secret or parameter binds to it is open question 4 of #105); in `image` and `ports` a variable is an error.
336
332
 
337
- **Reusing a generic Compose file.** A seller can keep one generic file (in their repo) and vary it for UnitySVC in the Document's `meta`: `meta.environment` is `{service: {NAME: "value"}}`; each service must exist in the file and each value is a string with a valid variable name. It overrides the file's own `environment` on a name conflict, and it is applied only at compile time (`compile_instance_spec(text, resources, environment=...)`), so the stored Compose bytes stay an exact copy of the seller's file and the seller's local test and the backend merge identically. `validate_instance_spec(..., environment=...)` checks it against the file (`overlay_service`). Values are plaintext in the spec; only `${UNITYSVC_INSTANCE_API_KEY}` is bound per instance (any other `${...}` only warns, open question 4 of #105). Only `environment` is supported, not a general override. `meta.sha256` is recommended with a URL, so an upstream change that breaks the overlay fails the upload.
333
+ **Reusing a generic Compose file, and the environment.** A seller keeps one generic, plain Compose file (it runs as it is with Docker) and sets the instance's environment on each container channel: `environment` is `{service: {NAME: "value"}}`; each service must exist in the file and each name is a valid variable name. A value may be, or contain, `{{ params.NAME }}`: that channel's own enrollment parameter, which the platform binds when the instance starts (any other `{{` is refused, and `{{ params` in the Compose file is a `bad_template` error). The channel's value overrides the file's own `environment` on a name conflict. It is applied only at compile time (`compile_instance_spec(text, resources, environment=...)`), so the stored Compose bytes stay an exact copy of the seller's file; `validate_instance_spec(text, channel=...)` checks the channel's environment against the file (`overlay_service`). There is no platform-issued instance key: a secret is an ordinary enrollment parameter. A Document's `meta.environment` is no longer supported. `meta.sha256` is recommended with a URL, so an upstream change that breaks the environment fails the upload.
338
334
 
339
335
  ```json
340
336
  "documents": {"Instance spec": {
341
337
  "category": "instance_spec", "mime_type": "text",
342
338
  "external_url": "https://raw.githubusercontent.com/Kadxy/weixin-ilink-gateway/<commit-sha>/docker-compose.yaml",
343
- "meta": {"format": "compose", "sha256": "<64 hex>",
344
- "environment": {"gateway": {"API_KEY": "${UNITYSVC_INSTANCE_API_KEY}"}}}
345
- }}
339
+ "meta": {"format": "compose", "sha256": "<64 hex>"}
340
+ }},
341
+ "upstream_access_config": {"base": {"access_method": "container",
342
+ "params": {"schema": {"properties": {"WEIXIN_API_KEY": {"type": "string", "default": "{{ token_urlsafe(32) }}"}}, "required": ["WEIXIN_API_KEY"]}},
343
+ "environment": {"gateway": {"API_KEY": "{{ params.WEIXIN_API_KEY }}"}}}}
346
344
  ```
347
345
 
348
346
  **Validating.** `validate_instance_spec(text, format="compose", channel=ContainerChannel | None)` returns an `InstanceSpecReport` of `errors` and `warnings`, each an `InstanceSpecIssue(code, path, message, loud)`; with the channel it also checks that every entry targets a declared service and port and that `resources.services` names the spec's services. It never raises on bad input. The seller CLI and backend ingest call it, directly or through `DataValidator`: `validate_service` / `validate_data_file` report the errors of every container channel's spec under `upstream_access_config.<channel>.instance_spec`, and `DataValidator.service_warnings(offering, service_dir)` returns the warnings (`issue.loud` for the ones a seller must not miss) for `specs validate` to print after the errors.
@@ -357,7 +355,7 @@ A seller can keep one file for local Docker and the platform and leave `deploy.r
357
355
 
358
356
  Each `entry` must name an entry of the offering's container channels. A script (any other file) is run as before. Core publishes the schema and fixtures (`tests/fixtures/probes`); the runners live in unitysvc-sellers and unitysvc-compute-k8s. The derived test is only as strict as `health`.
359
357
 
360
- Examples: `tests/example_data/hashicorp/services/echo` (one service, two tiers); `tests/example_data/kadxy/services/weixin-ilink-gateway` (secrets, scratch state, outbound traffic; its image digest is a marked placeholder); and `tests/example_data/kadxy/services/weixin-ilink-gateway-upstream` (the project's own Compose file by URL at a pinned commit with `meta.sha256`, plus a `meta.environment` overlay; `upstream-compose.yaml` is a byte-for-byte copy of that file, and `meta.sha256` is its hash, as core fetches nothing).
358
+ Examples: `tests/example_data/hashicorp/services/echo` (one service, two tiers); `tests/example_data/kadxy/services/weixin-ilink-gateway` (secrets, scratch state, outbound traffic; its image digest is a marked placeholder); and `tests/example_data/kadxy/services/weixin-ilink-gateway-upstream` (the project's own Compose file by URL at a pinned commit with `meta.sha256`, plus a channel `environment`; `upstream-compose.yaml` is a byte-for-byte copy of that file, and `meta.sha256` is its hash, as core fetches nothing).
361
359
 
362
360
  ### Request rules
363
361
 
@@ -48,7 +48,6 @@ def _channel(**changes: Any) -> dict[str, Any]:
48
48
  channel: dict[str, Any] = {
49
49
  "access_method": "container",
50
50
  "resources": {"limits": dict(LIMITS)},
51
- "customer_access_requests": [dict(REQUEST)],
52
51
  }
53
52
  channel.update(changes)
54
53
  return channel
@@ -172,6 +171,43 @@ class TestResources:
172
171
  assert validate_instance_spec(_compose(healthcheck={"test": ["CMD", "x"], field: ok})).ok
173
172
 
174
173
 
174
+ class TestParameterReferences:
175
+ """``{{ params.NAME }}`` belongs in the channel's ``environment``, not in the Compose file (unitysvc#3023)."""
176
+
177
+ @pytest.mark.parametrize(
178
+ "service",
179
+ [
180
+ {"environment": {"A": "{{ params.X }}"}},
181
+ {"environment": ["A={{params.X}}"]},
182
+ {"image": "{{ params.X }}"},
183
+ {"command": ["run", "{{ params.X }}"]},
184
+ ],
185
+ )
186
+ def test_the_file_may_not_carry_one(self, service: dict[str, Any]) -> None:
187
+ assert "bad_template" in _codes(validate_instance_spec(_compose(**service)))
188
+
189
+ def test_other_braces_are_left_alone(self) -> None:
190
+ assert validate_instance_spec(_compose(healthcheck={"test": ["CMD", "echo", "{{.State.Status}}"]})).ok
191
+
192
+ def test_a_channel_may_set_environment_from_its_params(self) -> None:
193
+ channel = {**_channel(), "environment": {"web": {"API_KEY": "{{ params.KEY }}", "MODE": "x-{{params.M}}"}}}
194
+ assert ContainerChannel.model_validate(channel).environment == channel["environment"]
195
+
196
+ @pytest.mark.parametrize(
197
+ "environment",
198
+ [
199
+ {"web": {"A": "{{ other }}"}},
200
+ {"web": {"A": "{{ params.X | upper }}"}},
201
+ {"Web!": {"A": "1"}},
202
+ {"web": {"1A": "1"}},
203
+ {"web": {}},
204
+ ],
205
+ )
206
+ def test_a_bad_channel_environment_is_refused(self, environment: dict[str, Any]) -> None:
207
+ with pytest.raises(ValidationError):
208
+ ContainerChannel.model_validate({**_channel(), "environment": environment})
209
+
210
+
175
211
  # --- the channel ----------------------------------------------------------------------------------
176
212
 
177
213
 
@@ -188,25 +224,15 @@ class TestChannel:
188
224
  with pytest.raises(ValidationError, match="resources"):
189
225
  ContainerChannel.model_validate(data)
190
226
 
191
- @pytest.mark.parametrize(
192
- "requests",
193
- [
194
- None,
195
- [],
196
- [{**REQUEST, "required": False}],
197
- [{**REQUEST, "permissions": ["join"]}],
198
- [{"object": "service:x", "permissions": ["invoke"], "required": True, "justification": "x"}],
199
- ],
200
- )
201
- def test_requires_the_container_create_request(self, requests: Any) -> None:
202
- data = _channel(customer_access_requests=requests)
203
- with pytest.raises(ValidationError, match="resource:container"):
204
- ContainerChannel.model_validate(data)
227
+ def test_a_container_channel_needs_no_access_request(self) -> None:
228
+ """The customer runs their own instance and grants the seller nothing (unitysvc#3023)."""
229
+ channel = ContainerChannel.model_validate(_channel())
230
+ assert not channel.customer_access_requests
205
231
 
206
232
  def test_the_request_passes_the_grants_checks(self, tmp_path: Path) -> None:
207
233
  (tmp_path / "compose.yaml").write_text(_compose())
208
234
  errors = DataValidator(EXAMPLES, SCHEMA_DIR).validate_service(
209
- offering=_offering({"base": _channel()}), service_dir=tmp_path
235
+ offering=_offering({"base": _channel(customer_access_requests=[REQUEST])}), service_dir=tmp_path
210
236
  )
211
237
  assert errors["offering"] == []
212
238
 
@@ -887,7 +913,7 @@ class TestExamples:
887
913
  loud = {w.code for w in report.warnings if w.loud}
888
914
  assert {"ignored_key", "scratch_volume"} <= loud
889
915
  env_file = next(w for w in report.warnings if w.path == "services.gateway.env_file")
890
- assert env_file.loud and "meta.environment" in env_file.message and "missing" in env_file.message
916
+ assert env_file.loud and "environment" in env_file.message and "missing" in env_file.message
891
917
  assert "unpinned_image" in _codes(report, "warnings")
892
918
 
893
919
  def test_a_bad_spec_fails_the_offering(self, validator: DataValidator, tmp_path: Path) -> None:
@@ -1239,7 +1265,7 @@ class TestEnvFile:
1239
1265
  assert report.ok, report.errors
1240
1266
  warning = next(w for w in report.warnings if w.path == "services.web.env_file")
1241
1267
  assert warning.code == "ignored_key" and warning.loud
1242
- assert "missing" in warning.message and "meta.environment" in warning.message
1268
+ assert "missing" in warning.message and "environment" in warning.message
1243
1269
  compiled = compile_instance_spec(_compose(env_file=".env"), _resources())
1244
1270
  assert ("web", "env_file", "ignored") in {(d.service, d.key, d.reason) for d in compiled.dropped}
1245
1271
 
@@ -1259,51 +1285,30 @@ class TestEnvironmentOverlay:
1259
1285
  assert text == self.compose()
1260
1286
 
1261
1287
  def test_it_supplies_what_env_file_would_have(self) -> None:
1262
- overlay = {"web": {"API_KEY": "${UNITYSVC_INSTANCE_API_KEY}"}}
1288
+ overlay = {"web": {"API_KEY": "${SECRET_KEY}"}}
1263
1289
  text = _compose(env_file=".env")
1264
1290
  env = compile_instance_spec(text, _resources(), environment=overlay).manifest.services[0].env
1265
- assert env == {"API_KEY": "${UNITYSVC_INSTANCE_API_KEY}"}
1266
- report = validate_instance_spec(text, environment=overlay)
1291
+ assert env == {"API_KEY": "${SECRET_KEY}"}
1292
+ report = validate_instance_spec(text, channel=ContainerChannel.model_validate(_channel(environment=overlay)))
1267
1293
  assert report.ok and "interpolation" in _codes(report, "warnings")
1268
1294
 
1269
1295
  def test_a_service_the_file_lacks_is_an_error(self) -> None:
1270
- report = validate_instance_spec(self.compose(), environment={"ghost": {"A": "1"}})
1296
+ ghost = ContainerChannel.model_validate(_channel(environment={"ghost": {"A": "1"}}))
1297
+ report = validate_instance_spec(self.compose(), channel=ghost)
1271
1298
  assert "overlay_service" in _codes(report)
1272
1299
  with pytest.raises(InstanceSpecError):
1273
1300
  compile_instance_spec(self.compose(), _resources(), environment={"ghost": {"A": "1"}})
1274
1301
 
1275
- @pytest.mark.parametrize(
1276
- "overlay",
1277
- [
1278
- {"web": {"1 BAD": "x"}},
1279
- {"web": {"A": 1}},
1280
- {"web": {"A": None}},
1281
- {"web": ["A=1"]},
1282
- {"Web": {"A": "1"}},
1283
- {"web": {}},
1284
- {},
1285
- ["web"],
1286
- "A=1",
1287
- ],
1288
- )
1289
- def test_the_document_refuses_a_bad_overlay(self, overlay: Any) -> None:
1302
+ def test_the_document_no_longer_takes_an_overlay(self) -> None:
1290
1303
  doc = {
1291
1304
  "category": "instance_spec",
1292
1305
  "mime_type": "text",
1293
1306
  "file_path": "c.yaml",
1294
- "meta": {"environment": overlay},
1307
+ "meta": {"environment": {"web": {"A": "1"}}},
1295
1308
  }
1296
- with pytest.raises(ValidationError, match="meta.environment"):
1309
+ with pytest.raises(ValidationError, match="channel's `environment`"):
1297
1310
  DocumentData.model_validate(doc)
1298
1311
 
1299
- def test_the_document_accepts_an_overlay_and_the_validator_checks_it(self, validator: DataValidator) -> None:
1300
- offering = expand_instance_spec(_echo())
1301
- doc = offering["documents"][INSTANCE_SPEC_TITLE]
1302
- doc["meta"]["environment"] = {"web": {"GREETING": "hi"}}
1303
- assert _errors(validator, offering) == []
1304
- doc["meta"]["environment"] = {"ghost": {"GREETING": "hi"}}
1305
- assert any("meta.environment.ghost" in e for e in _errors(validator, offering))
1306
-
1307
1312
  def test_the_schema_describes_meta_as_open(self) -> None:
1308
1313
  schema = json.loads((SCHEMA_DIR / "offering_v1.json").read_text())
1309
1314
  assert "instance_spec" in json.dumps(schema)
@@ -1354,7 +1359,8 @@ class TestReviewFixes:
1354
1359
  text = _compose(environment=env)
1355
1360
  assert "bad_env" in _codes(validate_instance_spec(text))
1356
1361
  overlay = {"web": {"KEY": "v"}}
1357
- assert validate_instance_spec(text, environment=overlay).ok
1362
+ channel = ContainerChannel.model_validate(_channel(environment=overlay))
1363
+ assert validate_instance_spec(text, channel=channel).ok
1358
1364
  assert compile_instance_spec(text, _resources(), environment=overlay).manifest.services[0].env == {
1359
1365
  "KEY": "v"
1360
1366
  }
@@ -1383,17 +1389,16 @@ class TestUpstreamExample:
1383
1389
  == hashlib.sha256((WEIXIN_UPSTREAM / "upstream-compose.yaml").read_bytes()).hexdigest()
1384
1390
  )
1385
1391
 
1386
- def test_the_overlay_and_scratch_reach_the_manifest(self) -> None:
1392
+ def test_the_channel_environment_and_scratch_reach_the_manifest(self) -> None:
1387
1393
  offering = self.offering()
1388
- doc = offering["documents"][INSTANCE_SPEC_TITLE]
1389
1394
  channel = ContainerChannel.model_validate(offering["upstream_access_config"]["base"])
1390
1395
  compiled = compile_instance_spec(
1391
1396
  (WEIXIN_UPSTREAM / "upstream-compose.yaml").read_text(),
1392
1397
  channel.resources,
1393
- environment=doc["meta"]["environment"],
1398
+ environment=channel.environment,
1394
1399
  )
1395
1400
  service = compiled.manifest.services[0]
1396
- assert service.env == {"DATA_DIR": "/app/data", "API_KEY": "${UNITYSVC_INSTANCE_API_KEY}"}
1401
+ assert service.env == {"DATA_DIR": "/app/data", "API_KEY": "change-me-at-least-12-chars"}
1397
1402
  assert service.image == "ghcr.io/kadxy/weixin-ilink-gateway:latest"
1398
1403
  assert [s.path for s in service.scratch or []] == ["/app/data"]
1399
1404
 
File without changes
File without changes