unitysvc-core 0.3.11__tar.gz → 0.3.12__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.12}/PKG-INFO +18 -7
  2. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/README.md +17 -6
  3. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/pyproject.toml +1 -1
  4. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/instance_spec.py +147 -25
  5. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/models/documents.py +3 -0
  6. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/models/manifest.py +34 -0
  7. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/schema/normalized_manifest_v1.json +33 -0
  8. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/validator.py +3 -1
  9. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12/src/unitysvc_core.egg-info}/PKG-INFO +18 -7
  10. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/tests/test_container.py +244 -17
  11. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/LICENSE +0 -0
  12. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/setup.cfg +0 -0
  13. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/__init__.py +0 -0
  14. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/grants.py +0 -0
  15. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/models/__init__.py +0 -0
  16. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/models/base.py +0 -0
  17. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/models/channel.py +0 -0
  18. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/models/container.py +0 -0
  19. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/models/listing_data.py +0 -0
  20. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/models/listing_v1.py +0 -0
  21. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/models/offering_data.py +0 -0
  22. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/models/offering_v1.py +0 -0
  23. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/models/pricing.py +0 -0
  24. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/models/probes.py +0 -0
  25. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/models/promotion_data.py +0 -0
  26. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/models/provider_data.py +0 -0
  27. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/models/provider_v1.py +0 -0
  28. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/models/service.py +0 -0
  29. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/models/service_group_data.py +0 -0
  30. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/models/validators.py +0 -0
  31. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/parameter_usage.py +0 -0
  32. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/py.typed +0 -0
  33. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/schema/base.json +0 -0
  34. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/schema/listing_v1.json +0 -0
  35. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/schema/offering_v1.json +0 -0
  36. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/schema/probes_v1.json +0 -0
  37. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/schema/promotion_v1.json +0 -0
  38. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/schema/provider_v1.json +0 -0
  39. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/schema/service_group_v1.json +0 -0
  40. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/utils.py +0 -0
  41. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core.egg-info/SOURCES.txt +0 -0
  42. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core.egg-info/dependency_links.txt +0 -0
  43. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core.egg-info/requires.txt +0 -0
  44. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core.egg-info/top_level.txt +0 -0
  45. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/tests/test_access_interface_routing.py +0 -0
  46. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/tests/test_canonical_interfaces.py +0 -0
  47. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/tests/test_channel.py +0 -0
  48. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/tests/test_documents.py +0 -0
  49. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/tests/test_effective_price.py +0 -0
  50. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/tests/test_external_apps.py +0 -0
  51. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/tests/test_grants.py +0 -0
  52. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/tests/test_hidden_path_skip.py +0 -0
  53. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/tests/test_listing_audience.py +0 -0
  54. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/tests/test_offering_data.py +0 -0
  55. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/tests/test_parameter_usage.py +0 -0
  56. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/tests/test_pricing.py +0 -0
  57. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/tests/test_provider_account_rate_limits.py +0 -0
  58. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/tests/test_request_rules.py +0 -0
  59. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/tests/test_service_group.py +0 -0
  60. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/tests/test_service_status.py +0 -0
  61. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/tests/test_utils.py +0 -0
  62. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/tests/test_validate_service.py +0 -0
  63. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/tests/test_validator.py +0 -0
  64. {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/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.12
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,27 @@ 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 `meta.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.** 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.
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
+ "environment": {"gateway": {"API_KEY": "${UNITYSVC_INSTANCE_API_KEY}"}}}
345
+ }}
346
+ ```
336
347
 
337
348
  **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
349
 
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.
350
+ **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
351
 
341
352
  **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
353
 
@@ -346,7 +357,7 @@ A seller can keep one file for local Docker and the platform: write `image` as `
346
357
 
347
358
  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
359
 
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).
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).
350
361
 
351
362
  ### Request rules
352
363
 
@@ -291,16 +291,27 @@ 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 `meta.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.** 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.
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
+ "environment": {"gateway": {"API_KEY": "${UNITYSVC_INSTANCE_API_KEY}"}}}
309
+ }}
310
+ ```
300
311
 
301
312
  **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
313
 
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.
314
+ **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
315
 
305
316
  **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
317
 
@@ -310,7 +321,7 @@ A seller can keep one file for local Docker and the platform: write `image` as `
310
321
 
311
322
  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
323
 
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).
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).
314
325
 
315
326
  ### Request rules
316
327
 
@@ -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.12"
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",
@@ -204,6 +205,26 @@ def snapshot_url_error(url: Any) -> str | None:
204
205
  return None
205
206
 
206
207
 
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
+
207
228
  def sha256_error(value: Any) -> str | None:
208
229
  if not isinstance(value, str) or not _SHA256_RE.fullmatch(value):
209
230
  return "must be 64 lowercase hexadecimal characters"
@@ -277,8 +298,10 @@ def _parse(text: str) -> Any:
277
298
  class _Checker:
