unitysvc-core 0.2.33__tar.gz → 0.2.35__tar.gz

{unitysvc_core-0.2.33/src/unitysvc_core.egg-info → unitysvc_core-0.2.35}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: unitysvc-core
-Version: 0.2.33
+Version: 0.2.35
 Summary: Shared data models and validation helpers for UnitySVC packages
 Author-email: Bo Peng <bo.peng@unitysvc.com>
 Maintainer-email: Bo Peng <bo.peng@unitysvc.com>
@@ -132,3 +132,20 @@ moved to `unitysvc-sellers`.
 ## License
 
 MIT
+
+### Required enrollment parameter usage
+
+The shared validator rejects required user parameters that no channel, interface,
+or document consumes. Only those consumer fields count — the offering's
+`upstream_access_config`, the listing's `user_access_interfaces`, and document
+content (a `.j2` document's template source, which the seller validator reads from
+disk as the SDK uploads it); metadata such as `display_name` or `description` is
+never rendered with `params`. File validation checks a listing against its paired offering
+when present; backend ingest calls the same `validate_required_parameter_usage`
+helper with the complete listing and offering. Schema declarations alone are not
+consumers. Jinja attribute access, string-key lookups, and `params.get("name")`
+are inspected; dynamic access and whole-map iteration conservatively consume all
+parameters. Deprecated content can still be retired.
+
+This validates usage, not channel attribution: a document reference counts as a
+consumer without proving that the intended paid channel takes enrollment.

{unitysvc_core-0.2.33 → unitysvc_core-0.2.35}/README.md

@@ -97,3 +97,20 @@ moved to `unitysvc-sellers`.
 ## License
 
 MIT
+
+### Required enrollment parameter usage
+
+The shared validator rejects required user parameters that no channel, interface,
+or document consumes. Only those consumer fields count — the offering's
+`upstream_access_config`, the listing's `user_access_interfaces`, and document
+content (a `.j2` document's template source, which the seller validator reads from
+disk as the SDK uploads it); metadata such as `display_name` or `description` is
+never rendered with `params`. File validation checks a listing against its paired offering
+when present; backend ingest calls the same `validate_required_parameter_usage`
+helper with the complete listing and offering. Schema declarations alone are not
+consumers. Jinja attribute access, string-key lookups, and `params.get("name")`
+are inspected; dynamic access and whole-map iteration conservatively consume all
+parameters. Deprecated content can still be retired.
+
+This validates usage, not channel attribution: a document reference counts as a
+consumer without proving that the intended paid channel takes enrollment.

{unitysvc_core-0.2.33 → unitysvc_core-0.2.35}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "unitysvc-core"
-version = "0.2.33"
+version = "0.2.35"
 description = "Shared data models and validation helpers for UnitySVC packages"
 readme = "README.md"
 authors = [{ name = "Bo Peng", email = "bo.peng@unitysvc.com" }]

unitysvc_core-0.2.35/src/unitysvc_core/parameter_usage.py

