unitysvc-core 0.3.11__tar.gz → 0.3.13__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.11/src/unitysvc_core.egg-info → unitysvc_core-0.3.13}/PKG-INFO +20 -7
  2. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/README.md +19 -6
  3. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/pyproject.toml +1 -1
  4. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/src/unitysvc_core/instance_spec.py +151 -25
  5. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/src/unitysvc_core/models/channel.py +30 -2
  6. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/src/unitysvc_core/models/documents.py +5 -0
  7. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/src/unitysvc_core/models/manifest.py +34 -0
  8. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/src/unitysvc_core/schema/normalized_manifest_v1.json +33 -0
  9. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/src/unitysvc_core/schema/offering_v1.json +20 -1
  10. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13/src/unitysvc_core.egg-info}/PKG-INFO +20 -7
  11. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/tests/test_container.py +260 -17
  12. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/LICENSE +0 -0
  13. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/setup.cfg +0 -0
  14. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/src/unitysvc_core/__init__.py +0 -0
  15. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/src/unitysvc_core/grants.py +0 -0
  16. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/src/unitysvc_core/models/__init__.py +0 -0
  17. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/src/unitysvc_core/models/base.py +0 -0
  18. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/src/unitysvc_core/models/container.py +0 -0
  19. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/src/unitysvc_core/models/listing_data.py +0 -0
  20. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/src/unitysvc_core/models/listing_v1.py +0 -0
  21. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/src/unitysvc_core/models/offering_data.py +0 -0
  22. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/src/unitysvc_core/models/offering_v1.py +0 -0
  23. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/src/unitysvc_core/models/pricing.py +0 -0
  24. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/src/unitysvc_core/models/probes.py +0 -0
  25. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/src/unitysvc_core/models/promotion_data.py +0 -0
  26. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/src/unitysvc_core/models/provider_data.py +0 -0
  27. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/src/unitysvc_core/models/provider_v1.py +0 -0
  28. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/src/unitysvc_core/models/service.py +0 -0
  29. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/src/unitysvc_core/models/service_group_data.py +0 -0
  30. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/src/unitysvc_core/models/validators.py +0 -0
  31. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/src/unitysvc_core/parameter_usage.py +0 -0
  32. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/src/unitysvc_core/py.typed +0 -0
  33. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/src/unitysvc_core/schema/base.json +0 -0
  34. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/src/unitysvc_core/schema/listing_v1.json +0 -0
  35. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/src/unitysvc_core/schema/probes_v1.json +0 -0
  36. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/src/unitysvc_core/schema/promotion_v1.json +0 -0
  37. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/src/unitysvc_core/schema/provider_v1.json +0 -0
  38. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/src/unitysvc_core/schema/service_group_v1.json +0 -0
  39. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/src/unitysvc_core/utils.py +0 -0
  40. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/src/unitysvc_core/validator.py +0 -0
  41. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/src/unitysvc_core.egg-info/SOURCES.txt +0 -0
  42. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/src/unitysvc_core.egg-info/dependency_links.txt +0 -0
  43. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/src/unitysvc_core.egg-info/requires.txt +0 -0
  44. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/src/unitysvc_core.egg-info/top_level.txt +0 -0
  45. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/tests/test_access_interface_routing.py +0 -0
  46. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/tests/test_canonical_interfaces.py +0 -0
  47. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/tests/test_channel.py +0 -0
  48. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/tests/test_documents.py +0 -0
  49. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/tests/test_effective_price.py +0 -0
  50. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/tests/test_external_apps.py +0 -0
  51. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/tests/test_grants.py +0 -0
  52. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/tests/test_hidden_path_skip.py +0 -0
  53. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/tests/test_listing_audience.py +0 -0
  54. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/tests/test_offering_data.py +0 -0
  55. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/tests/test_parameter_usage.py +0 -0
  56. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/tests/test_pricing.py +0 -0
  57. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/tests/test_provider_account_rate_limits.py +0 -0
  58. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/tests/test_request_rules.py +0 -0
  59. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/tests/test_service_group.py +0 -0
  60. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/tests/test_service_status.py +0 -0
  61. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/tests/test_utils.py +0 -0
  62. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/tests/test_validate_service.py +0 -0
  63. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/tests/test_validator.py +0 -0
  64. {unitysvc_core-0.3.11 → unitysvc_core-0.3.13}/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.11