278
299
  """One pass over a parsed Compose document, collecting errors, warnings and the compiled services."""
279
300
 
280
- def __init__(self, channel: ContainerChannel | None) -> None:
301
+ def __init__(self, channel: ContainerChannel | None, overlay: Any = None) -> None:
281
302
  self.channel = channel
303
+ self.overlay = overlay
304
+ self._overlay_checked: dict[str, dict[str, str]] | None = None
282
305
  self.report = InstanceSpecReport()
283
306
  self.dropped: list[DroppedKey] = []
284
307
  self.services: list[ManifestService] = []
@@ -325,6 +348,13 @@ class _Checker:
325
348
  for name, service in services.items():
326
349
  self._service(str(name), service, volumes, used_volumes, declared_networks, service_networks, services)
327
350
  self._network_split(service_networks)
351
+ for service in self._overlay_env_services():
352
+ if str(service) not in services:
353
+ self.error(
354
+ "overlay_service",
355
+ f"meta.environment.{service}",
356
+ f"{service!r} is not a service of the file; its services are {', '.join(map(str, services))}",
357
+ )
328
358
  self._channel_context()
329
359
 
330
360
  def _top_volumes(self, volumes: Any) -> set[str]:
@@ -383,6 +413,16 @@ class _Checker:
383
413
  elif key.startswith("x-"):
384
414
  self.warn("ignored_key", f"{at}.{key}", "extension fields (x-*) are ignored")
385
415
  self.drop(name, key)
416
+ elif key == "env_file":
417
+ self.warn(
418
+ "ignored_key",
419
+ f"{at}.env_file",
420
+ "`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)",
423
+ loud=True,
424
+ )
425
+ self.drop(name, "env_file")
386
426
  elif key == "deploy":
387
427
  self._deploy(name, service["deploy"])
388
428
  elif key in _REJECTED:
@@ -397,11 +437,12 @@ class _Checker:
397
437
  image = self._image(name, service.get("image"), "build" in service)
398
438
  ports = self._ports(name, service.get("ports"))
399
439
  self.ports[name] = ports
400
- env = self._environment(name, service.get("environment"))
440
+ overlay = self._overlay_env(name)
441
+ env = {**self._environment(name, service.get("environment"), frozenset(overlay)), **overlay}
401
442
  command = self._words(f"{at}.entrypoint", service.get("entrypoint"))
402
443
  args = self._words(f"{at}.command", service.get("command"))
403
444
  health = self._healthcheck(name, service.get("healthcheck"), ports)
404
- self._volumes(name, service.get("volumes"), volumes, used_volumes)
445
+ scratch = self._volumes(name, service.get("volumes"), volumes, used_volumes)
405
446
  self._depends_on(name, service.get("depends_on"), all_services)
406
447
  self._networks(name, service.get("networks"), declared_networks, service_networks)
407
448
  for key, check in (("working_dir", str), ("user", (str, int)), ("read_only", bool)):
@@ -425,6 +466,7 @@ class _Checker:
425
466
  command=command or None,
426
467
  args=args or None,
427
468
  health=health,
469
+ scratch=[ManifestScratch(path=path) for path in scratch] or None,
428
470
  )
429
471
  )
430
472
  except ValueError as exc:
@@ -457,7 +499,7 @@ class _Checker:
457
499
  at = f"services.{name}.image"
458
500
  if image is None:
459
501
  if not has_build:
460
- self.error("no_image", at, "a service needs `image`, pinned by digest (name:tag@sha256:...)")
502
+ self.error("no_image", at, "a service needs an `image` (name:tag, or name:tag@sha256:... to pin it)")
461
503
  return None
462
504
  if not isinstance(image, str) or not image:
463
505
  self.error("bad_value", at, "`image` must be a string")
@@ -465,14 +507,22 @@ class _Checker:
465
507
  if "$" in image:
466
508
  self.error("not_literal", at, "`image` must be written out in full: a variable cannot stand in the digest")
467
509
  return None
468
- if not _DIGEST_RE.search(image):
510
+ if image != image.strip() or any(c.isspace() for c in image):
511
+ self.error("bad_value", at, "`image` must not contain whitespace")
512
+ return None
513
+ if "@" in image and not _DIGEST_RE.search(image):
469
514
  self.error(
515
+ "bad_digest", at, f"`image` {image!r}: a digest must be written @sha256:<64 lowercase hex digits>"
516
+ )
517
+ return None
518
+ if not _DIGEST_RE.search(image):
519
+ self.warn(
470
520
  "unpinned_image",
471
521
  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)",
522
+ f"`image` {image!r} is not pinned by digest: the platform runs it as written and reports the digest "
523
+ "it pulled, and a moving tag can change at a restart. Write name:tag@sha256:<64 hex digits> to pin it "
524
+ "(Compose runs the digest locally too)",
474
525
  )
475
- return None
476
526
  return image