@@ -0,0 +1,120 @@
+"""Shared cross-file validation of required enrollment parameter usage.
+
+This checks that required parameters have consumers. It does not prove that
+an intended enrollment channel consumes them; interface/document use counts.
+
+Only the fields the platform renders with an enrollment's ``params`` are
+consumers: the offering's channels (``upstream_access_config``), the listing's
+interfaces (``user_access_interfaces``) and document content. Metadata such as
+``display_name`` or ``description`` is never rendered with ``params``, so a
+reference there does not count (unitysvc/unitysvc#2649).
+"""
+
+from typing import Any
+
+from jinja2 import Environment, TemplateSyntaxError, nodes
+
+_ENV = Environment()
+
+
+def referenced_param_names(value: Any) -> set[str] | None:
+    """Names read from ``params`` in Jinja, or None for dynamic/whole-map use.
+
+    Literal strings/comments are not references. Dictionary iteration and
+    dynamic lookups conservatively count as consuming all parameters.
+    """
+    names: set[str] = set()
+    if isinstance(value, str):
+        if "{{" not in value and "{%" not in value:
+            return names
+        tree = _ENV.parse(value)
+        parents = {id(child): parent for parent in tree.find_all(nodes.Node) for child in parent.iter_child_nodes()}
+        for node in tree.find_all(nodes.Name):
+            if node.name != "params" or node.ctx != "load":
+                continue
+            parent = parents.get(id(node))
+            if isinstance(parent, nodes.Getitem) and isinstance(parent.arg, nodes.Const):
+                if isinstance(parent.arg.value, str):
+                    names.add(parent.arg.value)
+                    continue
+            if isinstance(parent, nodes.Getattr):
+                call = parents.get(id(parent))
+                if isinstance(call, nodes.Call) and call.node is parent:
+                    if parent.attr == "get" and call.args and isinstance(call.args[0], nodes.Const):
+                        if isinstance(call.args[0].value, str):
+                            names.add(call.args[0].value)
+                            continue
+                    return None
+                names.add(parent.attr)
+                continue
+            return None
+        return names
+    items = value.values() if isinstance(value, dict) else value if isinstance(value, (list, tuple)) else ()
+    for item in items:
+        found = referenced_param_names(item)
+        if found is None:
+            return None
+        names |= found
+    return names
+
+
+def unused_required_params(parameters_schema: dict[str, Any] | None, *sources: Any) -> list[str]:
+    """Required names that no source consumes (schema declarations are not sources)."""
+    required = (parameters_schema or {}).get("required") or []
+    if not required:
+        return []
+    used: set[str] = set()
+    for source in sources:
+        names = referenced_param_names(source)
+        if names is None:
+            return []
+        used |= names
+    return [name for name in required if name not in used]
+
+
+# Keys of a document entry that hold its rendered content. Backend ingest sees
+# a ``.j2`` document's template source inlined as ``file_content``; the seller
+# validator inlines the same file before calling this module.
+_DOCUMENT_CONTENT_KEYS = ("file_content", "content")
+
+
+def _document_contents(documents: Any) -> list[str]:
+    entries = documents.values() if isinstance(documents, dict) else documents if isinstance(documents, list) else ()
+    out: list[str] = []
+    for doc in entries:
+        if isinstance(doc, dict):
+            out.extend(doc[key] for key in _DOCUMENT_CONTENT_KEYS if isinstance(doc.get(key), str))
+    return out
+
+
+def consumer_sources(listing: dict[str, Any], offering: dict[str, Any]) -> list[Any]:
+    """The parts of a service the platform renders with enrollment ``params``."""
+    return [
+        offering.get("upstream_access_config"),
+        listing.get("user_access_interfaces"),
+        _document_contents(listing.get("documents")),
+        _document_contents(offering.get("documents")),
+    ]
+
+
+def validate_required_parameter_usage(listing: dict[str, Any], offering: dict[str, Any]) -> list[str]:
+    """Return hard validation errors, shared by seller validation and backend ingest.
+
+    Deprecated content can still be retired. Referencing a parameter in a
+    document satisfies usage without guaranteeing correct channel attribution.
+    """
+    if listing.get("status") == "deprecated" or offering.get("status") == "deprecated":
+        return []
+    schema = listing.get("user_parameters_schema") or listing.get("parameters_schema")
+    try:
+        unused = unused_required_params(schema, *consumer_sources(listing, offering))
+    except TemplateSyntaxError as exc:
+        return [f"Cannot validate required parameter usage: invalid Jinja template: {exc}"]
+    if not unused:
+        return []
+    return [
+        f"Required user parameter(s) {', '.join(unused)} are used by no channel (upstream_access_config), "
+        "interface (user_access_interfaces) or document content. "
+        "Reference each one as {{ params.NAME }} (for example ${ customer_secrets.{{ params.NAME }} }), "
+        "or drop it from the required list."
+    ]

{unitysvc_core-0.2.33 → unitysvc_core-0.2.35}/src/unitysvc_core/validator.py

@@ -10,6 +10,7 @@ from urllib.parse import urlparse
 from jinja2 import Environment, StrictUndefined, TemplateSyntaxError, UndefinedError
 from jsonschema.validators import Draft7Validator
 
+from .parameter_usage import validate_required_parameter_usage
 from .utils import SCHEMA_TO_STEM, is_hidden_path, load_data_file, schema_for_path
 
 # ``details.model``: a provider-neutral model name (``glm-5.2``, not