3
+ Version: 0.3.13
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>
@@ -327,16 +327,29 @@ The seller tooling expands the shortcut before upload with `expand_instance_spec
327
327
 
328
328
  | Bucket | Features |
329
329
  | --- | --- |
330
- | Honor | `image` (a literal digest: `name:tag@sha256:...`), `command`, `entrypoint`, `environment`, `ports` (container side only), `healthcheck`, `working_dir`, `user`, `read_only` |
330
+ | 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
331
  | 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), named volumes (scratch space: data does not survive a restart) |
333
- | 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`, `env_file`, `secrets`, `configs`, `extends`, `include`, an unpinned `image`, two services that share no network, any other key |
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 the channel's `environment`), named volumes (scratch space: data survives a container restart, not a replacement of the instance) |
333
+ | 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
334
 
335
- A seller can keep one file for local Docker and the platform: write `image` as `name:tag@sha256:...` (Compose runs the digest) and leave `deploy.resources` in place. 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.
335
+ 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
+
337
+ **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
+
339
+ ```json
340
+ "documents": {"Instance spec": {
341
+ "category": "instance_spec", "mime_type": "text",
342
+ "external_url": "https://raw.githubusercontent.com/Kadxy/weixin-ilink-gateway/<commit-sha>/docker-compose.yaml",
343
+ "meta": {"format": "compose", "sha256": "<64 hex>"}
344
+ }},
345
+ "upstream_access_config": {"base": {"access_method": "container",
346
+ "params": {"schema": {"properties": {"WEIXIN_API_KEY": {"type": "string", "default": "{{ token_urlsafe(32) }}"}}, "required": ["WEIXIN_API_KEY"]}},
347
+ "environment": {"gateway": {"API_KEY": "{{ params.WEIXIN_API_KEY }}"}}}}
348
+ ```
336
349
 
337
350
  **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.
338
351
 
339
- **The normalized manifest** is what the agent receives for one instance: the compiled, validated spec. `NormalizedManifest` (JSON Schema `schema/normalized_manifest_v1.json`, which the agent repo vendors) has one service per Compose service with `name`, `image`, `ports`, `env`, `command`, `args`, `resources` (`requests`, `limits`), `replicas` and `health`, in the shapes of the agent's `intent.go`. `compile_instance_spec(text, resources)` returns a `CompiledInstanceSpec`: the manifest, the keys it `dropped` and the warnings. Compose `entrypoint` becomes `command` and Compose `command` becomes `args`; `healthcheck` becomes an `exec` `health` (`interval`, `timeout`, `retries` and `start_period` map to `period_seconds`, `timeout_seconds`, `failure_threshold` and `start_period_seconds`) (bounded as the agent bounds them: period and timeout 1-300 s, retries 1-30, start period at most its default 120 s progress deadline); the tier `resources` go to the single service, or are split by `resources.services`. That core compiles at all is a proposal (open question 3 of #105). `working_dir`, `user`, `read_only` and the scratch volumes are accepted by the policy but the agent's current manifest has no field for them: they are recorded in `dropped` with reason `not_carried` and a warning.
352
+ **The normalized manifest** is what the agent receives for one instance: the compiled, validated spec. `NormalizedManifest` (JSON Schema `schema/normalized_manifest_v1.json`, which the agent repo vendors) has one service per Compose service with `name`, `image`, `ports`, `env`, `command`, `args`, `resources` (`requests`, `limits`), `replicas`, `health` and `scratch` (`[{"path": "/data"}]`, from each named or anonymous volume mount; the cluster gives each an `emptyDir`), in the shapes of the agent's `intent.go` (`scratch` is a core addition the agent vendors the schema for later). `compile_instance_spec(text, resources)` returns a `CompiledInstanceSpec`: the manifest, the keys it `dropped` and the warnings. Compose `entrypoint` becomes `command` and Compose `command` becomes `args`; `healthcheck` becomes an `exec` `health` (`interval`, `timeout`, `retries` and `start_period` map to `period_seconds`, `timeout_seconds`, `failure_threshold` and `start_period_seconds`) (bounded as the agent bounds them: period and timeout 1-300 s, retries 1-30, start period at most its default 120 s progress deadline); the tier `resources` go to the single service, or are split by `resources.services`. That core compiles at all is a proposal (open question 3 of #105). `working_dir`, `user` and `read_only` are accepted by the policy but the agent's current manifest has no field for them: they are recorded in `dropped` with reason `not_carried` and a warning.
340
353
 