477
527
 
478
528
  def _ports(self, name: str, ports: Any) -> list[int]:
@@ -541,7 +591,52 @@ class _Checker:
541
591
  return None, None
542
592
  return number, published
543
593
 
544
- def _environment(self, name: str, environment: Any) -> dict[str, str]:
594
+ def _overlay(self, where: str = "meta.environment") -> dict[str, dict[str, str]]:
595
+ """The ``meta.environment`` overlay, checked: ``{service: {NAME: "value"}}`` of strings."""
596
+ overlay = self.overlay
597
+ if overlay is None:
598
+ return {}
599
+ if not isinstance(overlay, dict):
600
+ self.error("bad_overlay", where, "must be a mapping of service name to a mapping of NAME to value")
601
+ return {}
602
+ result: dict[str, dict[str, str]] = {}
603
+ for service, values in overlay.items():
604
+ at = f"{where}.{service}"
605
+ if not isinstance(values, dict):
606
+ self.error("bad_overlay", at, "must be a mapping of NAME to a string value")
607
+ continue
608
+ clean: dict[str, str] = {}
609
+ for key, value in values.items():
610
+ if not isinstance(key, str) or not _ENV_NAME_RE.fullmatch(key):
611
+ self.error("bad_env", f"{at}.{key}", f"{key!r} is not a valid environment variable name")
612
+ elif not isinstance(value, str):
613
+ self.error("bad_env", f"{at}.{key}", "an environment value must be a string")
614
+ else:
615
+ clean[key] = value
616
+ if _INTERPOLATION_RE.search(value):
617
+ self.warn(
618
+ "interpolation",
619
+ 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 "
622
+ "(unitysvc-core#105, open 4)",
623
+ )
624
+ result[str(service)] = clean
625
+ return result
626
+
627
+ def _checked_overlay(self) -> dict[str, dict[str, str]]:
628
+ if self._overlay_checked is None:
629
+ self._overlay_checked = self._overlay()
630
+ return self._overlay_checked
631
+
632
+ def _overlay_env_services(self) -> list[str]:
633
+ return list(self._checked_overlay())
634
+
635
+ def _overlay_env(self, name: str) -> dict[str, str]:
636
+ return self._checked_overlay().get(name, {})
637
+
638
+ def _environment(self, name: str, environment: Any, supplied: frozenset[str] = frozenset()) -> dict[str, str]:
639
+ """The service's own environment; a bare variable the overlay (``supplied``) gives a value is no host lookup."""
545
640
  at = f"services.{name}.environment"
546
641
  pairs: list[tuple[str, Any]] = []
547
642
  if environment is None:
@@ -563,6 +658,8 @@ class _Checker:
563
658
  where = f"{at}.{key}"
564
659
  if not _ENV_NAME_RE.fullmatch(key):
565
660
  self.error("bad_env", where, f"{key!r} is not a valid environment variable name")
661
+ elif value is None and key in supplied:
662
+ continue
566
663
  elif value is None:
567
664
  self.error(
568
665
  "bad_env",
@@ -666,13 +763,15 @@ class _Checker:
666
763
  self.error("bad_value", at, str(exc).replace("\n", "; "))
667
764
  return None
668
765
 
669
- def _volumes(self, name: str, volumes: Any, declared: set[str], used: dict[str, str]) -> None:
766
+ def _volumes(self, name: str, volumes: Any, declared: set[str], used: dict[str, str]) -> list[str]:
767
+ """Check a service's mounts; return the scratch paths (each a named or anonymous volume mount)."""
670
768
  at = f"services.{name}.volumes"
769
+ scratch: list[str] = []
671
770
  if volumes is None:
672
- return
771
+ return scratch
673
772
  if not isinstance(volumes, list):
674
773
  self.error("bad_value", at, "`volumes` must be a list")
675
- return
774
+ return scratch
676
775
  for index, item in enumerate(volumes):
677
776
  where = f"{at}[{index}]"
678
777
  source: Any
@@ -720,15 +819,25 @@ class _Checker:
720
819
  "between services",
721
820
  )
722
821
  continue
822
+ target = posixpath.normpath(target)
823
+ if target.startswith("//"): # POSIX keeps exactly two leading slashes
824
+ target = "/" + target.lstrip("/")
825
+ if target == "/":
826
+ self.error("bad_value", where, "a volume cannot be mounted at the container's root")
827
+ continue
828
+ if target in scratch:
829
+ self.error("duplicate_mount", where, f"{target} is mounted twice in this service")
830
+ continue
831
+ scratch.append(target)
723
832
  label = f"volume {source!r}" if source else "an anonymous volume"
724
833
  self.warn(
725
834
  "scratch_volume",
726
835
  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",
836
+ f"{label} at {target} becomes scratch space (an emptyDir the instance gets at that path, counted in "
837
+ "ephemeral-storage): its data survives a container restart but not a replacement of the instance",
729
838
  loud=True,
730
839
  )
