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.
- {unitysvc_core-0.3.11/src/unitysvc_core.egg-info → unitysvc_core-0.3.12}/PKG-INFO +18 -7
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/README.md +17 -6
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/pyproject.toml +1 -1
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/instance_spec.py +147 -25
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/models/documents.py +3 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/models/manifest.py +34 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/schema/normalized_manifest_v1.json +33 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/validator.py +3 -1
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12/src/unitysvc_core.egg-info}/PKG-INFO +18 -7
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/tests/test_container.py +244 -17
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/LICENSE +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/setup.cfg +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/__init__.py +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/grants.py +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/models/__init__.py +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/models/base.py +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/models/channel.py +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/models/container.py +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/models/listing_data.py +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/models/listing_v1.py +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/models/offering_data.py +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/models/offering_v1.py +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/models/pricing.py +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/models/probes.py +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/models/promotion_data.py +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/models/provider_data.py +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/models/provider_v1.py +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/models/service.py +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/models/service_group_data.py +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/models/validators.py +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/parameter_usage.py +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/py.typed +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/schema/base.json +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/schema/listing_v1.json +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/schema/offering_v1.json +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/schema/probes_v1.json +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/schema/promotion_v1.json +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/schema/provider_v1.json +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/schema/service_group_v1.json +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/utils.py +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core.egg-info/SOURCES.txt +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core.egg-info/dependency_links.txt +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core.egg-info/requires.txt +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core.egg-info/top_level.txt +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/tests/test_access_interface_routing.py +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/tests/test_canonical_interfaces.py +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/tests/test_channel.py +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/tests/test_documents.py +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/tests/test_effective_price.py +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/tests/test_external_apps.py +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/tests/test_grants.py +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/tests/test_hidden_path_skip.py +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/tests/test_listing_audience.py +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/tests/test_offering_data.py +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/tests/test_parameter_usage.py +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/tests/test_pricing.py +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/tests/test_provider_account_rate_limits.py +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/tests/test_request_rules.py +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/tests/test_service_group.py +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/tests/test_service_status.py +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/tests/test_utils.py +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/tests/test_validate_service.py +0 -0
- {unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/tests/test_validator.py +0 -0
- {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.
|
|
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
|
|
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
|
|
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`, `
|
|
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
|
|
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 `
|
|
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)
|
|
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
|
|
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
|
|
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`, `
|
|
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
|
|
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 `
|
|
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)
|
|
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.
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
473
|
-
"
|
|
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
|
|
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]) ->
|
|
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
|
|
728
|
-
"
|
|
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
|
-
|
|
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,
|
|
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.
|
|
865
|
-
|
|
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,
|
|
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
|
{unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/schema/normalized_manifest_v1.json
RENAMED
|
@@ -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(
|
|
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.
|
|
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
|
|
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
|
|
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`, `
|
|
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
|
|
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 `
|
|
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)
|
|
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 "
|
|
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
|
|
499
|
+
["nginx@sha256:abc", "nginx@sha256:" + "A" * 64, "nginx${TAG}" + DIGEST, "nginx latest", "nginx:1@sha256:"],
|
|
485
500
|
)
|
|
486
|
-
def
|
|
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(
|
|
805
|
-
|
|
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
|
|
847
|
-
report = validate_instance_spec((
|
|
848
|
-
assert
|
|
849
|
-
|
|
850
|
-
assert
|
|
851
|
-
|
|
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((
|
|
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("
|
|
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
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
{unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/models/service_group_data.py
RENAMED
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
{unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core/schema/service_group_v1.json
RENAMED
|
File without changes
|
|
File without changes
|
|
File without changes
|
{unitysvc_core-0.3.11 → unitysvc_core-0.3.12}/src/unitysvc_core.egg-info/dependency_links.txt
RENAMED
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|