unitysvc-core 0.3.10__tar.gz → 0.3.12__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (64) hide show
  1. {unitysvc_core-0.3.10/src/unitysvc_core.egg-info → unitysvc_core-0.3.12}/PKG-INFO +39 -12
  2. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/README.md +38 -11
  3. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/pyproject.toml +1 -1
  4. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/instance_spec.py +231 -25
  5. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/models/channel.py +3 -3
  6. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/models/documents.py +19 -1
  7. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/models/manifest.py +34 -0
  8. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/models/offering_v1.py +44 -0
  9. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/schema/normalized_manifest_v1.json +33 -0
  10. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/schema/offering_v1.json +20 -8
  11. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/validator.py +47 -25
  12. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12/src/unitysvc_core.egg-info}/PKG-INFO +39 -12
  13. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/tests/test_container.py +453 -37
  14. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/LICENSE +0 -0
  15. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/setup.cfg +0 -0
  16. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/__init__.py +0 -0
  17. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/grants.py +0 -0
  18. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/models/__init__.py +0 -0
  19. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/models/base.py +0 -0
  20. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/models/container.py +0 -0
  21. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/models/listing_data.py +0 -0
  22. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/models/listing_v1.py +0 -0
  23. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/models/offering_data.py +0 -0
  24. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/models/pricing.py +0 -0
  25. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/models/probes.py +0 -0
  26. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/models/promotion_data.py +0 -0
  27. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/models/provider_data.py +0 -0
  28. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/models/provider_v1.py +0 -0
  29. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/models/service.py +0 -0
  30. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/models/service_group_data.py +0 -0
  31. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/models/validators.py +0 -0
  32. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/parameter_usage.py +0 -0
  33. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/py.typed +0 -0
  34. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/schema/base.json +0 -0
  35. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/schema/listing_v1.json +0 -0
  36. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/schema/probes_v1.json +0 -0
  37. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/schema/promotion_v1.json +0 -0
  38. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/schema/provider_v1.json +0 -0
  39. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/schema/service_group_v1.json +0 -0
  40. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/utils.py +0 -0
  41. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core.egg-info/SOURCES.txt +0 -0
  42. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core.egg-info/dependency_links.txt +0 -0
  43. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core.egg-info/requires.txt +0 -0
  44. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core.egg-info/top_level.txt +0 -0
  45. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/tests/test_access_interface_routing.py +0 -0
  46. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/tests/test_canonical_interfaces.py +0 -0
  47. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/tests/test_channel.py +0 -0
  48. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/tests/test_documents.py +0 -0
  49. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/tests/test_effective_price.py +0 -0
  50. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/tests/test_external_apps.py +0 -0
  51. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/tests/test_grants.py +0 -0
  52. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/tests/test_hidden_path_skip.py +0 -0
  53. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/tests/test_listing_audience.py +0 -0
  54. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/tests/test_offering_data.py +0 -0
  55. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/tests/test_parameter_usage.py +0 -0
  56. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/tests/test_pricing.py +0 -0
  57. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/tests/test_provider_account_rate_limits.py +0 -0
  58. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/tests/test_request_rules.py +0 -0
  59. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/tests/test_service_group.py +0 -0
  60. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/tests/test_service_status.py +0 -0
  61. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/tests/test_utils.py +0 -0
  62. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/tests/test_validate_service.py +0 -0
  63. {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/tests/test_validator.py +0 -0
  64. {unitysvc_core-0.3.10 → 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.10
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>
@@ -273,7 +273,7 @@ A policy has three kinds of entry (unitysvc/unitysvc#2770):
273
273
  | `params` | the enrollment parameters (below) |
274
274
  | `request_rules` | `http` channels only: rules the gateway answers itself before dispatch (below) |
275
275
  | `servers` | the connection: `HttpServer`, `SmtpServer`, `S3Server` or `McpServer` (a `container` channel's are `HttpServer`s) |
276
- | `spec`, `resources`, `entries` | `container` channels only: the instance spec, the tier's resources and its entries (below) |
276
+ | `resources`, `entries` | `container` channels only: the tier's resources and its entries (below) |
277
277
 
278
278
  The common one-server case writes the connection fields directly on the channel; they are read as `servers[0]`. When a channel has both, each server inherits the direct fields it does not set. Any string may be a template (`{{ params.X }}`, `${ secrets.X }`, `${ customer_secrets.X ?? default }`), so numeric and boolean connection fields also accept strings.
279
279
 
@@ -284,10 +284,11 @@ Unknown keys are refused. Retired keys are refused with what to do instead (`RET
284
284
  A `container` channel is one tier of a service that runs as instances on Kubernetes (unitysvc/unitysvc-core#105; the compute agent is unitysvc-compute-k8s). Core only holds the data format and its validation: no Kubernetes client, image pulling, placement or pricing. One channel per tier (`base`, `team`), each with its own `resources` and its own price in the listing's channel-keyed `list_price`.
285
285
 
286
286
  ```json
287
+ "service_type": "container",
288
+ "instance_spec": "compose.yaml",
287
289
  "upstream_access_config": {
288
290
  "base": {
289
291
  "access_method": "container",
290
- "spec": "Application",
291
292
  "resources": {"limits": {"cpu": "250m", "memory": "256Mi", "ephemeral-storage": "1Gi"}},
292
293
  "entries": [{"name": "web", "service": "web", "port": 5678, "auth": "key"}],
293
294
  "customer_access_requests": [
@@ -298,29 +299,55 @@ A `container` channel is one tier of a service that runs as instances on Kuberne
298
299
  }
299
300
  ```
300
301
 
301
- - `spec` is the title of an `instance_spec` Document of the offering (written directly on the channel, like a one-server channel's connection).
302
+ - 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.
302
303
  - `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.
303
304
  - The channel is always enrollable and must request `resource:container` with `create`, marked `required` (`grants.RESOURCES` knows the resource; it has no options and no limits).
304
305
  - `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).
305
306
  - `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).
306
307
  - `params` and `customer_access_requests` are as on the other channels.
307
308
 
308
- **The instance spec.** The seller's file is a Document of category `instance_spec`, `"meta": {"format": "compose"}` (the default and the only format accepted; any other is refused with a message saying so). Core stores it like any uploaded file; the platform passes it on. A format is accepted only if it compiles to the normalized manifest, which is why a Helm chart is not (it renders arbitrary Kubernetes objects).
309
+ **The instance spec.** An offering with a `container` channel has exactly one instance spec, from either of two forms (two, or one on an offering with no container channel, is an error); a different stack is a different offering:
310
+
311
+ - the offering-level shortcut, like `logo`: `"instance_spec": "compose.yaml"`, a path relative to the offering file or an https URL, in `compose` format;
312
+ - a Document of category `instance_spec`, `"meta": {"format": "compose"}` (the default and the only format accepted; any other is refused with a message saying so), with exactly one of `file_path` and `external_url`.
313
+
314
+ The seller tooling expands the shortcut before upload with `expand_instance_spec(offering)`, which returns the offering with `documents["Instance spec"]` added (`file_path` or `external_url`, not public) and the shortcut removed, and raises if the offering already has an instance-spec Document. Core accepts both forms. A format is accepted only if it compiles to the normalized manifest, which is why a Helm chart is not (it renders arbitrary Kubernetes objects). `resources.services` keys are checked against the services of that one file, for every container channel.
315
+
316
+ *A URL is a snapshot source, not a link.* For this category core validates only the URL's shape: https, a host, no credentials, no `localhost`/`.local`/`.internal` name, no private, loopback or link-local IP literal (including integer and hex forms). Core fetches nothing and cannot check the content of a URL, so it validates the file only when it is local. `meta.source` (the original URL) and `meta.sha256` (64 lowercase hex characters, the bytes the seller tested) are accepted on the Document, and a local file is checked against `meta.sha256`. The contract for the **backend** (not implemented in core; unitysvc/unitysvc-core#107):
317
+
318
+ 1. At ingest, fetch the `external_url` (or the shortcut URL) once, store the bytes in the content-addressed object store, and keep the original URL in `meta.source`. Never fetch at enrollment; re-uploading is what refreshes the snapshot. The cluster runs what the policy approved.
319
+ 2. Run `validate_instance_spec` on the snapshot (with each container channel) and refuse the upload if it has errors. A failed fetch fails the upload with a clear error.
320
+ 3. https only, with a size cap and a timeout; limit redirects and apply the checks to each hop; refuse private, loopback and link-local addresses after resolving the host (SSRF); start with a host allowlist (`raw.githubusercontent.com`).
321
+ 4. Rewrite `github.com/<o>/<r>/blob/<ref>/<path>` pages to the raw URL. Warn on a branch URL (`/main/`); a commit-SHA permalink is the recommended form.
322
+ 5. If `meta.sha256` is set and the snapshot's differs, refuse the upload.
323
+
324
+ `specs validate` and the local Docker `run-tests` in the seller tooling download the file themselves.
309
325
 
310
326
  **The Compose policy** is an allowlist: a key in none of these is rejected, so a new Compose feature is never silently accepted. The compose file is parsed as YAML without executing anything (duplicate keys are refused).
311
327
 
312
328
  | Bucket | Features |
313
329
  | --- | --- |
314
- | Honor | `image` (a literal digest: `name:tag@sha256:...`), `command`, `entrypoint`, `environment`, `ports` (container side only), `healthcheck`, `working_dir`, `user`, `read_only` |
330
+ | Honor | `image` (a tag, or a literal digest `name:tag@sha256:...`; a tag-only image warns), `command`, `entrypoint`, `environment`, `ports` (container side only), `healthcheck`, `working_dir`, `user`, `read_only` |
315
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` |
316
- | Ignore, warn loudly | `depends_on` (no start ordering: the app must retry; readiness keeps traffic away), named volumes (scratch space: data does not survive a restart) |
317
- | Reject | `build`, `privileged`, `cap_add`, `devices`, `network_mode`, `pid`, `ipc`, `security_opt`, `sysctls`, bind mounts and host paths, `volumes_from`, a named volume shared by two services, `runtime`, `extra_hosts`, `env_file`, `secrets`, `configs`, `extends`, `include`, an unpinned `image`, two services that share no network, any other key |
332
+ | Ignore, warn loudly | `depends_on` (no start ordering: the app must retry; readiness keeps traffic away), `env_file` (the values it would supply are missing: provide them with `meta.environment`), named volumes (scratch space: data survives a container restart, not a replacement of the instance) |
333
+ | Reject | `build`, `privileged`, `cap_add`, `devices`, `network_mode`, `pid`, `ipc`, `security_opt`, `sysctls`, bind mounts and host paths, `volumes_from`, a named volume shared by two services, `runtime`, `extra_hosts`, `secrets`, `configs`, `extends`, `include`, an `image` with a malformed digest, two services that share no network, any other key |
318
334
 
319
- A seller can keep one file for local Docker and the platform: write `image` as `name:tag@sha256:...` (Compose runs the digest) and leave `deploy.resources` in place. Sibling services reach each other by name (`redis:6379`); service names must be DNS labels. `${VAR}` in an `environment` value is kept as written with a warning (how a secret or parameter binds to it is open question 4 of #105); in `image` and `ports` a variable is an error.
335
+ A seller can keep one file for local Docker and the platform and leave `deploy.resources` in place. **Images.** A tag-only or untagged `image` (`:latest`, `:1.4`, none) is accepted with a note (`unpinned_image`, a warning): the platform runs it as written and reports the digest it pulled, and a moving tag can change at a restart; a re-upload does not update running instances. A digest the seller writes (`name:tag@sha256:...`) is honored as written; one that is malformed is an error (`bad_digest`). Core never contacts a registry. Sibling services reach each other by name (`redis:6379`); service names must be DNS labels. `${VAR}` in an `environment` value is kept as written with a warning (how a secret or parameter binds to it is open question 4 of #105); in `image` and `ports` a variable is an error.
336
+
337
+ **Reusing a generic Compose file.** A seller can keep one generic file (in their repo) and vary it for UnitySVC in the Document's `meta`: `meta.environment` is `{service: {NAME: "value"}}`; each service must exist in the file and each value is a string with a valid variable name. It overrides the file's own `environment` on a name conflict, and it is applied only at compile time (`compile_instance_spec(text, resources, environment=...)`), so the stored Compose bytes stay an exact copy of the seller's file and the seller's local test and the backend merge identically. `validate_instance_spec(..., environment=...)` checks it against the file (`overlay_service`). Values are plaintext in the spec; only `${UNITYSVC_INSTANCE_API_KEY}` is bound per instance (any other `${...}` only warns, open question 4 of #105). Only `environment` is supported, not a general override. `meta.sha256` is recommended with a URL, so an upstream change that breaks the overlay fails the upload.
338
+
339
+ ```json
340
+ "documents": {"Instance spec": {
341
+ "category": "instance_spec", "mime_type": "text",
342
+ "external_url": "https://raw.githubusercontent.com/Kadxy/weixin-ilink-gateway/<commit-sha>/docker-compose.yaml",
343
+ "meta": {"format": "compose", "sha256": "<64 hex>",
344
+ "environment": {"gateway": {"API_KEY": "${UNITYSVC_INSTANCE_API_KEY}"}}}
345
+ }}
346
+ ```
320
347
 
321
- **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>.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.
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.
322
349
 
323
- **The normalized manifest** is what the agent receives for one instance: the compiled, validated spec. `NormalizedManifest` (JSON Schema `schema/normalized_manifest_v1.json`, which the agent repo vendors) has one service per Compose service with `name`, `image`, `ports`, `env`, `command`, `args`, `resources` (`requests`, `limits`), `replicas` and `health`, in the shapes of the agent's `intent.go`. `compile_instance_spec(text, resources)` returns a `CompiledInstanceSpec`: the manifest, the keys it `dropped` and the warnings. Compose `entrypoint` becomes `command` and Compose `command` becomes `args`; `healthcheck` becomes an `exec` `health` (`interval`, `timeout`, `retries` and `start_period` map to `period_seconds`, `timeout_seconds`, `failure_threshold` and `start_period_seconds`) (bounded as the agent bounds them: period and timeout 1-300 s, retries 1-30, start period at most its default 120 s progress deadline); the tier `resources` go to the single service, or are split by `resources.services`. That core compiles at all is a proposal (open question 3 of #105). `working_dir`, `user`, `read_only` and the scratch volumes are accepted by the policy but the agent's current manifest has no field for them: they are recorded in `dropped` with reason `not_carried` and a warning.
350
+ **The normalized manifest** is what the agent receives for one instance: the compiled, validated spec. `NormalizedManifest` (JSON Schema `schema/normalized_manifest_v1.json`, which the agent repo vendors) has one service per Compose service with `name`, `image`, `ports`, `env`, `command`, `args`, `resources` (`requests`, `limits`), `replicas`, `health` and `scratch` (`[{"path": "/data"}]`, from each named or anonymous volume mount; the cluster gives each an `emptyDir`), in the shapes of the agent's `intent.go` (`scratch` is a core addition the agent vendors the schema for later). `compile_instance_spec(text, resources)` returns a `CompiledInstanceSpec`: the manifest, the keys it `dropped` and the warnings. Compose `entrypoint` becomes `command` and Compose `command` becomes `args`; `healthcheck` becomes an `exec` `health` (`interval`, `timeout`, `retries` and `start_period` map to `period_seconds`, `timeout_seconds`, `failure_threshold` and `start_period_seconds`) (bounded as the agent bounds them: period and timeout 1-300 s, retries 1-30, start period at most its default 120 s progress deadline); the tier `resources` go to the single service, or are split by `resources.services`. That core compiles at all is a proposal (open question 3 of #105). `working_dir`, `user` and `read_only` are accepted by the policy but the agent's current manifest has no field for them: they are recorded in `dropped` with reason `not_carried` and a warning.
324
351
 
325
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:
326
353
 
@@ -330,7 +357,7 @@ A seller can keep one file for local Docker and the platform: write `image` as `
330
357
 
331
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`.
332
359
 
333
- Examples: `tests/example_data/hashicorp/services/echo` (one service, two tiers) and `tests/example_data/kadxy/services/weixin-ilink-gateway` (secrets, scratch state, outbound traffic; its image digest is a marked placeholder and its original `docker-compose.yaml` is a negative test).
360
+ Examples: `tests/example_data/hashicorp/services/echo` (one service, two tiers); `tests/example_data/kadxy/services/weixin-ilink-gateway` (secrets, scratch state, outbound traffic; its image digest is a marked placeholder); and `tests/example_data/kadxy/services/weixin-ilink-gateway-upstream` (the project's own Compose file by URL at a pinned commit with `meta.sha256`, plus a `meta.environment` overlay; `upstream-compose.yaml` is a byte-for-byte copy of that file, and `meta.sha256` is its hash, as core fetches nothing).
334
361
 
335
362
  ### Request rules
336
363
 
@@ -237,7 +237,7 @@ A policy has three kinds of entry (unitysvc/unitysvc#2770):
237
237
  | `params` | the enrollment parameters (below) |
238
238
  | `request_rules` | `http` channels only: rules the gateway answers itself before dispatch (below) |
239
239
  | `servers` | the connection: `HttpServer`, `SmtpServer`, `S3Server` or `McpServer` (a `container` channel's are `HttpServer`s) |
240
- | `spec`, `resources`, `entries` | `container` channels only: the instance spec, the tier's resources and its entries (below) |
240
+ | `resources`, `entries` | `container` channels only: the tier's resources and its entries (below) |
241
241
 
242
242
  The common one-server case writes the connection fields directly on the channel; they are read as `servers[0]`. When a channel has both, each server inherits the direct fields it does not set. Any string may be a template (`{{ params.X }}`, `${ secrets.X }`, `${ customer_secrets.X ?? default }`), so numeric and boolean connection fields also accept strings.
243
243
 
@@ -248,10 +248,11 @@ Unknown keys are refused. Retired keys are refused with what to do instead (`RET
248
248
  A `container` channel is one tier of a service that runs as instances on Kubernetes (unitysvc/unitysvc-core#105; the compute agent is unitysvc-compute-k8s). Core only holds the data format and its validation: no Kubernetes client, image pulling, placement or pricing. One channel per tier (`base`, `team`), each with its own `resources` and its own price in the listing's channel-keyed `list_price`.
249
249
 
250
250
  ```json
251
+ "service_type": "container",
252
+ "instance_spec": "compose.yaml",
251
253
  "upstream_access_config": {
252
254
  "base": {
253
255
  "access_method": "container",
254
- "spec": "Application",
255
256
  "resources": {"limits": {"cpu": "250m", "memory": "256Mi", "ephemeral-storage": "1Gi"}},
256
257
  "entries": [{"name": "web", "service": "web", "port": 5678, "auth": "key"}],
257
258
  "customer_access_requests": [
@@ -262,29 +263,55 @@ A `container` channel is one tier of a service that runs as instances on Kuberne
262
263
  }
263
264
  ```
264
265
 
265
- - `spec` is the title of an `instance_spec` Document of the offering (written directly on the channel, like a one-server channel's connection).
266
+ - 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.
266
267
  - `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.
267
268
  - The channel is always enrollable and must request `resource:container` with `create`, marked `required` (`grants.RESOURCES` knows the resource; it has no options and no limits).
268
269
  - `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).
269
270
  - `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).
270
271
  - `params` and `customer_access_requests` are as on the other channels.
271
272
 
272
- **The instance spec.** The seller's file is a Document of category `instance_spec`, `"meta": {"format": "compose"}` (the default and the only format accepted; any other is refused with a message saying so). Core stores it like any uploaded file; the platform passes it on. A format is accepted only if it compiles to the normalized manifest, which is why a Helm chart is not (it renders arbitrary Kubernetes objects).
273
+ **The instance spec.** An offering with a `container` channel has exactly one instance spec, from either of two forms (two, or one on an offering with no container channel, is an error); a different stack is a different offering:
274
+
275
+ - the offering-level shortcut, like `logo`: `"instance_spec": "compose.yaml"`, a path relative to the offering file or an https URL, in `compose` format;
276
+ - a Document of category `instance_spec`, `"meta": {"format": "compose"}` (the default and the only format accepted; any other is refused with a message saying so), with exactly one of `file_path` and `external_url`.
277
+
278
+ The seller tooling expands the shortcut before upload with `expand_instance_spec(offering)`, which returns the offering with `documents["Instance spec"]` added (`file_path` or `external_url`, not public) and the shortcut removed, and raises if the offering already has an instance-spec Document. Core accepts both forms. A format is accepted only if it compiles to the normalized manifest, which is why a Helm chart is not (it renders arbitrary Kubernetes objects). `resources.services` keys are checked against the services of that one file, for every container channel.
279
+
280
+ *A URL is a snapshot source, not a link.* For this category core validates only the URL's shape: https, a host, no credentials, no `localhost`/`.local`/`.internal` name, no private, loopback or link-local IP literal (including integer and hex forms). Core fetches nothing and cannot check the content of a URL, so it validates the file only when it is local. `meta.source` (the original URL) and `meta.sha256` (64 lowercase hex characters, the bytes the seller tested) are accepted on the Document, and a local file is checked against `meta.sha256`. The contract for the **backend** (not implemented in core; unitysvc/unitysvc-core#107):
281
+
282
+ 1. At ingest, fetch the `external_url` (or the shortcut URL) once, store the bytes in the content-addressed object store, and keep the original URL in `meta.source`. Never fetch at enrollment; re-uploading is what refreshes the snapshot. The cluster runs what the policy approved.
283
+ 2. Run `validate_instance_spec` on the snapshot (with each container channel) and refuse the upload if it has errors. A failed fetch fails the upload with a clear error.
284
+ 3. https only, with a size cap and a timeout; limit redirects and apply the checks to each hop; refuse private, loopback and link-local addresses after resolving the host (SSRF); start with a host allowlist (`raw.githubusercontent.com`).
285
+ 4. Rewrite `github.com/<o>/<r>/blob/<ref>/<path>` pages to the raw URL. Warn on a branch URL (`/main/`); a commit-SHA permalink is the recommended form.
286
+ 5. If `meta.sha256` is set and the snapshot's differs, refuse the upload.
287
+
288
+ `specs validate` and the local Docker `run-tests` in the seller tooling download the file themselves.
273
289
 
274
290
  **The Compose policy** is an allowlist: a key in none of these is rejected, so a new Compose feature is never silently accepted. The compose file is parsed as YAML without executing anything (duplicate keys are refused).
275
291
 
276
292
  | Bucket | Features |
277
293
  | --- | --- |
278
- | Honor | `image` (a literal digest: `name:tag@sha256:...`), `command`, `entrypoint`, `environment`, `ports` (container side only), `healthcheck`, `working_dir`, `user`, `read_only` |
294
+ | Honor | `image` (a tag, or a literal digest `name:tag@sha256:...`; a tag-only image warns), `command`, `entrypoint`, `environment`, `ports` (container side only), `healthcheck`, `working_dir`, `user`, `read_only` |
279
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` |
280
- | Ignore, warn loudly | `depends_on` (no start ordering: the app must retry; readiness keeps traffic away), named volumes (scratch space: data does not survive a restart) |
281
- | Reject | `build`, `privileged`, `cap_add`, `devices`, `network_mode`, `pid`, `ipc`, `security_opt`, `sysctls`, bind mounts and host paths, `volumes_from`, a named volume shared by two services, `runtime`, `extra_hosts`, `env_file`, `secrets`, `configs`, `extends`, `include`, an unpinned `image`, two services that share no network, any other key |
296
+ | Ignore, warn loudly | `depends_on` (no start ordering: the app must retry; readiness keeps traffic away), `env_file` (the values it would supply are missing: provide them with `meta.environment`), named volumes (scratch space: data survives a container restart, not a replacement of the instance) |
297
+ | Reject | `build`, `privileged`, `cap_add`, `devices`, `network_mode`, `pid`, `ipc`, `security_opt`, `sysctls`, bind mounts and host paths, `volumes_from`, a named volume shared by two services, `runtime`, `extra_hosts`, `secrets`, `configs`, `extends`, `include`, an `image` with a malformed digest, two services that share no network, any other key |
282
298
 
283
- A seller can keep one file for local Docker and the platform: write `image` as `name:tag@sha256:...` (Compose runs the digest) and leave `deploy.resources` in place. Sibling services reach each other by name (`redis:6379`); service names must be DNS labels. `${VAR}` in an `environment` value is kept as written with a warning (how a secret or parameter binds to it is open question 4 of #105); in `image` and `ports` a variable is an error.
299
+ A seller can keep one file for local Docker and the platform and leave `deploy.resources` in place. **Images.** A tag-only or untagged `image` (`:latest`, `:1.4`, none) is accepted with a note (`unpinned_image`, a warning): the platform runs it as written and reports the digest it pulled, and a moving tag can change at a restart; a re-upload does not update running instances. A digest the seller writes (`name:tag@sha256:...`) is honored as written; one that is malformed is an error (`bad_digest`). Core never contacts a registry. Sibling services reach each other by name (`redis:6379`); service names must be DNS labels. `${VAR}` in an `environment` value is kept as written with a warning (how a secret or parameter binds to it is open question 4 of #105); in `image` and `ports` a variable is an error.
300
+
301
+ **Reusing a generic Compose file.** A seller can keep one generic file (in their repo) and vary it for UnitySVC in the Document's `meta`: `meta.environment` is `{service: {NAME: "value"}}`; each service must exist in the file and each value is a string with a valid variable name. It overrides the file's own `environment` on a name conflict, and it is applied only at compile time (`compile_instance_spec(text, resources, environment=...)`), so the stored Compose bytes stay an exact copy of the seller's file and the seller's local test and the backend merge identically. `validate_instance_spec(..., environment=...)` checks it against the file (`overlay_service`). Values are plaintext in the spec; only `${UNITYSVC_INSTANCE_API_KEY}` is bound per instance (any other `${...}` only warns, open question 4 of #105). Only `environment` is supported, not a general override. `meta.sha256` is recommended with a URL, so an upstream change that breaks the overlay fails the upload.
302
+
303
+ ```json
304
+ "documents": {"Instance spec": {
305
+ "category": "instance_spec", "mime_type": "text",
306
+ "external_url": "https://raw.githubusercontent.com/Kadxy/weixin-ilink-gateway/<commit-sha>/docker-compose.yaml",
307
+ "meta": {"format": "compose", "sha256": "<64 hex>",
308
+ "environment": {"gateway": {"API_KEY": "${UNITYSVC_INSTANCE_API_KEY}"}}}
309
+ }}
310
+ ```
284
311
 
285
- **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>.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.
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.
286
313
 
287
- **The normalized manifest** is what the agent receives for one instance: the compiled, validated spec. `NormalizedManifest` (JSON Schema `schema/normalized_manifest_v1.json`, which the agent repo vendors) has one service per Compose service with `name`, `image`, `ports`, `env`, `command`, `args`, `resources` (`requests`, `limits`), `replicas` and `health`, in the shapes of the agent's `intent.go`. `compile_instance_spec(text, resources)` returns a `CompiledInstanceSpec`: the manifest, the keys it `dropped` and the warnings. Compose `entrypoint` becomes `command` and Compose `command` becomes `args`; `healthcheck` becomes an `exec` `health` (`interval`, `timeout`, `retries` and `start_period` map to `period_seconds`, `timeout_seconds`, `failure_threshold` and `start_period_seconds`) (bounded as the agent bounds them: period and timeout 1-300 s, retries 1-30, start period at most its default 120 s progress deadline); the tier `resources` go to the single service, or are split by `resources.services`. That core compiles at all is a proposal (open question 3 of #105). `working_dir`, `user`, `read_only` and the scratch volumes are accepted by the policy but the agent's current manifest has no field for them: they are recorded in `dropped` with reason `not_carried` and a warning.
314
+ **The normalized manifest** is what the agent receives for one instance: the compiled, validated spec. `NormalizedManifest` (JSON Schema `schema/normalized_manifest_v1.json`, which the agent repo vendors) has one service per Compose service with `name`, `image`, `ports`, `env`, `command`, `args`, `resources` (`requests`, `limits`), `replicas`, `health` and `scratch` (`[{"path": "/data"}]`, from each named or anonymous volume mount; the cluster gives each an `emptyDir`), in the shapes of the agent's `intent.go` (`scratch` is a core addition the agent vendors the schema for later). `compile_instance_spec(text, resources)` returns a `CompiledInstanceSpec`: the manifest, the keys it `dropped` and the warnings. Compose `entrypoint` becomes `command` and Compose `command` becomes `args`; `healthcheck` becomes an `exec` `health` (`interval`, `timeout`, `retries` and `start_period` map to `period_seconds`, `timeout_seconds`, `failure_threshold` and `start_period_seconds`) (bounded as the agent bounds them: period and timeout 1-300 s, retries 1-30, start period at most its default 120 s progress deadline); the tier `resources` go to the single service, or are split by `resources.services`. That core compiles at all is a proposal (open question 3 of #105). `working_dir`, `user` and `read_only` are accepted by the policy but the agent's current manifest has no field for them: they are recorded in `dropped` with reason `not_carried` and a warning.
288
315
 
289
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:
290
317
 
@@ -294,7 +321,7 @@ A seller can keep one file for local Docker and the platform: write `image` as `
294
321
 
295
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`.
296
323
 
297
- Examples: `tests/example_data/hashicorp/services/echo` (one service, two tiers) and `tests/example_data/kadxy/services/weixin-ilink-gateway` (secrets, scratch state, outbound traffic; its image digest is a marked placeholder and its original `docker-compose.yaml` is a negative test).
324
+ Examples: `tests/example_data/hashicorp/services/echo` (one service, two tiers); `tests/example_data/kadxy/services/weixin-ilink-gateway` (secrets, scratch state, outbound traffic; its image digest is a marked placeholder); and `tests/example_data/kadxy/services/weixin-ilink-gateway-upstream` (the project's own Compose file by URL at a pinned commit with `meta.sha256`, plus a `meta.environment` overlay; `upstream-compose.yaml` is a byte-for-byte copy of that file, and `meta.sha256` is its hash, as core fetches nothing).
298
325
 
299
326
  ### Request rules
300
327
 
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "unitysvc-core"
7
- version = "0.3.10"
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" }]