731
- self.drop(name, "volumes", "not_carried")
840
+ return scratch
732
841
 
733
842
  def _depends_on(self, name: str, depends_on: Any, all_services: dict[Any, Any]) -> None:
734
843
  at = f"services.{name}.depends_on"
@@ -820,8 +929,8 @@ class _Checker:
820
929
  )
821
930
 
822
931
 
823
- def _check(text: str, fmt: str, channel: ContainerChannel | None) -> _Checker:
824
- checker = _Checker(channel)
932
+ def _check(text: str, fmt: str, channel: ContainerChannel | None, overlay: Any = None) -> _Checker:
933
+ checker = _Checker(channel, overlay)
825
934
  if fmt not in SUPPORTED_FORMATS:
826
935
  checker.error("unsupported_format", "", unsupported_format_message(fmt))
827
936
  return checker
@@ -854,21 +963,30 @@ def _check(text: str, fmt: str, channel: ContainerChannel | None) -> _Checker:
854
963
 
855
964
 
856
965
  def validate_instance_spec(
857
- text: str, *, format: str = DEFAULT_FORMAT, channel: ContainerChannel | None = None
966
+ text: str,
967
+ *,
968
+ format: str = DEFAULT_FORMAT,
969
+ channel: ContainerChannel | None = None,
970
+ environment: dict[str, dict[str, str]] | None = None,
858
971
  ) -> InstanceSpecReport:
859
972
  """Validate an instance spec's content, with the channel that runs it when known.
860
973
 
861
974
  Checks the Compose allowlist and the static rules (literal digests,
862
975
  container-side ports, health checks, volumes, networks, service names). With
863
976
  ``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.
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.
866
980
  """
867
- return _check(text, format, channel).report
981
+ return _check(text, format, channel, environment).report
868
982
 
869
983
 
870
984
  def compile_instance_spec(
871
- text: str, resources: ContainerResources, *, format: str = DEFAULT_FORMAT
985
+ text: str,
986
+ resources: ContainerResources,
987
+ *,
988
+ format: str = DEFAULT_FORMAT,
989
+ environment: dict[str, dict[str, str]] | None = None,
872
990
  ) -> CompiledInstanceSpec:
873
991
  """Compile a valid spec and the channel's ``resources`` into the agent's normalized manifest.
874
992
 
@@ -876,10 +994,14 @@ def compile_instance_spec(
876
994
  are split by ``resources.services``. Raises :class:`InstanceSpecError`
877
995
  (carrying the report) if the spec is not valid for these resources.
878
996
 
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.
1000
+
879
1001
  PROPOSAL (unitysvc-core#105, open 3): that core compiles, rather than the
880
1002
  agent, is not decided.
881
1003
  """
882
- checker = _check(text, format, None)
1004
+ checker = _check(text, format, None, environment)
883
1005
  report = checker.report
884
1006
  names = list(checker.ports)
885
1007
  split = resources.services
@@ -62,6 +62,7 @@ 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,
65
66
  instance_spec_format,
66
67
  sha256_error,
67
68
  snapshot_url_error,
@@ -80,4 +81,6 @@ class DocumentData(BaseModel):
80
81
  raise ValueError(f"instance_spec meta.source {problem}")
81
82
  if "sha256" in meta and (problem := sha256_error(meta["sha256"])):
82
83
  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
86
  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
@@ -169,6 +169,23 @@
169
169
  "title": "ManifestResources",
170
170
  "type": "object"
171
171
  },
172
+ "ManifestScratch": {
173
+ "additionalProperties": false,
174
+ "description": "A path in the container that is temporary storage (from a Compose named or anonymous volume mount).\n\nThe cluster gives it an ``emptyDir``: the path exists and is writable, its data survives a container\nrestart but not a replacement of the instance, and it counts against the service's ephemeral storage.",
175
+ "properties": {
176
+ "path": {
177
+ "description": "Normalized absolute path inside the container, below /",
178
+ "pattern": "^/.",
179
+ "title": "Path",
180
+ "type": "string"
181
+ }
182
+ },
183
+ "required": [
184
+ "path"
185
+ ],
186
+ "title": "ManifestScratch",
187
+ "type": "object"
188
+ },
172
189
  "ManifestService": {
173
190
  "additionalProperties": false,
174
191
  "description": "One container of an instance (the agent's ``Service``).",
@@ -281,6 +298,22 @@
281
298
  }
282
299
  ],
283
300
  "default": null
301
+ },
302
+ "scratch": {
303
+ "anyOf": [
304
+ {
305
+ "items": {
306
+ "$ref": "#/$defs/ManifestScratch"
307
+ },
308
+ "type": "array"
309
+ },
310
+ {
311
+ "type": "null"
312
+ }
313
+ ],
314
+ "default": null,
315
+ "description": "Temporary storage mounted in the container (an emptyDir each)",
316
+ "title": "Scratch"
284
317
  }