341
354
  **The connectivity test is derived.** `validate_connectivity_test_exists` exempts an offering whose channels are all `container`, as it does an external app: the platform starts the services, waits for each one's `health` (or the default TCP check), fetches each entry expecting a success status, and shuts down. A seller may add a declarative `connectivity_test` Document (a `.json` file, `ProbesV1`, schema `schema/probes_v1.json`; a **proposal**), a list of probes run on top of the derived checks:
342
355
 
@@ -346,7 +359,7 @@ A seller can keep one file for local Docker and the platform: write `image` as `
346
359
 
347
360
  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`.
348
361
 
349
- Examples: `tests/example_data/hashicorp/services/echo` (one service, two tiers) and `tests/example_data/kadxy/services/weixin-ilink-gateway` (secrets, scratch state, outbound traffic; its image digest is a marked placeholder and its original `docker-compose.yaml` is a negative test).
362
+ 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).
350
363
 
351
364
  ### Request rules
352
365
 
@@ -291,16 +291,29 @@ The seller tooling expands the shortcut before upload with `expand_instance_spec
291
291
 
292
292
  | Bucket | Features |
293
293
  | --- | --- |
294
- | Honor | `image` (a literal digest: `name:tag@sha256:...`), `command`, `entrypoint`, `environment`, `ports` (container side only), `healthcheck`, `working_dir`, `user`, `read_only` |
294
+ | 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
295
  | 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), named volumes (scratch space: data does not survive a restart) |
297
- | 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`, `env_file`, `secrets`, `configs`, `extends`, `include`, an unpinned `image`, two services that share no network, any other key |
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 the channel's `environment`), named volumes (scratch space: data survives a container restart, not a replacement of the instance) |
297
+ | 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
298
 
299
- A seller can keep one file for local Docker and the platform: write `image` as `name:tag@sha256:...` (Compose runs the digest) and leave `deploy.resources` in place. 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.
299
+ 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
+
301
+ **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
+
303
+ ```json
304
+ "documents": {"Instance spec": {
305
+ "category": "instance_spec", "mime_type": "text",
306
+ "external_url": "https://raw.githubusercontent.com/Kadxy/weixin-ilink-gateway/<commit-sha>/docker-compose.yaml",
307
+ "meta": {"format": "compose", "sha256": "<64 hex>"}
308
+ }},
309
+ "upstream_access_config": {"base": {"access_method": "container",
310
+ "params": {"schema": {"properties": {"WEIXIN_API_KEY": {"type": "string", "default": "{{ token_urlsafe(32) }}"}}, "required": ["WEIXIN_API_KEY"]}},
311
+ "environment": {"gateway": {"API_KEY": "{{ params.WEIXIN_API_KEY }}"}}}}
312
+ ```
300
313
 
301
314
  **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.
302
315
 
303
- **The normalized manifest** is what the agent receives for one instance: the compiled, validated spec. `NormalizedManifest` (JSON Schema `schema/normalized_manifest_v1.json`, which the agent repo vendors) has one service per Compose service with `name`, `image`, `ports`, `env`, `command`, `args`, `resources` (`requests`, `limits`), `replicas` and `health`, in the shapes of the agent's `intent.go`. `compile_instance_spec(text, resources)` returns a `CompiledInstanceSpec`: the manifest, the keys it `dropped` and the warnings. Compose `entrypoint` becomes `command` and Compose `command` becomes `args`; `healthcheck` becomes an `exec` `health` (`interval`, `timeout`, `retries` and `start_period` map to `period_seconds`, `timeout_seconds`, `failure_threshold` and `start_period_seconds`) (bounded as the agent bounds them: period and timeout 1-300 s, retries 1-30, start period at most its default 120 s progress deadline); the tier `resources` go to the single service, or are split by `resources.services`. That core compiles at all is a proposal (open question 3 of #105). `working_dir`, `user`, `read_only` and the scratch volumes are accepted by the policy but the agent's current manifest has no field for them: they are recorded in `dropped` with reason `not_carried` and a warning.
316
+ **The normalized manifest** is what the agent receives for one instance: the compiled, validated spec. `NormalizedManifest` (JSON Schema `schema/normalized_manifest_v1.json`, which the agent repo vendors) has one service per Compose service with `name`, `image`, `ports`, `env`, `command`, `args`, `resources` (`requests`, `limits`), `replicas`, `health` and `scratch` (`[{"path": "/data"}]`, from each named or anonymous volume mount; the cluster gives each an `emptyDir`), in the shapes of the agent's `intent.go` (`scratch` is a core addition the agent vendors the schema for later). `compile_instance_spec(text, resources)` returns a `CompiledInstanceSpec`: the manifest, the keys it `dropped` and the warnings. Compose `entrypoint` becomes `command` and Compose `command` becomes `args`; `healthcheck` becomes an `exec` `health` (`interval`, `timeout`, `retries` and `start_period` map to `period_seconds`, `timeout_seconds`, `failure_threshold` and `start_period_seconds`) (bounded as the agent bounds them: period and timeout 1-300 s, retries 1-30, start period at most its default 120 s progress deadline); the tier `resources` go to the single service, or are split by `resources.services`. That core compiles at all is a proposal (open question 3 of #105). `working_dir`, `user` and `read_only` are accepted by the policy but the agent's current manifest has no field for them: they are recorded in `dropped` with reason `not_carried` and a warning.
304
317
 