@@ -1004,10 +1005,55 @@ class DataValidator:
             errors.extend(validate_listing_smtp_base_urls(uai))
             errors.extend(validate_listing_mcp_base_urls(uai))
             errors.extend(validate_listing_jinja_var_references(data))
+            errors.extend(self.validate_required_parameter_usage(data, file_path))
             errors.extend(self.validate_listing_name_namespace(data, file_path))
 
         return len(errors) == 0, errors
 
+    def validate_required_parameter_usage(self, listing: dict[str, Any], file_path: Path) -> list[str]:
+        """Check the listing against its paired offering, after overrides/presets.
+
+        Standalone listings without an offering cannot establish cross-file
+        usage; full service uploads are always checked by backend ingest too.
+        """
+        schema = listing.get("user_parameters_schema") or listing.get("parameters_schema")
+        if not isinstance(schema, dict) or not schema.get("required"):
+            return []
+        for candidate in sorted(file_path.parent.glob("offering*.*")):
+            if candidate.suffix not in (".json", ".toml") or ".override." in candidate.name:
+                continue
+            try:
+                offering, _ = load_data_file(candidate)
+            except Exception as exc:
+                return [f"Cannot check required parameter usage: {exc}"]
+            if isinstance(offering, dict) and (offering.get("schema") == "offering_v1" or candidate.stem == "offering"):
+                return validate_required_parameter_usage(
+                    self._with_template_documents(listing, file_path.parent),
+                    self._with_template_documents(offering, candidate.parent),
+                )
+        return []
+
+    @staticmethod
+    def _with_template_documents(data: dict[str, Any], base_dir: Path) -> dict[str, Any]:
+        """``data`` with each ``.j2`` document's template source inlined as
+        ``file_content``, as the seller SDK uploads it — so the seller check
+        sees the same document content backend ingest does."""
+        documents = data.get("documents")
+        if not isinstance(documents, dict):
+            return data
+        inlined: dict[str, Any] = {}
+        for title, doc in documents.items():
+            if isinstance(doc, dict) and "file_content" not in doc:
+                rel = doc.get("file_path")
+                if isinstance(rel, str) and rel.endswith(".j2"):
+                    path = Path(rel) if Path(rel).is_absolute() else base_dir / rel
+                    try:
+                        doc = {**doc, "file_content": path.read_text(encoding="utf-8")}
+                    except OSError:
+                        pass  # a missing file is reported by the file-reference checks
+            inlined[title] = doc
+        return {**data, "documents": inlined}
+
     def _resolve_provider_name(self, file_path: Path) -> str | None:
         """Find the provider name (``provider_v1.name``) governing a listing file.
 

{unitysvc_core-0.2.33 → unitysvc_core-0.2.35/src/unitysvc_core.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: unitysvc-core
-Version: 0.2.33
+Version: 0.2.35
 Summary: Shared data models and validation helpers for UnitySVC packages
 Author-email: Bo Peng <bo.peng@unitysvc.com>
 Maintainer-email: Bo Peng <bo.peng@unitysvc.com>
@@ -132,3 +132,20 @@ moved to `unitysvc-sellers`.
 ## License
 
 MIT
+
+### Required enrollment parameter usage
+
+The shared validator rejects required user parameters that no channel, interface,
+or document consumes. Only those consumer fields count — the offering's
+`upstream_access_config`, the listing's `user_access_interfaces`, and document
+content (a `.j2` document's template source, which the seller validator reads from
+disk as the SDK uploads it); metadata such as `display_name` or `description` is
+never rendered with `params`. File validation checks a listing against its paired offering
+when present; backend ingest calls the same `validate_required_parameter_usage`
+helper with the complete listing and offering. Schema declarations alone are not
+consumers. Jinja attribute access, string-key lookups, and `params.get("name")`
+are inspected; dynamic access and whole-map iteration conservatively consume all
+parameters. Deprecated content can still be retired.
+
+This validates usage, not channel attribution: a document reference counts as a
+consumer without proving that the intended paid channel takes enrollment.

{unitysvc_core-0.2.33 → unitysvc_core-0.2.35}/src/unitysvc_core.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ LICENSE
 README.md
 pyproject.toml
 src/unitysvc_core/__init__.py
+src/unitysvc_core/parameter_usage.py
 src/unitysvc_core/py.typed
 src/unitysvc_core/utils.py
 src/unitysvc_core/validator.py
@@ -34,6 +35,7 @@ tests/test_access_interface_routing.py
 tests/test_effective_price.py
 tests/test_hidden_path_skip.py
 tests/test_offering_data.py
+tests/test_parameter_usage.py
 tests/test_pricing.py
 tests/test_provider_account_rate_limits.py
 tests/test_service_group.py

unitysvc_core-0.2.35/tests/test_parameter_usage.py

@@ -0,0 +1,185 @@
+"""Required enrollment parameters must have consumers across service data."""
+
+import json
+from pathlib import Path
+
+import pytest
+
+from unitysvc_core.parameter_usage import referenced_param_names, validate_required_parameter_usage
+from unitysvc_core.validator import DataValidator
+
+
+@pytest.mark.parametrize("expression", ["params.name", "params['name']", 'params.get("name")'])
+def test_named_reads(expression):
+    assert referenced_param_names("{{ " + expression + " }}") == {"name"}
+
+
+@pytest.mark.parametrize(
+    "expression",
+    [
+        "params",
+        "params | tojson",
+        "params.items()",
+        "params.keys()",
+        "params.values()",
+        "params.get(key)",
+        "params[key]",
+    ],
+)
+def test_dynamic_and_whole_map_reads(expression):
+    assert referenced_param_names("{{ " + expression + " }}") is None
+
+
+def test_strings_comments_and_non_template_text_are_not_consumers():
+    assert referenced_param_names(["params.name", "{# params.name #}", '{{ "params.name" }}']) == set()
+
+
+def listing(**changes):
+    return {"status": "ready", "user_parameters_schema": {"required": ["host", "token"]}, **changes}
+
+
+def channel(**fields):
+    """An offering whose one channel carries ``fields``."""
+    return {"upstream_access_config": {"plus": fields}}
+
+
+def test_required_names_in_the_schema_do_not_count_as_use():
+    errors = validate_required_parameter_usage(
+        listing(), {"upstream_access_config": {"free": {"api_key": "${ customer_secrets.TOKEN }"}}}
+    )
+    assert len(errors) == 1
+    assert "host, token are used by no channel" in errors[0]
+
+
+@pytest.mark.parametrize(
+    ("listing_changes", "offering"),
+    [
+        ({"display_name": "{{ params.host }} {{ params.token }}"}, {}),
+        ({"description": "{{ params.host }}", "summary": "{{ params.token }}"}, {}),
+        ({}, {"description": "{{ params.host }} {{ params.token }}", "name": "{{ params.host }}"}),
+        # a document's metadata is not its content
+        ({"documents": {"Doc": {"description": "{{ params.host }} {{ params.token }}"}}}, {}),
+        ({"service_options": {"note": "{{ params.host }} {{ params.token }}"}}, {}),
+    ],
+)
+def test_metadata_is_not_a_consumer(listing_changes, offering):
+    """Only channels, interfaces and document content are rendered with
+    params; a reference anywhere else must not satisfy the rule (#2649)."""
+    errors = validate_required_parameter_usage(listing(**listing_changes), offering)
+    assert len(errors) == 1
+    assert "host, token are used by no channel" in errors[0]
+
+
+def test_dynamic_use_in_metadata_does_not_disable_the_rule():
+    errors = validate_required_parameter_usage(listing(description="{{ params | tojson }}"), {})
+    assert "host, token" in errors[0]
+
+
+def test_partial_use_is_rejected():
+    errors = validate_required_parameter_usage(listing(), channel(base_url="{{ params.host }}"))
+    assert "token are used by no channel" in errors[0]
+
+
+def test_channel_interface_and_document_reads_count_without_proving_attribution():
+    data = listing(documents={"example": {"file_content": "{{ params.token }}"}})
+    assert validate_required_parameter_usage(data, channel(base_url="{{ params.host }}")) == []
+    assert (
+        validate_required_parameter_usage(
+            listing(
+                user_access_interfaces={"canonical": {"base_url": "{{ params.host }}"}},
+                documents={"Example": {"file_content": "{{ params.token }}"}},
+            ),
+            {},
+        )
+        == []
+    )
+    # offering-level document content counts too
+    assert (
+        validate_required_parameter_usage(
+            listing(),
+            {**channel(base_url="{{ params.host }}"), "documents": {"Doc": {"file_content": "{{ params.token }}"}}},
+        )
+        == []
+    )
+
+
+def test_required_parameter_can_have_punctuation_in_its_name():
+    assert (
+        validate_required_parameter_usage(
+            listing(user_parameters_schema={"required": ["host-name"]}), channel(host="{{ params['host-name'] }}")
+        )
+        == []
+    )
+
+
+def test_deprecated_content_can_be_retired():
+    assert validate_required_parameter_usage(listing(status="deprecated"), {}) == []
+    assert validate_required_parameter_usage(listing(), {"status": "deprecated"}) == []
+
+
+def test_no_required_parameters():
+    assert validate_required_parameter_usage({}, {}) == []
+
+
+@pytest.mark.parametrize("suffix", ["json", "toml"])
+def test_file_validator_checks_paired_offering(tmp_path, suffix):
+    schema_dir = Path(__file__).parents[1] / "src/unitysvc_core/schema"
+    validator = DataValidator(tmp_path, schema_dir)
+    data = listing()
+    (tmp_path / "listing.json").write_text(json.dumps(data))
+    path = tmp_path / f"offering.{suffix}"
+    path.write_text("{}" if suffix == "json" else "")
+    errors = validator.validate_required_parameter_usage(data, tmp_path / "listing.json")
+    assert "host, token" in errors[0]
+    path.write_text(
+        json.dumps(channel(host="{{ params.host }}", token="{{ params.token }}"))
+        if suffix == "json"
+        else '[upstream_access_config.plus]\nhost = "{{ params.host }}"\ntoken = "{{ params.token }}"\n'
+    )
+    assert validator.validate_required_parameter_usage(data, tmp_path / "listing.json") == []
+
+
+def test_file_validator_reads_template_documents_like_ingest(tmp_path):
+    """The seller SDK uploads a .j2 document's source as file_content, so the
+    file validator must count a param used only there, as ingest does."""
+    schema_dir = Path(__file__).parents[1] / "src/unitysvc_core/schema"
+    validator = DataValidator(tmp_path, schema_dir)
+    (tmp_path / "offering.json").write_text(json.dumps(channel(base_url="{{ params.host }}")))
+    (tmp_path / "connectivity.sh.j2").write_text('curl "$URL" -H "X-Token: {{ params.token }}"\n')
+    data = listing(documents={"Connectivity": {"file_path": "connectivity.sh.j2", "category": "connectivity_test"}})
+    (tmp_path / "listing.json").write_text(json.dumps(data))
+    assert validator.validate_required_parameter_usage(data, tmp_path / "listing.json") == []
+    # a non-template document is uploaded as-is, never rendered: not a consumer
+    (tmp_path / "usage.md").write_text("{{ params.token }}")
+    data = listing(documents={"Usage": {"file_path": "usage.md"}})
+    errors = validator.validate_required_parameter_usage(data, tmp_path / "listing.json")
+    assert "token are used by no channel" in errors[0]
+
+
+def test_validation_pipeline_invokes_the_shared_rule(tmp_path, monkeypatch):
+    schema_dir = Path(__file__).parents[1] / "src/unitysvc_core/schema"
+    validator = DataValidator(tmp_path, schema_dir)
+    path = tmp_path / "listing.json"
+    path.write_text(json.dumps({"name": "labs/test"}))
+    calls = []
+
+    def check(data, file_path):
+        calls.append(file_path)
+        return ["unused-param-sentinel"]
+
+    monkeypatch.setattr(validator, "validate_required_parameter_usage", check)
+    valid, errors = validator.validate_data_file(path, "listing_v1")
+    assert not valid
+    assert "unused-param-sentinel" in errors
+    assert calls == [path]
+
+
+def test_invalid_jinja_does_not_bypass_the_rule():
+    errors = validate_required_parameter_usage(listing(), channel(base_url="{{ params.host"))
+    assert "invalid Jinja template" in errors[0]
+
+
+def test_invalid_jinja_in_metadata_is_ignored():
+    """Metadata is never rendered with params, so it is not parsed either."""
+    errors = validate_required_parameter_usage(listing(description="Go: {{ .Name }}"), {})
+    assert "host, token are used by no channel" in errors[0]