285
318
  },
286
319
  "required": [
@@ -768,7 +768,9 @@ 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(text, format=fmt, channel=channel)
771
+ report = validate_instance_spec(
772
+ text, format=fmt, channel=channel, environment=(doc.get("meta") or {}).get("environment")
773
+ )
772
774
  errors.extend(f"{at}.instance_spec ({title!r}): {issue}" for issue in report.errors)
773
775
  warnings.extend(issue.model_copy(update={"path": f"{at}: {issue.path}"}) for issue in report.warnings)
774
776
  return errors, warnings
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: unitysvc-core
3
- Version: 0.3.11
3
+ Version: 0.3.12
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,27 @@ 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 `meta.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.** 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.
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
+ "environment": {"gateway": {"API_KEY": "${UNITYSVC_INSTANCE_API_KEY}"}}}
345
+ }}
346
+ ```
336
347
 
337
348
  **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
349
 
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.
350
+ **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
351
 
341
352
  **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
353
 
@@ -346,7 +357,7 @@ A seller can keep one file for local Docker and the platform: write `image` as `
346
357
 
347
358
  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
359
 
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).
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).
350
361
 
351
362
  ### Request rules
352
363
 
@@ -31,6 +31,7 @@ ROOT = Path(__file__).parent
31
31
  EXAMPLES = ROOT / "example_data"
32
32
  ECHO = EXAMPLES / "hashicorp" / "services" / "echo"
33
33
  WEIXIN = EXAMPLES / "kadxy" / "services" / "weixin-ilink-gateway"
34
+ WEIXIN_UPSTREAM = EXAMPLES / "kadxy" / "services" / "weixin-ilink-gateway-upstream"
34
35
  FIXTURES = ROOT / "fixtures"
35
36
  SCHEMA_DIR = ROOT.parent / "src" / "unitysvc_core" / "schema"
36
37
  DIGEST = "@sha256:" + "a" * 64
@@ -438,7 +439,22 @@ class TestLoudWarnings:
438
439
  assert report.ok, report.errors
439
440
  scratch = [w for w in report.warnings if w.code == "scratch_volume"]
440
441
  assert len(scratch) == 2 and all(w.loud for w in scratch)
441
- assert "does not survive a restart" in scratch[0].message
442
+ assert "survives a container restart" in scratch[0].message
443
+ manifest = compile_instance_spec(text, ContainerResources.model_validate({"limits": LIMITS})).manifest
444
+ assert [s.path for s in manifest.services[0].scratch or []] == ["/data", "/cache"]
445
+ assert not any(
446
+ d.key == "volumes"
447
+ for d in compile_instance_spec(text, ContainerResources.model_validate({"limits": LIMITS})).dropped
448
+ )
449
+
450
+ def test_a_path_mounted_twice_is_an_error(self) -> None:
451
+ text = yaml.safe_dump(
452
+ {
453
+ "services": {"web": {"image": f"web{DIGEST}", "volumes": ["a:/data", "b:/data"]}},
454
+ "volumes": {"a": {}, "b": {}},
455
+ }
456
+ )
457
+ assert "duplicate_mount" in _codes(validate_instance_spec(text))
442
458
 
443
459
 
444
460
  class TestReject:
@@ -457,7 +473,6 @@ class TestReject:
457
473
  ("volumes_from", ["x"]),
458
474
  ("runtime", "nvidia"),
459
475
  ("extra_hosts", ["a:1.1.1.1"]),
460
- ("env_file", ".env"),
461
476
  ("extends", {"service": "x"}),
462
477
  ("mem_limit", "1g"),
463
478
  ("secrets", ["s"]),
@@ -481,11 +496,33 @@ class TestReject:
481
496
 
482
497
  @pytest.mark.parametrize(
483
498
  "image",
484
- ["nginx", "nginx:latest", "nginx:1.27", "nginx@sha256:abc", "nginx@sha256:" + "A" * 64, "nginx${TAG}" + DIGEST],
499
+ ["nginx@sha256:abc", "nginx@sha256:" + "A" * 64, "nginx${TAG}" + DIGEST, "nginx latest", "nginx:1@sha256:"],
485
500
  )
486
- def test_images_must_be_pinned_by_a_literal_digest(self, image: str) -> None:
501
+ def test_a_written_digest_must_be_a_literal_valid_one(self, image: str) -> None:
487
502
  assert not validate_instance_spec(_compose(image=image)).ok
488
503
 
504
+ @pytest.mark.parametrize("image", ["nginx", "nginx:latest", "nginx:1.27", "ghcr.io/o/app:stable"])
505
+ def test_a_tag_or_no_tag_is_accepted_with_a_note(self, image: str) -> None:
506
+ report = validate_instance_spec(_compose(image=image))
507
+ assert report.ok, report.errors
508
+ note = next(w for w in report.warnings if w.code == "unpinned_image")
509
+ assert not note.loud and "runs it as written" in note.message and "reports the digest" in note.message
510
+ assert (
511
+ compile_instance_spec(_compose(image=image), ContainerResources.model_validate({"limits": LIMITS}))
512
+ .manifest.services[0]
513
+ .image
514
+ == image
515
+ )
516
+
517
+ def test_a_digest_written_by_the_seller_is_honored_as_written(self) -> None:
518
+ image = "ghcr.io/o/app:v1" + DIGEST
519
+ report = validate_instance_spec(_compose(image=image))
520
+ assert report.ok and "unpinned_image" not in _codes(report, "warnings")
521
+ manifest = compile_instance_spec(
522
+ _compose(image=image), ContainerResources.model_validate({"limits": LIMITS})
523
+ ).manifest
524
+ assert manifest.services[0].image == image
525
+
489
526
  def test_a_tag_with_a_digest_is_accepted(self) -> None:
490
527
  assert validate_instance_spec(_compose(image="ghcr.io/o/app:v1.2.3" + DIGEST)).ok
491
528
 
@@ -778,7 +815,6 @@ class TestCompileGolden:
778
815
  compiled = compile_instance_spec((WEIXIN / "compose.yaml").read_text(), channel.resources)
779
816
  assert {(d.service, d.key, d.reason) for d in compiled.dropped} == {
780
817
  ("gateway", "deploy.resources", "ignored"),
781
- ("gateway", "volumes", "not_carried"),
782
818
  }
783
819
  assert any(w.loud for w in compiled.warnings)
784
820
 
@@ -801,8 +837,10 @@ class TestCompileGolden:
801
837
 
802
838
  def test_an_invalid_spec_does_not_compile(self) -> None:
803
839
  with pytest.raises(InstanceSpecError) as caught:
804
- compile_instance_spec(_compose(image="nginx:latest"), ContainerResources.model_validate({"limits": LIMITS}))
805
- assert "unpinned_image" in {e.code for e in caught.value.report.errors}
840
+ compile_instance_spec(
841
+ _compose(image="nginx@sha256:abc"), ContainerResources.model_validate({"limits": LIMITS})
842
+ )
843
+ assert "bad_digest" in {e.code for e in caught.value.report.errors}
806
844
 
807
845
 
808
846
  # --- the examples through the validator --------------------------------------------------------
@@ -843,20 +881,20 @@ class TestExamples:
843
881
  assert any(w.code == "scratch_volume" and w.loud for w in warnings)
844
882
  assert any(w.code == "interpolation" for w in warnings)
845
883
 
846
- def test_the_original_weixin_compose_is_rejected(self) -> None:
847
- report = validate_instance_spec((WEIXIN / "docker-compose.original.yaml").read_text())
848
- assert {"unpinned_image", "rejected_key"} <= _codes(report)
849
- assert any(e.path == "services.gateway.env_file" for e in report.errors)
850
- assert any(e.path == "services.gateway.image" for e in report.errors)
851
- assert "host_port" in _codes(report, "warnings")
884
+ def test_the_upstream_weixin_compose_is_accepted_with_loud_warnings(self) -> None:
885
+ report = validate_instance_spec((WEIXIN_UPSTREAM / "upstream-compose.yaml").read_text())
886
+ assert report.ok, report.errors
887
+ loud = {w.code for w in report.warnings if w.loud}
888
+ assert {"ignored_key", "scratch_volume"} <= loud
889
+ 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
891
+ assert "unpinned_image" in _codes(report, "warnings")
852
892
 
853
893
  def test_a_bad_spec_fails_the_offering(self, validator: DataValidator, tmp_path: Path) -> None:
854
- (tmp_path / "compose.yaml").write_text((WEIXIN / "docker-compose.original.yaml").read_text())
894
+ (tmp_path / "compose.yaml").write_text(_compose(privileged=True))
855
895
  offering = json.loads((ECHO / "offering.json").read_text())
856
896
  errors = validator.validate_service(offering=offering, service_dir=tmp_path)["offering"]
857
- assert any("env_file" in e for e in errors) and any(
858
- "upstream_access_config.base.instance_spec" in e for e in errors
859
- )
897
+ assert any("upstream_access_config.base.instance_spec" in e and "privileged" in e for e in errors)
860
898
 
861
899
  def test_entry_and_split_errors_surface_in_the_offering(self, validator: DataValidator) -> None:
862
900
  offering = json.loads((ECHO / "offering.json").read_text())
@@ -1186,3 +1224,192 @@ class TestSnapshotDocument:
1186
1224
  assert _errors(validator, offering) == []
1187
1225
  doc["meta"]["sha256"] = "0" * 64
1188
1226
  assert any("does not match meta.sha256" in e for e in _errors(validator, offering))
1227
+
1228
+
1229
+ # --- addenda of #107: env_file, meta.environment, scratch ---------------------------------------------
1230
+
1231
+
1232
+ def _resources() -> ContainerResources:
1233
+ return ContainerResources.model_validate({"limits": LIMITS})
1234
+
1235
+
1236
+ class TestEnvFile:
1237
+ def test_env_file_is_ignored_loudly_not_rejected(self) -> None:
1238
+ report = validate_instance_spec(_compose(env_file=".env"))
1239
+ assert report.ok, report.errors
1240
+ warning = next(w for w in report.warnings if w.path == "services.web.env_file")
1241
+ assert warning.code == "ignored_key" and warning.loud
1242
+ assert "missing" in warning.message and "meta.environment" in warning.message
1243
+ compiled = compile_instance_spec(_compose(env_file=".env"), _resources())
1244
+ assert ("web", "env_file", "ignored") in {(d.service, d.key, d.reason) for d in compiled.dropped}
1245
+
1246
+
1247
+ class TestEnvironmentOverlay:
1248
+ def compose(self) -> str:
1249
+ return _compose(environment={"A": "file", "KEEP": "k"})
1250
+
1251
+ def test_the_overlay_overrides_and_adds(self) -> None:
1252
+ overlay = {"web": {"A": "overlay", "B": "new"}}
1253
+ env = compile_instance_spec(self.compose(), _resources(), environment=overlay).manifest.services[0].env
1254
+ assert env == {"A": "overlay", "KEEP": "k", "B": "new"}
1255
+
1256
+ def test_the_file_is_not_edited_and_no_overlay_is_the_file(self) -> None:
1257
+ text = self.compose()
1258
+ assert compile_instance_spec(text, _resources()).manifest.services[0].env == {"A": "file", "KEEP": "k"}
1259
+ assert text == self.compose()
1260
+
1261
+ def test_it_supplies_what_env_file_would_have(self) -> None:
1262
+ overlay = {"web": {"API_KEY": "${UNITYSVC_INSTANCE_API_KEY}"}}
1263
+ text = _compose(env_file=".env")
1264
+ 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)
1267
+ assert report.ok and "interpolation" in _codes(report, "warnings")
1268
+
1269
+ def test_a_service_the_file_lacks_is_an_error(self) -> None:
1270
+ report = validate_instance_spec(self.compose(), environment={"ghost": {"A": "1"}})
1271
+ assert "overlay_service" in _codes(report)
1272
+ with pytest.raises(InstanceSpecError):
1273
+ compile_instance_spec(self.compose(), _resources(), environment={"ghost": {"A": "1"}})
1274
+
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:
1290
+ doc = {
1291
+ "category": "instance_spec",
1292
+ "mime_type": "text",
1293
+ "file_path": "c.yaml",
1294
+ "meta": {"environment": overlay},
1295
+ }
1296
+ with pytest.raises(ValidationError, match="meta.environment"):
1297
+ DocumentData.model_validate(doc)
1298
+
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
+ def test_the_schema_describes_meta_as_open(self) -> None:
1308
+ schema = json.loads((SCHEMA_DIR / "offering_v1.json").read_text())
1309
+ assert "instance_spec" in json.dumps(schema)
1310
+
1311
+
1312
+ class TestScratch:
1313
+ def test_the_manifest_schema_has_scratch(self) -> None:
1314
+ props = MANIFEST_SCHEMA["$defs"]["ManifestService"]["properties"]
1315
+ assert "scratch" in props
1316
+ manifest = {"services": [{"name": "a", "image": "i", "scratch": [{"path": "/data"}]}]}
1317
+ assert list(Draft7Validator(MANIFEST_SCHEMA).iter_errors(manifest)) == []
1318
+ bad = {"services": [{"name": "a", "image": "i", "scratch": [{"path": "data"}]}]}
1319
+ assert list(Draft7Validator(MANIFEST_SCHEMA).iter_errors(bad)) != []
1320
+ with pytest.raises(ValidationError):
1321
+ NormalizedManifest.model_validate(bad)
1322
+ with pytest.raises(ValidationError, match="distinct"):
1323
+ NormalizedManifest.model_validate(
1324
+ {"services": [{"name": "a", "image": "i", "scratch": [{"path": "/d"}, {"path": "/d"}]}]}
1325
+ )
1326
+ with pytest.raises(ValidationError):
1327
+ NormalizedManifest.model_validate({"services": [{"name": "a", "image": "i", "scratch": [{"path": "/"}]}]})
1328
+
1329
+ def test_the_golden_weixin_manifest_carries_scratch(self) -> None:
1330
+ golden = json.loads((FIXTURES / "manifest" / "weixin.manifest.json").read_text())
1331
+ assert golden["services"][0]["scratch"] == [{"path": "/app/data"}]
1332
+
1333
+
1334
+ def _with_volumes(volumes: list[Any]) -> str:
1335
+ base = {"image": f"example/app{DIGEST}", "ports": ["8080"], "volumes": volumes}
1336
+ return yaml.safe_dump({"services": {"web": base}, "volumes": {"v": {}}})
1337
+
1338
+
1339
+ class TestReviewFixes:
1340
+ def test_scratch_paths_are_normalized(self) -> None:
1341
+ for bad in ("/data/..", "/data/../..", "/."):
1342
+ text = _with_volumes([{"type": "volume", "source": "v", "target": bad}])
1343
+ assert "bad_value" in _codes(validate_instance_spec(text)), bad
1344
+ text = _with_volumes([{"type": "volume", "source": "v", "target": "/data"}, "/data/../data"])
1345
+ assert "duplicate_mount" in _codes(validate_instance_spec(text))
1346
+ for bad in ("/data/..", "/a//b", "/a/", "/", "//", "//data"):
1347
+ with pytest.raises(ValidationError):
1348
+ NormalizedManifest.model_validate(
1349
+ {"services": [{"name": "a", "image": "i", "scratch": [{"path": bad}]}]}
1350
+ )
1351
+
1352
+ def test_an_overlay_resolves_an_inherited_variable(self) -> None:
1353
+ for env in (["KEY"], {"KEY": None}):
1354
+ text = _compose(environment=env)
1355
+ assert "bad_env" in _codes(validate_instance_spec(text))
1356
+ overlay = {"web": {"KEY": "v"}}
1357
+ assert validate_instance_spec(text, environment=overlay).ok
1358
+ assert compile_instance_spec(text, _resources(), environment=overlay).manifest.services[0].env == {
1359
+ "KEY": "v"
1360
+ }
1361
+
1362
+
1363
+ class TestUpstreamExample:
1364
+ """The Kadxy URL-plus-overlay case: the project's own Compose file, a URL, a pinned hash and an overlay."""
1365
+
1366
+ def offering(self) -> dict[str, Any]:
1367
+ return json.loads((WEIXIN_UPSTREAM / "offering.json").read_text())
1368
+
1369
+ def test_it_validates(self, validator: DataValidator) -> None:
1370
+ for name in ("offering", "listing"):
1371
+ ok, errors = validator.validate_data_file(
1372
+ WEIXIN_UPSTREAM / f"{name}.json", f"{name}_v1", check_name_consistency=False
1373
+ )
1374
+ assert ok, errors
1375
+
1376
+ def test_the_url_is_the_pinned_commit_and_the_hash_matches_the_fixture(self) -> None:
1377
+ import hashlib
1378
+
1379
+ doc = self.offering()["documents"][INSTANCE_SPEC_TITLE]
1380
+ assert "ad6097361b834e263247764368c15529b5cf2a39" in doc["external_url"]
1381
+ assert (
1382
+ doc["meta"]["sha256"]
1383
+ == hashlib.sha256((WEIXIN_UPSTREAM / "upstream-compose.yaml").read_bytes()).hexdigest()
1384
+ )
1385
+
1386
+ def test_the_overlay_and_scratch_reach_the_manifest(self) -> None:
1387
+ offering = self.offering()
1388
+ doc = offering["documents"][INSTANCE_SPEC_TITLE]
1389
+ channel = ContainerChannel.model_validate(offering["upstream_access_config"]["base"])
1390
+ compiled = compile_instance_spec(
1391
+ (WEIXIN_UPSTREAM / "upstream-compose.yaml").read_text(),
1392
+ channel.resources,
1393
+ environment=doc["meta"]["environment"],
1394
+ )
1395
+ service = compiled.manifest.services[0]
1396
+ assert service.env == {"DATA_DIR": "/app/data", "API_KEY": "${UNITYSVC_INSTANCE_API_KEY}"}
1397
+ assert service.image == "ghcr.io/kadxy/weixin-ilink-gateway:latest"
1398
+ assert [s.path for s in service.scratch or []] == ["/app/data"]
1399
+
1400
+
1401
+ class TestVersion0311Shapes:
1402
+ """What 0.3.11 accepted keeps validating."""
1403
+
1404
+ def test_digest_pinned_images_and_the_two_examples(self, validator: DataValidator) -> None:
1405
+ for service_dir in (ECHO, WEIXIN):
1406
+ offering = json.loads((service_dir / "offering.json").read_text())
1407
+ assert _errors(validator, offering, service_dir) == []
1408
+ assert "unpinned_image" not in {w.code for w in validator.service_warnings(offering, service_dir)}
1409
+
1410
+ def test_the_document_form_with_a_url_and_no_overlay(self, validator: DataValidator) -> None:
1411
+ offering = expand_instance_spec(_echo())
1412
+ doc = offering["documents"][INSTANCE_SPEC_TITLE]
1413
+ del doc["file_path"]
1414
+ doc["external_url"] = "https://raw.githubusercontent.com/o/r/" + "a" * 40 + "/compose.yaml"
1415
+ assert _errors(validator, offering) == []
File without changes
File without changes