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