unitysvc-core 0.3.9__tar.gz → 0.3.11__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.9/src/unitysvc_core.egg-info → unitysvc_core-0.3.11}/PKG-INFO +79 -4
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/README.md +77 -3
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/pyproject.toml +2 -1
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/src/unitysvc_core/grants.py +10 -2
- unitysvc_core-0.3.11/src/unitysvc_core/instance_spec.py +913 -0
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/src/unitysvc_core/models/__init__.py +15 -0
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/src/unitysvc_core/models/base.py +2 -0
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/src/unitysvc_core/models/channel.py +56 -7
- unitysvc_core-0.3.11/src/unitysvc_core/models/container.py +199 -0
- unitysvc_core-0.3.11/src/unitysvc_core/models/documents.py +83 -0
- unitysvc_core-0.3.11/src/unitysvc_core/models/manifest.py +134 -0
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/src/unitysvc_core/models/offering_v1.py +44 -0
- unitysvc_core-0.3.11/src/unitysvc_core/models/probes.py +56 -0
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/src/unitysvc_core/schema/listing_v1.json +1 -0
- unitysvc_core-0.3.11/src/unitysvc_core/schema/normalized_manifest_v1.json +311 -0
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/src/unitysvc_core/schema/offering_v1.json +688 -1
- unitysvc_core-0.3.11/src/unitysvc_core/schema/probes_v1.json +66 -0
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/src/unitysvc_core/schema/provider_v1.json +1 -0
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/src/unitysvc_core/validator.py +140 -2
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11/src/unitysvc_core.egg-info}/PKG-INFO +79 -4
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/src/unitysvc_core.egg-info/SOURCES.txt +8 -0
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/src/unitysvc_core.egg-info/requires.txt +1 -0
- unitysvc_core-0.3.11/tests/test_container.py +1188 -0
- unitysvc_core-0.3.11/tests/test_documents.py +35 -0
- unitysvc_core-0.3.9/src/unitysvc_core/models/documents.py +0 -44
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/LICENSE +0 -0
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/setup.cfg +0 -0
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/src/unitysvc_core/__init__.py +0 -0
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/src/unitysvc_core/models/listing_data.py +0 -0
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/src/unitysvc_core/models/listing_v1.py +0 -0
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/src/unitysvc_core/models/offering_data.py +0 -0
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/src/unitysvc_core/models/pricing.py +0 -0
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/src/unitysvc_core/models/promotion_data.py +0 -0
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/src/unitysvc_core/models/provider_data.py +0 -0
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/src/unitysvc_core/models/provider_v1.py +0 -0
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/src/unitysvc_core/models/service.py +0 -0
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/src/unitysvc_core/models/service_group_data.py +0 -0
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/src/unitysvc_core/models/validators.py +0 -0
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/src/unitysvc_core/parameter_usage.py +0 -0
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/src/unitysvc_core/py.typed +0 -0
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/src/unitysvc_core/schema/base.json +0 -0
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/src/unitysvc_core/schema/promotion_v1.json +0 -0
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/src/unitysvc_core/schema/service_group_v1.json +0 -0
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/src/unitysvc_core/utils.py +0 -0
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/src/unitysvc_core.egg-info/dependency_links.txt +0 -0
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/src/unitysvc_core.egg-info/top_level.txt +0 -0
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/tests/test_access_interface_routing.py +0 -0
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/tests/test_canonical_interfaces.py +0 -0
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/tests/test_channel.py +0 -0
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/tests/test_effective_price.py +0 -0
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/tests/test_external_apps.py +0 -0
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/tests/test_grants.py +0 -0
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/tests/test_hidden_path_skip.py +0 -0
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/tests/test_listing_audience.py +0 -0
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/tests/test_offering_data.py +0 -0
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/tests/test_parameter_usage.py +0 -0
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/tests/test_pricing.py +0 -0
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/tests/test_provider_account_rate_limits.py +0 -0
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/tests/test_request_rules.py +0 -0
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/tests/test_service_group.py +0 -0
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/tests/test_service_status.py +0 -0
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/tests/test_utils.py +0 -0
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/tests/test_validate_service.py +0 -0
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/tests/test_validator.py +0 -0
- {unitysvc_core-0.3.9 → unitysvc_core-0.3.11}/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.11
|
|
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>
|
|
@@ -14,6 +14,7 @@ Classifier: Typing :: Typed
|
|
|
14
14
|
Requires-Python: >=3.11
|
|
15
15
|
Description-Content-Type: text/markdown
|
|
16
16
|
License-File: LICENSE
|
|
17
|
+
Requires-Dist: pyyaml
|
|
17
18
|
Requires-Dist: pydantic>=2
|
|
18
19
|
Requires-Dist: email-validator
|
|
19
20
|
Requires-Dist: jsonschema>=4.18
|
|
@@ -59,6 +60,9 @@ src/unitysvc_core/
|
|
|
59
60
|
│ │ # Pricing union, validate_pricing, cost calculation
|
|
60
61
|
│ ├── channel.py # UpstreamAccessConfig, ChannelConfig, per-protocol
|
|
61
62
|
│ │ # servers, ChannelParams, RETIRED_CHANNEL_KEYS
|
|
63
|
+
│ ├── container.py # Container channel parts: resources, quantities, entries
|
|
64
|
+
│ ├── manifest.py # NormalizedManifest: what the compute agent receives
|
|
65
|
+
│ ├── probes.py # Declarative connectivity probes (proposal)
|
|
62
66
|
│ ├── documents.py # DocumentData
|
|
63
67
|
│ ├── service.py # RateLimit, ServiceConstraints, AccessInterfaceData,
|
|
64
68
|
│ │ # UpstreamAccessConfigData
|
|
@@ -70,6 +74,7 @@ src/unitysvc_core/
|
|
|
70
74
|
│ ├── promotion_v1.py # Promotion file schema + PromotionData
|
|
71
75
|
│ └── service_group_v1.py
|
|
72
76
|
├── schema/ # Generated JSON schemas (run scripts/generate_schemas.py; CI enforces sync)
|
|
77
|
+
├── instance_spec.py # validate_instance_spec / compile_instance_spec (Compose)
|
|
73
78
|
├── validator.py # DataValidator — per-file schema validation,
|
|
74
79
|
│ # union-field reference checks, API-key secret
|
|
75
80
|
│ # scanning, Jinja2 syntax validation, etc.
|
|
@@ -259,7 +264,7 @@ A policy has three kinds of entry (unitysvc/unitysvc#2770):
|
|
|
259
264
|
|
|
260
265
|
| Channel key | What it is |
|
|
261
266
|
| --- | --- |
|
|
262
|
-
| `access_method` | `http` (default), `smtp`, `s3` or `
|
|
267
|
+
| `access_method` | `http` (default), `smtp`, `s3`, `mcp` or `container`; selects the server type |
|
|
263
268
|
| `type` | normally derived by the platform; declare `enrollable` to state it |
|
|
264
269
|
| `description`, `is_active`, `sort_order` | display text; inactive channels are skipped; rank, lowest first |
|
|
265
270
|
| `request_formats`, `applicable_interfaces` | the formats the channel serves; the interfaces that reach it (display only) |
|
|
@@ -267,12 +272,82 @@ A policy has three kinds of entry (unitysvc/unitysvc#2770):
|
|
|
267
272
|
| `customer_access_requests` | what the enrolling customer is asked to approve (see above) |
|
|
268
273
|
| `params` | the enrollment parameters (below) |
|
|
269
274
|
| `request_rules` | `http` channels only: rules the gateway answers itself before dispatch (below) |
|
|
270
|
-
| `servers` | the connection: `HttpServer`, `SmtpServer`, `S3Server` or `McpServer` |
|
|
275
|
+
| `servers` | the connection: `HttpServer`, `SmtpServer`, `S3Server` or `McpServer` (a `container` channel's are `HttpServer`s) |
|
|
276
|
+
| `resources`, `entries` | `container` channels only: the tier's resources and its entries (below) |
|
|
271
277
|
|
|
272
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.
|
|
273
279
|
|
|
274
280
|
Unknown keys are refused. Retired keys are refused with what to do instead (`RETIRED_CHANNEL_KEYS`): `raw`, `is_primary`, the listing-style parameter trio, `grants`, `rate_limits` (nothing reads it; use `rate_limit_refs`), `storage_type` (use `access_method: s3`), `response_rules`, `timeout_ms`, `transport`, and the platform-derived `customer_secrets_required` / `customer_secrets_optional`.
|
|
275
281
|
|
|
282
|
+
### Container channels
|
|
283
|
+
|
|
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
|
+
|
|
286
|
+
```json
|
|
287
|
+
"service_type": "container",
|
|
288
|
+
"instance_spec": "compose.yaml",
|
|
289
|
+
"upstream_access_config": {
|
|
290
|
+
"base": {
|
|
291
|
+
"access_method": "container",
|
|
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
|
+
]
|
|
298
|
+
}
|
|
299
|
+
}
|
|
300
|
+
```
|
|
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.
|
|
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.
|
|
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).
|
|
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).
|
|
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).
|
|
307
|
+
- `params` and `customer_access_requests` are as on the other channels.
|
|
308
|
+
|
|
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.
|
|
325
|
+
|
|
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).
|
|
327
|
+
|
|
328
|
+
| Bucket | Features |
|
|
329
|
+
| --- | --- |
|
|
330
|
+
| Honor | `image` (a literal digest: `name:tag@sha256:...`), `command`, `entrypoint`, `environment`, `ports` (container side only), `healthcheck`, `working_dir`, `user`, `read_only` |
|
|
331
|
+
| Ignore, warn | `container_name`, `restart`, `labels`, `logging`, `networks`, the host side of `ports`, `expose`, `profiles`, `links`, `x-*`, `deploy.resources`, top-level `name`, `version`, `networks` |
|
|
332
|
+
| Ignore, warn loudly | `depends_on` (no start ordering: the app must retry; readiness keeps traffic away), named volumes (scratch space: data does not survive a restart) |
|
|
333
|
+
| Reject | `build`, `privileged`, `cap_add`, `devices`, `network_mode`, `pid`, `ipc`, `security_opt`, `sysctls`, bind mounts and host paths, `volumes_from`, a named volume shared by two services, `runtime`, `extra_hosts`, `env_file`, `secrets`, `configs`, `extends`, `include`, an unpinned `image`, two services that share no network, any other key |
|
|
334
|
+
|
|
335
|
+
A seller can keep one file for local Docker and the platform: write `image` as `name:tag@sha256:...` (Compose runs the digest) and leave `deploy.resources` in place. Sibling services reach each other by name (`redis:6379`); service names must be DNS labels. `${VAR}` in an `environment` value is kept as written with a warning (how a secret or parameter binds to it is open question 4 of #105); in `image` and `ports` a variable is an error.
|
|
336
|
+
|
|
337
|
+
**Validating.** `validate_instance_spec(text, format="compose", channel=ContainerChannel | None)` returns an `InstanceSpecReport` of `errors` and `warnings`, each an `InstanceSpecIssue(code, path, message, loud)`; with the channel it also checks that every entry targets a declared service and port and that `resources.services` names the spec's services. It never raises on bad input. The seller CLI and backend ingest call it, directly or through `DataValidator`: `validate_service` / `validate_data_file` report the errors of every container channel's spec under `upstream_access_config.<channel>.instance_spec`, and `DataValidator.service_warnings(offering, service_dir)` returns the warnings (`issue.loud` for the ones a seller must not miss) for `specs validate` to print after the errors.
|
|
338
|
+
|
|
339
|
+
**The normalized manifest** is what the agent receives for one instance: the compiled, validated spec. `NormalizedManifest` (JSON Schema `schema/normalized_manifest_v1.json`, which the agent repo vendors) has one service per Compose service with `name`, `image`, `ports`, `env`, `command`, `args`, `resources` (`requests`, `limits`), `replicas` and `health`, in the shapes of the agent's `intent.go`. `compile_instance_spec(text, resources)` returns a `CompiledInstanceSpec`: the manifest, the keys it `dropped` and the warnings. Compose `entrypoint` becomes `command` and Compose `command` becomes `args`; `healthcheck` becomes an `exec` `health` (`interval`, `timeout`, `retries` and `start_period` map to `period_seconds`, `timeout_seconds`, `failure_threshold` and `start_period_seconds`) (bounded as the agent bounds them: period and timeout 1-300 s, retries 1-30, start period at most its default 120 s progress deadline); the tier `resources` go to the single service, or are split by `resources.services`. That core compiles at all is a proposal (open question 3 of #105). `working_dir`, `user`, `read_only` and the scratch volumes are accepted by the policy but the agent's current manifest has no field for them: they are recorded in `dropped` with reason `not_carried` and a warning.
|
|
340
|
+
|
|
341
|
+
**The connectivity test is derived.** `validate_connectivity_test_exists` exempts an offering whose channels are all `container`, as it does an external app: the platform starts the services, waits for each one's `health` (or the default TCP check), fetches each entry expecting a success status, and shuts down. A seller may add a declarative `connectivity_test` Document (a `.json` file, `ProbesV1`, schema `schema/probes_v1.json`; a **proposal**), a list of probes run on top of the derived checks:
|
|
342
|
+
|
|
343
|
+
```json
|
|
344
|
+
{"probes": [{"entry": "web", "path": "/", "expect_status": 200, "expect_body_contains": "healthy"}]}
|
|
345
|
+
```
|
|
346
|
+
|
|
347
|
+
Each `entry` must name an entry of the offering's container channels. A script (any other file) is run as before. Core publishes the schema and fixtures (`tests/fixtures/probes`); the runners live in unitysvc-sellers and unitysvc-compute-k8s. The derived test is only as strict as `health`.
|
|
348
|
+
|
|
349
|
+
Examples: `tests/example_data/hashicorp/services/echo` (one service, two tiers) and `tests/example_data/kadxy/services/weixin-ilink-gateway` (secrets, scratch state, outbound traffic; its image digest is a marked placeholder and its original `docker-compose.yaml` is a negative test).
|
|
350
|
+
|
|
276
351
|
### Request rules
|
|
277
352
|
|
|
278
353
|
An `http` channel may list up to 32 `request_rules` (unitysvc/unitysvc#2947, unitysvc/apisix-gateways#94). The gateway checks them in order after authentication, channel selection and rate limiting and before anything is dispatched. The first rule whose `when` holds answers with its static `respond`, and the request goes no further; when none holds, the request continues unchanged. A rule without `when` answers every request.
|
|
@@ -285,7 +360,7 @@ An `http` channel may list up to 32 `request_rules` (unitysvc/unitysvc#2947, uni
|
|
|
285
360
|
]
|
|
286
361
|
```
|
|
287
362
|
|
|
288
|
-
`when` is a Lua expression that the gateway compiles and evaluates against the request. Its environment (the request's `body`, `header`, `query` and `method`, the approved functions), its template references (`${ customer_secrets.NAME ?? }`, `${ secrets.NAME }`, `{{ params.NAME }}`, `{{ enrollment.code }}`, bound as values and never spliced into the source; a secret may only
|
|
363
|
+
`when` is a Lua expression that the gateway compiles and evaluates against the request. Its environment (the request's `body`, `header`, `query` and `method`, the approved functions), its template references (`${ customer_secrets.NAME ?? }`, `${ secrets.NAME }`, `{{ params.NAME }}`, `{{ enrollment.code }}`, bound as values and never spliced into the source; a resolved secret is an ordinary value the approved functions may inspect, so anchor a substring test on a secret so that only a whole value can match) and its limits are the gateway's, documented in apisix-gateways' README. Core does not parse it: it checks only that it is non-empty and at most 1024 bytes. Lua syntax errors and invalid references are reported by the gateway (the channel answers 503) and by a gateway-run test (`services run-tests`), not by `specs validate`.
|
|
289
364
|
|
|
290
365
|
`respond` takes a `status` (200–599), an optional `body` (an object or array is sent as JSON; a string needs `content_type`), and optional `headers` (not the gateway-managed or hop-by-hop ones).
|
|
291
366
|
|
|
@@ -24,6 +24,9 @@ src/unitysvc_core/
|
|
|
24
24
|
│ │ # Pricing union, validate_pricing, cost calculation
|
|
25
25
|
│ ├── channel.py # UpstreamAccessConfig, ChannelConfig, per-protocol
|
|
26
26
|
│ │ # servers, ChannelParams, RETIRED_CHANNEL_KEYS
|
|
27
|
+
│ ├── container.py # Container channel parts: resources, quantities, entries
|
|
28
|
+
│ ├── manifest.py # NormalizedManifest: what the compute agent receives
|
|
29
|
+
│ ├── probes.py # Declarative connectivity probes (proposal)
|
|
27
30
|
│ ├── documents.py # DocumentData
|
|
28
31
|
│ ├── service.py # RateLimit, ServiceConstraints, AccessInterfaceData,
|
|
29
32
|
│ │ # UpstreamAccessConfigData
|
|
@@ -35,6 +38,7 @@ src/unitysvc_core/
|
|
|
35
38
|
│ ├── promotion_v1.py # Promotion file schema + PromotionData
|
|
36
39
|
│ └── service_group_v1.py
|
|
37
40
|
├── schema/ # Generated JSON schemas (run scripts/generate_schemas.py; CI enforces sync)
|
|
41
|
+
├── instance_spec.py # validate_instance_spec / compile_instance_spec (Compose)
|
|
38
42
|
├── validator.py # DataValidator — per-file schema validation,
|
|
39
43
|
│ # union-field reference checks, API-key secret
|
|
40
44
|
│ # scanning, Jinja2 syntax validation, etc.
|
|
@@ -224,7 +228,7 @@ A policy has three kinds of entry (unitysvc/unitysvc#2770):
|
|
|
224
228
|
|
|
225
229
|
| Channel key | What it is |
|
|
226
230
|
| --- | --- |
|
|
227
|
-
| `access_method` | `http` (default), `smtp`, `s3` or `
|
|
231
|
+
| `access_method` | `http` (default), `smtp`, `s3`, `mcp` or `container`; selects the server type |
|
|
228
232
|
| `type` | normally derived by the platform; declare `enrollable` to state it |
|
|
229
233
|
| `description`, `is_active`, `sort_order` | display text; inactive channels are skipped; rank, lowest first |
|
|
230
234
|
| `request_formats`, `applicable_interfaces` | the formats the channel serves; the interfaces that reach it (display only) |
|
|
@@ -232,12 +236,82 @@ A policy has three kinds of entry (unitysvc/unitysvc#2770):
|
|
|
232
236
|
| `customer_access_requests` | what the enrolling customer is asked to approve (see above) |
|
|
233
237
|
| `params` | the enrollment parameters (below) |
|
|
234
238
|
| `request_rules` | `http` channels only: rules the gateway answers itself before dispatch (below) |
|
|
235
|
-
| `servers` | the connection: `HttpServer`, `SmtpServer`, `S3Server` or `McpServer` |
|
|
239
|
+
| `servers` | the connection: `HttpServer`, `SmtpServer`, `S3Server` or `McpServer` (a `container` channel's are `HttpServer`s) |
|
|
240
|
+
| `resources`, `entries` | `container` channels only: the tier's resources and its entries (below) |
|
|
236
241
|
|
|
237
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.
|
|
238
243
|
|
|
239
244
|
Unknown keys are refused. Retired keys are refused with what to do instead (`RETIRED_CHANNEL_KEYS`): `raw`, `is_primary`, the listing-style parameter trio, `grants`, `rate_limits` (nothing reads it; use `rate_limit_refs`), `storage_type` (use `access_method: s3`), `response_rules`, `timeout_ms`, `transport`, and the platform-derived `customer_secrets_required` / `customer_secrets_optional`.
|
|
240
245
|
|
|
246
|
+
### Container channels
|
|
247
|
+
|
|
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
|
+
|
|
250
|
+
```json
|
|
251
|
+
"service_type": "container",
|
|
252
|
+
"instance_spec": "compose.yaml",
|
|
253
|
+
"upstream_access_config": {
|
|
254
|
+
"base": {
|
|
255
|
+
"access_method": "container",
|
|
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
|
+
]
|
|
262
|
+
}
|
|
263
|
+
}
|
|
264
|
+
```
|
|
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.
|
|
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.
|
|
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).
|
|
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).
|
|
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).
|
|
271
|
+
- `params` and `customer_access_requests` are as on the other channels.
|
|
272
|
+
|
|
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.
|
|
289
|
+
|
|
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).
|
|
291
|
+
|
|
292
|
+
| Bucket | Features |
|
|
293
|
+
| --- | --- |
|
|
294
|
+
| Honor | `image` (a literal digest: `name:tag@sha256:...`), `command`, `entrypoint`, `environment`, `ports` (container side only), `healthcheck`, `working_dir`, `user`, `read_only` |
|
|
295
|
+
| Ignore, warn | `container_name`, `restart`, `labels`, `logging`, `networks`, the host side of `ports`, `expose`, `profiles`, `links`, `x-*`, `deploy.resources`, top-level `name`, `version`, `networks` |
|
|
296
|
+
| Ignore, warn loudly | `depends_on` (no start ordering: the app must retry; readiness keeps traffic away), named volumes (scratch space: data does not survive a restart) |
|
|
297
|
+
| Reject | `build`, `privileged`, `cap_add`, `devices`, `network_mode`, `pid`, `ipc`, `security_opt`, `sysctls`, bind mounts and host paths, `volumes_from`, a named volume shared by two services, `runtime`, `extra_hosts`, `env_file`, `secrets`, `configs`, `extends`, `include`, an unpinned `image`, two services that share no network, any other key |
|
|
298
|
+
|
|
299
|
+
A seller can keep one file for local Docker and the platform: write `image` as `name:tag@sha256:...` (Compose runs the digest) and leave `deploy.resources` in place. Sibling services reach each other by name (`redis:6379`); service names must be DNS labels. `${VAR}` in an `environment` value is kept as written with a warning (how a secret or parameter binds to it is open question 4 of #105); in `image` and `ports` a variable is an error.
|
|
300
|
+
|
|
301
|
+
**Validating.** `validate_instance_spec(text, format="compose", channel=ContainerChannel | None)` returns an `InstanceSpecReport` of `errors` and `warnings`, each an `InstanceSpecIssue(code, path, message, loud)`; with the channel it also checks that every entry targets a declared service and port and that `resources.services` names the spec's services. It never raises on bad input. The seller CLI and backend ingest call it, directly or through `DataValidator`: `validate_service` / `validate_data_file` report the errors of every container channel's spec under `upstream_access_config.<channel>.instance_spec`, and `DataValidator.service_warnings(offering, service_dir)` returns the warnings (`issue.loud` for the ones a seller must not miss) for `specs validate` to print after the errors.
|
|
302
|
+
|
|
303
|
+
**The normalized manifest** is what the agent receives for one instance: the compiled, validated spec. `NormalizedManifest` (JSON Schema `schema/normalized_manifest_v1.json`, which the agent repo vendors) has one service per Compose service with `name`, `image`, `ports`, `env`, `command`, `args`, `resources` (`requests`, `limits`), `replicas` and `health`, in the shapes of the agent's `intent.go`. `compile_instance_spec(text, resources)` returns a `CompiledInstanceSpec`: the manifest, the keys it `dropped` and the warnings. Compose `entrypoint` becomes `command` and Compose `command` becomes `args`; `healthcheck` becomes an `exec` `health` (`interval`, `timeout`, `retries` and `start_period` map to `period_seconds`, `timeout_seconds`, `failure_threshold` and `start_period_seconds`) (bounded as the agent bounds them: period and timeout 1-300 s, retries 1-30, start period at most its default 120 s progress deadline); the tier `resources` go to the single service, or are split by `resources.services`. That core compiles at all is a proposal (open question 3 of #105). `working_dir`, `user`, `read_only` and the scratch volumes are accepted by the policy but the agent's current manifest has no field for them: they are recorded in `dropped` with reason `not_carried` and a warning.
|
|
304
|
+
|
|
305
|
+
**The connectivity test is derived.** `validate_connectivity_test_exists` exempts an offering whose channels are all `container`, as it does an external app: the platform starts the services, waits for each one's `health` (or the default TCP check), fetches each entry expecting a success status, and shuts down. A seller may add a declarative `connectivity_test` Document (a `.json` file, `ProbesV1`, schema `schema/probes_v1.json`; a **proposal**), a list of probes run on top of the derived checks:
|
|
306
|
+
|
|
307
|
+
```json
|
|
308
|
+
{"probes": [{"entry": "web", "path": "/", "expect_status": 200, "expect_body_contains": "healthy"}]}
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
Each `entry` must name an entry of the offering's container channels. A script (any other file) is run as before. Core publishes the schema and fixtures (`tests/fixtures/probes`); the runners live in unitysvc-sellers and unitysvc-compute-k8s. The derived test is only as strict as `health`.
|
|
312
|
+
|
|
313
|
+
Examples: `tests/example_data/hashicorp/services/echo` (one service, two tiers) and `tests/example_data/kadxy/services/weixin-ilink-gateway` (secrets, scratch state, outbound traffic; its image digest is a marked placeholder and its original `docker-compose.yaml` is a negative test).
|
|
314
|
+
|
|
241
315
|
### Request rules
|
|
242
316
|
|
|
243
317
|
An `http` channel may list up to 32 `request_rules` (unitysvc/unitysvc#2947, unitysvc/apisix-gateways#94). The gateway checks them in order after authentication, channel selection and rate limiting and before anything is dispatched. The first rule whose `when` holds answers with its static `respond`, and the request goes no further; when none holds, the request continues unchanged. A rule without `when` answers every request.
|
|
@@ -250,7 +324,7 @@ An `http` channel may list up to 32 `request_rules` (unitysvc/unitysvc#2947, uni
|
|
|
250
324
|
]
|
|
251
325
|
```
|
|
252
326
|
|
|
253
|
-
`when` is a Lua expression that the gateway compiles and evaluates against the request. Its environment (the request's `body`, `header`, `query` and `method`, the approved functions), its template references (`${ customer_secrets.NAME ?? }`, `${ secrets.NAME }`, `{{ params.NAME }}`, `{{ enrollment.code }}`, bound as values and never spliced into the source; a secret may only
|
|
327
|
+
`when` is a Lua expression that the gateway compiles and evaluates against the request. Its environment (the request's `body`, `header`, `query` and `method`, the approved functions), its template references (`${ customer_secrets.NAME ?? }`, `${ secrets.NAME }`, `{{ params.NAME }}`, `{{ enrollment.code }}`, bound as values and never spliced into the source; a resolved secret is an ordinary value the approved functions may inspect, so anchor a substring test on a secret so that only a whole value can match) and its limits are the gateway's, documented in apisix-gateways' README. Core does not parse it: it checks only that it is non-empty and at most 1024 bytes. Lua syntax errors and invalid references are reported by the gateway (the channel answers 503) and by a gateway-run test (`services run-tests`), not by `specs validate`.
|
|
254
328
|
|
|
255
329
|
`respond` takes a `status` (200–599), an optional `body` (an object or array is sent as JSON; a string needs `content_type`), and optional `headers` (not the gateway-managed or hop-by-hop ones).
|
|
256
330
|
|
|
@@ -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.11"
|
|
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" }]
|
|
@@ -17,6 +17,7 @@ classifiers = [
|
|
|
17
17
|
"Typing :: Typed",
|
|
18
18
|
]
|
|
19
19
|
dependencies = [
|
|
20
|
+
"pyyaml",
|
|
20
21
|
"pydantic>=2",
|
|
21
22
|
"email-validator",
|
|
22
23
|
"jsonschema>=4.18",
|
|
@@ -218,6 +218,10 @@ RESOURCES: dict[str, Exports] = {
|
|
|
218
218
|
},
|
|
219
219
|
},
|
|
220
220
|
),
|
|
221
|
+
# A container instance of the channel's tier (the ``container`` channel,
|
|
222
|
+
# ``access_method: "container"``): the customer may be given one to run.
|
|
223
|
+
# It has no options; its size is the channel's ``resources``.
|
|
224
|
+
"container": Exports({"create": ()}, {}),
|
|
221
225
|
}
|
|
222
226
|
|
|
223
227
|
_REQUEST_KEYS = frozenset({"object", "permissions", "required", "justification", "options", "limits"})
|
|
@@ -504,8 +508,10 @@ def validate_access_requests(
|
|
|
504
508
|
if resource:
|
|
505
509
|
exports = RESOURCES[name]
|
|
506
510
|
check_resource(at, obj, permissions, options, entry.get("limits"))
|
|
507
|
-
if
|
|
508
|
-
|
|
511
|
+
if name == "room" and (
|
|
512
|
+
kind := next(
|
|
513
|
+
(o[ROOM_KIND] for other, o, _ in seen if other == obj and o[ROOM_KIND] == options[ROOM_KIND]), None
|
|
514
|
+
)
|
|
509
515
|
):
|
|
510
516
|
raise ValueError(f"{at}: {obj} with {ROOM_KIND}={kind} is listed twice; a kind is requested once")
|
|
511
517
|
elif resolve is not None:
|
|
@@ -632,6 +638,8 @@ def check_resource(where: str, obj: str, permissions: list[str], options: dict[s
|
|
|
632
638
|
check_claim(where, obj, permissions, options, RESOURCES[obj.removeprefix(RESOURCE_PREFIX)])
|
|
633
639
|
if limits:
|
|
634
640
|
raise ValueError(f"{where}.limits: {obj} is provisioned, not called; it takes no limits")
|
|
641
|
+
if obj != f"{RESOURCE_PREFIX}room":
|
|
642
|
+
return
|
|
635
643
|
kind = options.get(ROOM_KIND)
|
|
636
644
|
if kind is None:
|
|
637
645
|
raise ValueError(
|