305
318
  **The connectivity test is derived.** `validate_connectivity_test_exists` exempts an offering whose channels are all `container`, as it does an external app: the platform starts the services, waits for each one's `health` (or the default TCP check), fetches each entry expecting a success status, and shuts down. A seller may add a declarative `connectivity_test` Document (a `.json` file, `ProbesV1`, schema `schema/probes_v1.json`; a **proposal**), a list of probes run on top of the derived checks:
306
319
 
@@ -310,7 +323,7 @@ A seller can keep one file for local Docker and the platform: write `image` as `
310
323
 
311
324
  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`.
312
325
 
313
- Examples: `tests/example_data/hashicorp/services/echo` (one service, two tiers) and `tests/example_data/kadxy/services/weixin-ilink-gateway` (secrets, scratch state, outbound traffic; its image digest is a marked placeholder and its original `docker-compose.yaml` is a negative test).
326
+ 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).
314
327
 
315
328
  ### Request rules
316
329
 
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "unitysvc-core"
7
- version = "0.3.11"
7
+ version = "0.3.13"
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" }]
@@ -25,6 +25,7 @@ from __future__ import annotations
25
25
 
26
26
  import ipaddress
27
27
  import math
28
+ import posixpath
28
29
  import re
29
30
  import shlex
30
31
  from typing import Any, Literal
@@ -38,6 +39,7 @@ from .models.container import DNS_LABEL_RE, ContainerResources
38
39
  from .models.manifest import (
39
40
  ManifestHealth,
40
41
  ManifestResources,
42
+ ManifestScratch,
41
43
  ManifestService,
42
44
  NormalizedManifest,
43
45
  )
