unitysvc-core 0.2.32__tar.gz → 0.2.34__tar.gz

{unitysvc_core-0.2.32/src/unitysvc_core.egg-info → unitysvc_core-0.2.34}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: unitysvc-core
-Version: 0.2.32
+Version: 0.2.34
 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,16 @@ moved to `unitysvc-sellers`.
 ## License
 
 MIT
+
+### Required enrollment parameter usage
+
+The shared validator rejects required user parameters that no channel, interface,
+or document consumes. 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.32 → unitysvc_core-0.2.34}/README.md

@@ -97,3 +97,16 @@ moved to `unitysvc-sellers`.
 ## License
 
 MIT
+
+### Required enrollment parameter usage
+
+The shared validator rejects required user parameters that no channel, interface,
+or document consumes. 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.32 → unitysvc_core-0.2.34}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "unitysvc-core"
-version = "0.2.32"
+version = "0.2.34"
 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.32 → unitysvc_core-0.2.34}/src/unitysvc_core/models/base.py

@@ -281,6 +281,11 @@ class RequestTransformEnum(StrEnum):
     # the gateway auto-detects the incoming format and translates in-process only
     # when needed (#923/#929/#1400). Replaces the earlier ``llm_translate`` key.
     llm_translator = "llm_translator"
+    # Normalize a `msg` envelope (title, body, links, attachment, format) for
+    # the destination channel's declared capabilities, optionally mapping the
+    # result into the upstream body. Runs before body_transformer, which can
+    # template the normalized msg (unitysvc/unitysvc#2650).
+    msg_transformer = "msg_transformer"
 
 
 class ServiceTypeEnum(StrEnum):

unitysvc_core-0.2.34/src/unitysvc_core/parameter_usage.py

@@ -0,0 +1,89 @@
+"""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.
+"""
+
+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]
+
+
+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")
+    content = {k: v for k, v in listing.items() if k not in ("user_parameters_schema", "parameters_schema")}
+    try:
+        unused = unused_required_params(schema, content, 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, interface or document. "
+        "Reference each one as {{ params.NAME }} (for example ${ customer_secrets.{{ params.NAME }} }), "
+        "or drop it from the required list."
+    ]

{unitysvc_core-0.2.32 → unitysvc_core-0.2.34}/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,31 @@ 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(listing, offering)
+        return []
+
     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.32 → unitysvc_core-0.2.34/src/unitysvc_core.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: unitysvc-core
-Version: 0.2.32
+Version: 0.2.34
 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,16 @@ moved to `unitysvc-sellers`.
 ## License
 
 MIT
+
+### Required enrollment parameter usage
+
+The shared validator rejects required user parameters that no channel, interface,
+or document consumes. 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.32 → unitysvc_core-0.2.34}/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.34/tests/test_parameter_usage.py

@@ -0,0 +1,121 @@
+"""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 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]
+
+
+def test_partial_use_is_rejected():
+    errors = validate_required_parameter_usage(listing(), {"host": "{{ 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": {"body": "{{ params.token }}"}})
+    assert validate_required_parameter_usage(data, {"host": "{{ params.host }}"}) == []
+    assert (
+        validate_required_parameter_usage(
+            listing(user_access_interfaces={"url": "{{ params.host }}"}, documents={"body": "{{ params.token }}"}), {}
+        )
+        == []
+    )
+
+
+def test_required_parameter_can_have_punctuation_in_its_name():
+    assert (
+        validate_required_parameter_usage(
+            listing(user_parameters_schema={"required": ["host-name"]}), {"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({"host": "{{ params.host }}", "token": "{{ params.token }}"})
+        if suffix == "json"
+        else 'host = "{{ params.host }}"\ntoken = "{{ params.token }}"\n'
+    )
+    assert validator.validate_required_parameter_usage(data, tmp_path / "listing.json") == []
+
+
+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(), {"host": "{{ params.host"})
+    assert "invalid Jinja template" in errors[0]

{unitysvc_core-0.2.32 → unitysvc_core-0.2.34}/tests/test_validators.py

@@ -675,3 +675,11 @@ class TestPlatformListingBaseUrls:
     def test_requires_the_address(self, value) -> None:
         errors = validate_platform_listing_base_urls(value)
         assert len(errors) == 1 and "/p/<route>" in errors[0]
+
+
+def test_request_transformer_enum_has_msg_transformer():
+    """The gateway's msg_transformer key must be a valid request_transformer
+    key, or the backend rejects routes that use it (unitysvc/unitysvc#2650)."""
+    from unitysvc_core.models import RequestTransformEnum
+
+    assert RequestTransformEnum("msg_transformer") is RequestTransformEnum.msg_transformer