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.
- {unitysvc_core-0.3.10/src/unitysvc_core.egg-info → unitysvc_core-0.3.12}/PKG-INFO +39 -12
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/README.md +38 -11
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/pyproject.toml +1 -1
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/instance_spec.py +231 -25
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/models/channel.py +3 -3
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/models/documents.py +19 -1
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/models/manifest.py +34 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/models/offering_v1.py +44 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/schema/normalized_manifest_v1.json +33 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/schema/offering_v1.json +20 -8
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/validator.py +47 -25
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12/src/unitysvc_core.egg-info}/PKG-INFO +39 -12
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/tests/test_container.py +453 -37
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/LICENSE +0 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/setup.cfg +0 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/__init__.py +0 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/grants.py +0 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/models/__init__.py +0 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/models/base.py +0 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/models/container.py +0 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/models/listing_data.py +0 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/models/listing_v1.py +0 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/models/offering_data.py +0 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/models/pricing.py +0 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/models/probes.py +0 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/models/promotion_data.py +0 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/models/provider_data.py +0 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/models/provider_v1.py +0 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/models/service.py +0 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/models/service_group_data.py +0 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/models/validators.py +0 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/parameter_usage.py +0 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/py.typed +0 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/schema/base.json +0 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/schema/listing_v1.json +0 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/schema/probes_v1.json +0 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/schema/promotion_v1.json +0 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/schema/provider_v1.json +0 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/schema/service_group_v1.json +0 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core/utils.py +0 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core.egg-info/SOURCES.txt +0 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core.egg-info/dependency_links.txt +0 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core.egg-info/requires.txt +0 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/src/unitysvc_core.egg-info/top_level.txt +0 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/tests/test_access_interface_routing.py +0 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/tests/test_canonical_interfaces.py +0 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/tests/test_channel.py +0 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/tests/test_documents.py +0 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/tests/test_effective_price.py +0 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/tests/test_external_apps.py +0 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/tests/test_grants.py +0 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/tests/test_hidden_path_skip.py +0 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/tests/test_listing_audience.py +0 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/tests/test_offering_data.py +0 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/tests/test_parameter_usage.py +0 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/tests/test_pricing.py +0 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/tests/test_provider_account_rate_limits.py +0 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/tests/test_request_rules.py +0 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/tests/test_service_group.py +0 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/tests/test_service_status.py +0 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/tests/test_utils.py +0 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/tests/test_validate_service.py +0 -0
- {unitysvc_core-0.3.10 → unitysvc_core-0.3.12}/tests/test_validator.py +0 -0
- {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.
|
|
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
|
-
| `
|
|
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
|
-
-
|
|
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.**
|
|
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
|
|
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
|
|
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`, `
|
|
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
|
|
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>.
|
|
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 `
|
|
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)
|
|
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
|
-
| `
|
|
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
|
-
-
|
|
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.**
|
|
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
|
|
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
|
|
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`, `
|
|
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
|
|
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>.
|
|
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 `
|
|
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)
|
|
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.
|
|
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" }]
|