@@ -68,7 +70,7 @@ _HONORED = frozenset(
68
70
  _IGNORED = frozenset({"container_name", "restart", "labels", "logging", "networks", "expose", "profiles", "links"})
69
71
  # Rejected, with why (anything not listed anywhere is rejected too, as "not supported").
70
72
  _REJECTED: dict[str, str] = {
71
- "build": "an image is built elsewhere; give a digest-pinned `image`",
73
+ "build": "an image is built elsewhere; give an `image`",
72
74
  "privileged": "it removes the isolation instances run in",
73
75
  "cap_add": "it changes the container's isolation",
74
76
  "devices": "host devices are not available in a cluster",
@@ -80,7 +82,6 @@ _REJECTED: dict[str, str] = {
80
82
  "volumes_from": "volumes cannot be shared between services",
81
83
  "runtime": "the runtime is chosen by the platform",
82
84
  "extra_hosts": "it cannot work in a cluster",
83
- "env_file": "put the values in `environment`",
84
85
  "extends": "write the whole service in this file",
85
86
  "include": "write the whole file in one piece",
86
87
  "secrets": "secrets are bound by the platform, not by a Compose `secrets` section",
@@ -94,6 +95,9 @@ _HEALTHCHECK_KEYS = frozenset({"test", "interval", "timeout", "retries", "start_
94
95
  _DIGEST_RE = re.compile(r"@sha256:[0-9a-f]{64}$")
95
96
  _ENV_NAME_RE = re.compile(r"^[-._a-zA-Z][-._a-zA-Z0-9]*$")
96
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")
97
101
  _MAX_DURATION_SECONDS = 86400.0 # far above any bound the agent accepts; keeps float overflow out of ceil()
98
102
  _DURATION_RE = re.compile(r"^(?:\d+(?:\.\d+)?(?:us|ms|s|m|h))+$")
99
103
  _DURATION_PART_RE = re.compile(r"(\d+(?:\.\d+)?)(us|ms|s|m|h)")
@@ -277,8 +281,10 @@ def _parse(text: str) -> Any:
277
281
  class _Checker:
278
282
  """One pass over a parsed Compose document, collecting errors, warnings and the compiled services."""
279
283
 
280
- def __init__(self, channel: ContainerChannel | None) -> None:
284
+ def __init__(self, channel: ContainerChannel | None, overlay: Any = None) -> None:
281
285
  self.channel = channel
286
+ self.overlay = overlay
287
+ self._overlay_checked: dict[str, dict[str, str]] | None = None
282
288
  self.report = InstanceSpecReport()
283
289
  self.dropped: list[DroppedKey] = []
284
290
  self.services: list[ManifestService] = []
@@ -325,8 +331,37 @@ class _Checker:
325
331
  for name, service in services.items():
326
332
  self._service(str(name), service, volumes, used_volumes, declared_networks, service_networks, services)
327
333
  self._network_split(service_networks)
334
+ for service in self._overlay_env_services():
335
+ if str(service) not in services:
336
+ self.error(
337
+ "overlay_service",
338
+ f"environment.{service}",
339
+ f"{service!r} is not a service of the file; its services are {', '.join(map(str, services))}",
340
+ )
341
+ self._templates(doc)
328
342
  self._channel_context()
329
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
+
330
365
  def _top_volumes(self, volumes: Any) -> set[str]:
331
366
  if volumes is None:
332
367
  return set()
@@ -383,6 +418,16 @@ class _Checker:
383
418
  elif key.startswith("x-"):
384
419
  self.warn("ignored_key", f"{at}.{key}", "extension fields (x-*) are ignored")
385
420
  self.drop(name, key)
421
+ elif key == "env_file":
422
+ self.warn(
423
+ "ignored_key",
424
+ f"{at}.env_file",
425
+ "`env_file` is ignored: the values it would supply are missing from the instance, so the "
426
+ "service may not start. Provide them with `environment` on the container channel "
427
+ f"(environment.{name}.NAME)",
428
+ loud=True,
429
+ )
430
+ self.drop(name, "env_file")
386
431
  elif key == "deploy":
387
432
  self._deploy(name, service["deploy"])
388
433
  elif key in _REJECTED:
@@ -397,11 +442,12 @@ class _Checker:
397
442
  image = self._image(name, service.get("image"), "build" in service)
398
443
  ports = self._ports(name, service.get("ports"))
399
444
  self.ports[name] = ports
400
- env = self._environment(name, service.get("environment"))
445
+ overlay = self._overlay_env(name)
446
+ env = {**self._environment(name, service.get("environment"), frozenset(overlay)), **overlay}
401
447
  command = self._words(f"{at}.entrypoint", service.get("entrypoint"))
402
448
  args = self._words(f"{at}.command", service.get("command"))
403
449
  health = self._healthcheck(name, service.get("healthcheck"), ports)
404
- self._volumes(name, service.get("volumes"), volumes, used_volumes)
450
+ scratch = self._volumes(name, service.get("volumes"), volumes, used_volumes)
405
451
  self._depends_on(name, service.get("depends_on"), all_services)
406
452
  self._networks(name, service.get("networks"), declared_networks, service_networks)
407
453
  for key, check in (("working_dir", str), ("user", (str, int)), ("read_only", bool)):
@@ -425,6 +471,7 @@ class _Checker:
425
471
  command=command or None,
426
472
  args=args or None,
427
473
  health=health,
474
+ scratch=[ManifestScratch(path=path) for path in scratch] or None,
428
475
  )
429
476
  )
430
477
  except ValueError as exc:
@@ -457,7 +504,7 @@ class _Checker:
457
504
  at = f"services.{name}.image"
458
505
  if image is None:
459
506
  if not has_build:
460
- self.error("no_image", at, "a service needs `image`, pinned by digest (name:tag@sha256:...)")
507
+ self.error("no_image", at, "a service needs an `image` (name:tag, or name:tag@sha256:... to pin it)")
461
508
  return None
462
509
  if not isinstance(image, str) or not image:
463
510
  self.error("bad_value", at, "`image` must be a string")
@@ -465,14 +512,22 @@ class _Checker:
465
512
  if "$" in image:
466
513
  self.error("not_literal", at, "`image` must be written out in full: a variable cannot stand in the digest")
467
514
  return None
468
- if not _DIGEST_RE.search(image):
515
+ if image != image.strip() or any(c.isspace() for c in image):
516
+ self.error("bad_value", at, "`image` must not contain whitespace")
517
+ return None
518
+ if "@" in image and not _DIGEST_RE.search(image):
469
519
  self.error(
520
+ "bad_digest", at, f"`image` {image!r}: a digest must be written @sha256:<64 lowercase hex digits>"
521
+ )
522
+ return None
523
+ if not _DIGEST_RE.search(image):
524
+ self.warn(
470
525
  "unpinned_image",
471
526
  at,
472
- f"`image` {image!r} is not pinned by digest; write name:tag@sha256:<64 hex digits> "
473
- "(Compose runs the digest locally too, so one file serves local Docker and the platform)",
527
+ f"`image` {image!r} is not pinned by digest: the platform runs it as written and reports the digest "
528
+ "it pulled, and a moving tag can change at a restart. Write name:tag@sha256:<64 hex digits> to pin it "
529
+ "(Compose runs the digest locally too)",
474
530
  )
475
- return None
476
531
  return image
477
532
 
478
533
  def _ports(self, name: str, ports: Any) -> list[int]:
@@ -541,7 +596,52 @@ class _Checker:
541
596
  return None, None
542
597
  return number, published
543
598
 
544
- def _environment(self, name: str, environment: Any) -> dict[str, str]:
599
+ def _overlay(self, where: str = "environment") -> dict[str, dict[str, str]]:
600
+ """The channel's ``environment``, checked: ``{service: {NAME: "value"}}`` of strings."""
601
+ overlay = self.overlay
602
+ if overlay is None:
603
+ return {}
604
+ if not isinstance(overlay, dict):
605
+ self.error("bad_overlay", where, "must be a mapping of service name to a mapping of NAME to value")
606
+ return {}
607
+ result: dict[str, dict[str, str]] = {}
608
+ for service, values in overlay.items():
609
+ at = f"{where}.{service}"
610
+ if not isinstance(values, dict):
611
+ self.error("bad_overlay", at, "must be a mapping of NAME to a string value")
612
+ continue
613
+ clean: dict[str, str] = {}
614
+ for key, value in values.items():
615
+ if not isinstance(key, str) or not _ENV_NAME_RE.fullmatch(key):
616
+ self.error("bad_env", f"{at}.{key}", f"{key!r} is not a valid environment variable name")
617
+ elif not isinstance(value, str):
618
+ self.error("bad_env", f"{at}.{key}", "an environment value must be a string")
619
+ else:
620
+ clean[key] = value
621
+ if _INTERPOLATION_RE.search(value):
622
+ self.warn(
623
+ "interpolation",
624
+ f"{at}.{key}",
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 "
627
+ "(unitysvc-core#105, open 4)",
628
+ )
629
+ result[str(service)] = clean
630
+ return result
631
+
632
+ def _checked_overlay(self) -> dict[str, dict[str, str]]:
633
+ if self._overlay_checked is None:
634
+ self._overlay_checked = self._overlay()
635
+ return self._overlay_checked
636
+
637
+ def _overlay_env_services(self) -> list[str]:
638
+ return list(self._checked_overlay())
639
+
640
+ def _overlay_env(self, name: str) -> dict[str, str]:
641
+ return self._checked_overlay().get(name, {})
642
+
643
+ def _environment(self, name: str, environment: Any, supplied: frozenset[str] = frozenset()) -> dict[str, str]:
644
+ """The service's own environment; a bare variable the overlay (``supplied``) gives a value is no host lookup."""
545
645
  at = f"services.{name}.environment"
546
646
  pairs: list[tuple[str, Any]] = []
547
647
  if environment is None:
@@ -563,6 +663,8 @@ class _Checker:
563
663
  where = f"{at}.{key}"
564
664
  if not _ENV_NAME_RE.fullmatch(key):
565
665
  self.error("bad_env", where, f"{key!r} is not a valid environment variable name")
666
+ elif value is None and key in supplied:
667
+ continue
566
668
  elif value is None:
567
669
  self.error(
568
670
  "bad_env",
@@ -666,13 +768,15 @@ class _Checker:
666
768
  self.error("bad_value", at, str(exc).replace("\n", "; "))
667
769
  return None
668
770
 
669
- def _volumes(self, name: str, volumes: Any, declared: set[str], used: dict[str, str]) -> None:
771
+ def _volumes(self, name: str, volumes: Any, declared: set[str], used: dict[str, str]) -> list[str]:
772
+ """Check a service's mounts; return the scratch paths (each a named or anonymous volume mount)."""
670
773
  at = f"services.{name}.volumes"
774
+ scratch: list[str] = []
671
775
  if volumes is None:
672
- return
776
+ return scratch
673
777
  if not isinstance(volumes, list):
674
778
  self.error("bad_value", at, "`volumes` must be a list")
675
- return
779
+ return scratch
676
780
  for index, item in enumerate(volumes):
677
781
  where = f"{at}[{index}]"
678
782
  source: Any
@@ -720,15 +824,25 @@ class _Checker:
720
824
  "between services",
721
825
  )
722
826
  continue
827
+ target = posixpath.normpath(target)
828
+ if target.startswith("//"): # POSIX keeps exactly two leading slashes
829
+ target = "/" + target.lstrip("/")
830
+ if target == "/":
831
+ self.error("bad_value", where, "a volume cannot be mounted at the container's root")
832
+ continue
833
+ if target in scratch:
834
+ self.error("duplicate_mount", where, f"{target} is mounted twice in this service")
835
+ continue
836
+ scratch.append(target)
723
837
  label = f"volume {source!r}" if source else "an anonymous volume"
724
838
  self.warn(
725
839
  "scratch_volume",
726
840
  where,
727
- f"{label} at {target} becomes scratch space (emptyDir, counted in ephemeral-storage): its data does "
728
- "not survive a restart or a replacement of the instance",
841
+ f"{label} at {target} becomes scratch space (an emptyDir the instance gets at that path, counted in "
842
+ "ephemeral-storage): its data survives a container restart but not a replacement of the instance",
729
843
  loud=True,
730
844
  )
731
- self.drop(name, "volumes", "not_carried")
845
+ return scratch
732
846
 
733
847
  def _depends_on(self, name: str, depends_on: Any, all_services: dict[Any, Any]) -> None:
734
848
  at = f"services.{name}.depends_on"
@@ -820,8 +934,8 @@ class _Checker:
820
934
  )
821
935
 
822
936
 
823
- def _check(text: str, fmt: str, channel: ContainerChannel | None) -> _Checker:
824
- checker = _Checker(channel)
937
+ def _check(text: str, fmt: str, channel: ContainerChannel | None, overlay: Any = None) -> _Checker:
938
+ checker = _Checker(channel, overlay)
825
939
  if fmt not in SUPPORTED_FORMATS:
826
940
  checker.error("unsupported_format", "", unsupported_format_message(fmt))
827
941
  return checker
@@ -854,21 +968,30 @@ def _check(text: str, fmt: str, channel: ContainerChannel | None) -> _Checker:
854
968
 
855
969
 
856
970
  def validate_instance_spec(
857
- text: str, *, format: str = DEFAULT_FORMAT, channel: ContainerChannel | None = None
971
+ text: str,
972
+ *,
973
+ format: str = DEFAULT_FORMAT,
974
+ channel: ContainerChannel | None = None,
975
+ # (the channel's ``environment`` is read from ``channel``)
858
976
  ) -> InstanceSpecReport:
859
977
  """Validate an instance spec's content, with the channel that runs it when known.
860
978
 
861
979
  Checks the Compose allowlist and the static rules (literal digests,
862
980
  container-side ports, health checks, volumes, networks, service names). With
863
981
  ``channel``, also that every entry targets a declared service and port and
864
- that ``resources.services`` names the spec's services. Never raises on bad
865
- 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.
866
985
  """
867
- return _check(text, format, channel).report
986
+ return _check(text, format, channel, channel.environment if channel else None).report
868
987
 
869
988
 
870
989
  def compile_instance_spec(
871
- text: str, resources: ContainerResources, *, format: str = DEFAULT_FORMAT
990
+ text: str,
991
+ resources: ContainerResources,
992
+ *,
993
+ format: str = DEFAULT_FORMAT,
994
+ environment: dict[str, dict[str, str]] | None = None,
872
995
  ) -> CompiledInstanceSpec:
873
996
  """Compile a valid spec and the channel's ``resources`` into the agent's normalized manifest.
874
997
 
@@ -876,10 +999,13 @@ def compile_instance_spec(
876
999
  are split by ``resources.services``. Raises :class:`InstanceSpecError`
877
1000
  (carrying the report) if the spec is not valid for these resources.
878
1001
 
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.
1004
+
879
1005
  PROPOSAL (unitysvc-core#105, open 3): that core compiles, rather than the
880
1006
  agent, is not decided.
881
1007
  """
882
- checker = _check(text, format, None)
1008
+ checker = _check(text, format, None, environment)
883
1009
  report = checker.report
884
1010
  names = list(checker.ports)
885
1011
  split = resources.services
@@ -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,6 +420,29 @@ 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":
@@ -80,4 +80,9 @@ class DocumentData(BaseModel):
80
80
  raise ValueError(f"instance_spec meta.source {problem}")
81
81
  if "sha256" in meta and (problem := sha256_error(meta["sha256"])):
82
82
  raise ValueError(f"instance_spec meta.sha256 {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
+ )
83
88
  return self
@@ -12,12 +12,15 @@ Deliberate differences from ``intent.go`` (listed in the PR that added it):
12
12
 
13
13
  * the agent's ``cpu`` and ``memory`` shorthand (request = limit) is not
14
14
  modelled: core always writes the general ``resources`` form;
15
+ * ``scratch`` (temporary storage mounts) is a core addition the agent does not decode yet; the agent repo
16
+ vendors this schema when it adds it (unitysvc/unitysvc-core#107);
15
17
  * the agent's ``Entry`` (with a ``hostname`` central assigns) is not part of the
16
18
  manifest; it travels beside it in the intent.
17
19
  """
18
20
 
19
21
  from __future__ import annotations
20
22
 
23
+ import posixpath
21
24
  from typing import Literal
22
25
 
23
26
  from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
@@ -76,6 +79,25 @@ class ManifestHealth(BaseModel):
76
79
  return self
77
80
 
78
81
 
82
+ class ManifestScratch(BaseModel):
83
+ """A path in the container that is temporary storage (from a Compose named or anonymous volume mount).
84
+
85
+ The cluster gives it an ``emptyDir``: the path exists and is writable, its data survives a container
86
+ restart but not a replacement of the instance, and it counts against the service's ephemeral storage.
87
+ """
88
+
89
+ model_config = ConfigDict(extra="forbid")
90
+
91
+ path: str = Field(pattern=r"^/.", description="Normalized absolute path inside the container, below /")
92
+
93
+ @field_validator("path")
94
+ @classmethod
95
+ def _normalized(cls, value: str) -> str:
96
+ if posixpath.normpath(value) != value or value == "/" or value.startswith("//"):
97
+ raise ValueError("path must be normalized (no '..', '.', '//' or trailing '/') and below /")
98
+ return value
99
+
100
+
79
101
  class ManifestService(BaseModel):
80
102
  """One container of an instance (the agent's ``Service``)."""
81
103
 
@@ -90,6 +112,9 @@ class ManifestService(BaseModel):
90
112
  resources: ManifestResources | None = None
91
113
  replicas: int | None = Field(default=None, ge=0)
92
114
  health: ManifestHealth | None = None
115
+ scratch: list[ManifestScratch] | None = Field(
116
+ default=None, description="Temporary storage mounted in the container (an emptyDir each)"
117
+ )
93
118
 
94
119
  @field_validator("name")
95
120
  @classmethod
@@ -108,6 +133,15 @@ class ManifestService(BaseModel):
108
133
  raise ValueError("ports must be distinct")
109
134
  return value
110
135
 
136
+ @field_validator("scratch")
137
+ @classmethod
138
+ def _scratch(cls, value: list[ManifestScratch] | None) -> list[ManifestScratch] | None:
139
+ if value is not None:
140
+ paths = [s.path for s in value]
141
+ if len(set(paths)) != len(paths):
142
+ raise ValueError("scratch paths must be distinct")
143
+ return value
144
+
111
145
  @model_validator(mode="after")
112
146
  def _check_health_port(self) -> ManifestService:
113
147
  health = self.health