unitysvc-data 0.1.0__py3-none-any.whl

unitysvc_data/examples/s3/connectivity/README.md

@@ -0,0 +1,53 @@
++++
+preset_name = "s3_connectivity"
+category = "connectivity_test"
+mime_type = "python"
+file = "connectivity.py.j2"
+description = "Verify S3 endpoint accepts the configured credentials"
+is_active = true
+is_public = false
+meta = { output_contains = "connectivity ok" }
++++
+
+# s3 / connectivity — S3 credential smoke test
+
+Python smoke test that proves **credentials are accepted** by the S3
+endpoint. It does not try to access a specific bucket — the point is
+"can the user authenticate against the upstream", not "does bucket X
+exist" — so AccessDenied on a list call still counts as pass.
+
+## Branches (rendered at upload time with the listing context)
+
+| `local_testing` | `interface.access_key` | Behaviour |
+|-----------------|------------------------|-----------|
+| `true`          | present                | Signs with seller credentials and calls `list_buckets()`. |
+| `true`          | absent                 | Public bucket — prints `connectivity ok` and exits 0 without network call. |
+| `false`         | —                      | Signs with the customer's `UNITYSVC_API_KEY` via the gateway and calls `list_objects_v2(Bucket=..., MaxKeys=1)` against the gateway-resolved bucket. |
+
+## Environment variables (local mode)
+
+- `REGION`, `ACCESS_KEY`, `SECRET_KEY` — seller credentials.
+- `S3_ENDPOINT` — optional; set for non-AWS endpoints (DigitalOcean
+  Spaces, MinIO, etc.).
+
+## Environment variables (gateway mode)
+
+- `SERVICE_BASE_URL` — form: `{endpoint_prefix}/{service_slug}`. The
+  script splits on the last `/` to recover `endpoint_url` and `bucket`.
+- `UNITYSVC_API_KEY` — customer's gateway key, used as
+  `aws_access_key_id`; `aws_secret_access_key` is set to `"not-used"`
+  because the gateway ignores it.
+
+## Auth-failure classification
+
+Only these error codes are treated as genuine auth rejection:
+`InvalidAccessKeyId`, `SignatureDoesNotMatch`, `InvalidClientTokenId`,
+and any HTTP 401. Anything else (including 403 AccessDenied) means the
+signature was accepted — that's still connectivity ok.
+
+## Versions
+
+### v1 — initial release
+
+- Three-way branch on `local_testing` / `interface.access_key`.
+- Treats non-auth `ClientError` as pass.

unitysvc_data/examples/s3/connectivity/connectivity-v1.py.j2

@@ -0,0 +1,63 @@
+import boto3
+import os
+import sys
+from botocore.exceptions import BotoCoreError, ClientError
+{% if local_testing %}
+{% if interface.get("access_key") %}
+# Local testing: verify credentials are accepted by the S3 endpoint.
+# We intentionally do NOT target a specific bucket — this test is about
+# "can the user authenticate against the upstream", not "does bucket X
+# exist". list_buckets is the cheapest signed call: credentials are
+# validated regardless of whether the account is actually allowed to
+# enumerate buckets (AccessDenied on the list still proves auth worked).
+s3_kwargs = {
+    'region_name': os.environ['REGION'],
+    'aws_access_key_id': os.environ['ACCESS_KEY'],
+    'aws_secret_access_key': os.environ['SECRET_KEY'],
+}
+if os.environ.get('S3_ENDPOINT'):
+    s3_kwargs['endpoint_url'] = os.environ['S3_ENDPOINT']
+s3 = boto3.client('s3', **s3_kwargs)
+{% else %}
+# Public bucket: no credentials to verify, nothing to check.
+print("connectivity ok (public bucket — no credentials to verify)")
+sys.exit(0)
+{% endif %}
+{% else %}
+# Access via UnitySVC S3 gateway — sign with the customer's API key.
+# SERVICE_BASE_URL is {endpoint_prefix}/{service_slug} (e.g. http://host:9180/demo/s3).
+# Split on the last '/' so boto3 path-style addressing reconstructs the full URL.
+service_url = os.environ['SERVICE_BASE_URL'].rstrip('/')
+endpoint_url = service_url.rsplit('/', 1)[0]
+bucket = service_url.rsplit('/', 1)[1]
+s3 = boto3.client('s3',
+    endpoint_url=endpoint_url,
+    aws_access_key_id=os.environ['UNITYSVC_API_KEY'],
+    aws_secret_access_key='not-used',
+    region_name='us-east-1',
+)
+{% endif %}
+
+# Auth-error codes: credentials were rejected. Anything else (including
+# 403 AccessDenied on list_buckets) still proves the signature was
+# accepted — the caller just isn't allowed to list. That counts as ok.
+AUTH_FAILURES = {'InvalidAccessKeyId', 'SignatureDoesNotMatch', 'InvalidClientTokenId'}
+
+try:
+    {% if local_testing %}
+    s3.list_buckets()
+    {% else %}
+    s3.list_objects_v2(Bucket=bucket, MaxKeys=1)
+    {% endif %}
+except ClientError as e:
+    status = e.response.get('ResponseMetadata', {}).get('HTTPStatusCode')
+    code = e.response.get('Error', {}).get('Code', '')
+    if status == 401 or code in AUTH_FAILURES:
+        print(f"connectivity failed: credentials rejected ({code or status})", file=sys.stderr)
+        sys.exit(1)
+    # Non-auth errors: credentials were accepted, endpoint just didn't
+    # like the specific call. That's still connectivity ok.
+except BotoCoreError as e:
+    print(f"connectivity failed: {e}", file=sys.stderr)
+    sys.exit(1)
+print("connectivity ok")

unitysvc_data/examples/s3/description/README.md

@@ -0,0 +1,45 @@
++++
+preset_name = "s3_description"
+category = "description"
+mime_type = "markdown"
+file = "description.md"
+description = "Customer-facing overview of the S3 gateway service"
+is_active = true
+is_public = true
++++
+
+# s3 / description — S3 gateway service description
+
+Markdown overview shown to customers on the listing page. Gives them a
+short narrative about the gateway plus a minimal `boto3` snippet they
+can copy-paste.
+
+## What's in the description
+
+- One-sentence framing of the gateway.
+- A `boto3.client('s3', ...)` snippet with the four fields a customer
+  needs to fill in: `endpoint_url`, `aws_access_key_id`,
+  `aws_secret_access_key` (always `"not-used"` for this gateway), and
+  the `Bucket` for the `list_objects_v2` call.
+- Closing paragraph explaining how the gateway authenticates, resolves
+  the upstream bucket, and proxies the request.
+
+## Template tokens — **not** Jinja2
+
+The description file contains `{{ S3_GATEWAY_PUBLIC_URL }}`,
+`{{ API_KEY }}`, and `{{ SERVICE_NAME }}` tokens. These are deliberately
+**not** rendered by the SDK — the file's name is `description.md`, not
+`description.md.j2`, so Pass-2 rendering leaves the tokens intact.
+Customers see them as literal placeholders they're expected to replace
+with their own values.
+
+If a future variant wants server-rendered tokens, add it as a new
+`[[versions]]` entry with a `description-v2.md.j2` file alongside the
+existing `description-v1.md` — do not convert `_v1` in place.
+
+## Versions
+
+### v1 — initial release
+
+- Static markdown; `{{ ... }}` tokens are literal placeholders shown
+  to customers.

unitysvc_data/examples/s3/description/description-v1.md

@@ -0,0 +1,21 @@
+## S3 Content via UnitySVC Storage Gateway
+
+Access S3-compatible content through UnitySVC's storage gateway using any
+S3 client (boto3, aws-cli, rclone, cyberduck) authenticated with your
+UnitySVC API key.
+
+```python
+import boto3
+
+s3 = boto3.client('s3',
+    endpoint_url='{{ S3_GATEWAY_PUBLIC_URL }}',
+    aws_access_key_id='{{ API_KEY }}',
+    aws_secret_access_key='not-used',
+)
+
+# Browse available files
+s3.list_objects_v2(Bucket='{{ SERVICE_NAME }}', MaxKeys=10)
+```
+
+The gateway authenticates you against your UnitySVC API key, resolves the
+upstream bucket from the service configuration, and proxies the request.

unitysvc_data/examples/smtp/connectivity/README.md

@@ -0,0 +1,50 @@
++++
+preset_name = "smtp_connectivity"
+category = "connectivity_test"
+mime_type = "bash"
+file = "connectivity.sh.j2"
+description = "Verify SMTP server returns a 220 greeting on connect"
+is_active = true
+is_public = false
+meta = { output_contains = "connectivity ok" }
++++
+
+# smtp / connectivity — SMTP banner smoke test
+
+Bash smoke test for mail-submission services routed through the
+UnitySVC SMTP relay. A healthy server answers a TCP connect with
+`220 ... ESMTP ...` within five seconds; anything else is failure.
+
+## Modes
+
+- **Local** — harness sets `$HOST` and `$PORT` from
+  `upstream_access_config`. `$PORT` defaults to 587 (submission).
+- **Gateway** — harness sets `$SERVICE_BASE_URL` as `smtp://host:port`
+  or `smtps://host:port`. The script strips the scheme, splits host
+  from port, and defaults the port to 587 if absent.
+
+The script picks the mode by looking at which env var is set — no
+`local_testing` conditional needed.
+
+## How the test works
+
+1. Open a TCP connection via `nc -w 5` (5-second cap on both connect
+   and idle-after-banner).
+2. Send `QUIT` so the server closes cleanly instead of timing out on
+   us.
+3. Read the first line of output.
+4. Accept any line starting with `220 `.
+
+## Conventions
+
+- Success line: `connectivity ok (220 ...)` — `meta.output_contains`
+  uses `connectivity ok` so any banner text passes.
+- Does not run `STARTTLS` or authenticate. This test is strictly
+  "pipe opens and server says it's SMTP".
+- Ports 25 and 465 work too; override `PORT` in the env.
+
+## Versions
+
+### v1 — initial release
+
+- Uses `nc -w 5`; sends `QUIT`; accepts any `220 ...` banner.

unitysvc_data/examples/smtp/connectivity/connectivity-v1.sh.j2

@@ -0,0 +1,34 @@
+#!/bin/bash
+# Connectivity test for SMTP services. A healthy mail server sends a
+# "220 ... ESMTP ..." greeting on connect; anything else (no response,
+# timeout, or other greeting code) is treated as failure.
+#
+# Env var layout the harness provides:
+#   local mode   — $HOST, $PORT  (from upstream_access_config)
+#   online mode  — $SERVICE_BASE_URL  (smtp://host:port or smtps://host:port)
+# We branch on whichever is present so the same script works in both.
+set -o pipefail
+
+if [ -n "${HOST:-}" ]; then
+    PORT="${PORT:-587}"
+else
+    URL="${SERVICE_BASE_URL:?need HOST or SERVICE_BASE_URL}"
+    stripped="${URL#smtp://}"
+    stripped="${stripped#smtps://}"
+    HOST="${stripped%%:*}"
+    PORT="${stripped#*:}"
+    PORT="${PORT%%/*}"
+    PORT="${PORT:-587}"
+fi
+
+# `nc -w 5` caps both connect wait and idle-after-banner wait. Send QUIT
+# so the server closes cleanly instead of timing out on us.
+greeting=$( (echo "QUIT"; sleep 1) | nc -w 5 "$HOST" "$PORT" 2>/dev/null | head -1 )
+
+if [[ "$greeting" == "220 "* ]]; then
+    echo "connectivity ok ($greeting)"
+    exit 0
+fi
+
+echo "connectivity failed: expected '220 ...' greeting from ${HOST}:${PORT}, got: ${greeting:-<no response>}" >&2
+exit 1

unitysvc_data/presets.py

@@ -0,0 +1,259 @@
+"""Preset document records and file content, backed by bundled example files.
+
+Loaded from ``_manifest.json`` at import time so installs don't pay for
+a filesystem walk. The manifest is generated by ``tools/build.py`` from
+the per-family ``README.md`` front-matter; CI validates it's up to
+date on every PR.
+
+Two primitives are exposed:
+
+- :func:`doc_preset` — returns a fully-populated document record
+  (``category``, ``description``, ``mime_type``, ``file_path``, ...),
+  suitable for dropping into a seller's ``listing.json`` ``documents``
+  map. This is the expansion the SDK applies to ``$preset`` JSON
+  sentinels at upload time.
+
+- :func:`file_preset` — returns the raw UTF-8 content of the bundled
+  example file itself. Useful when the example isn't a listing
+  document — for embedding as a code snippet, feeding to a test
+  harness, or any future use that needs the bytes rather than the
+  document metadata.
+
+Both accept either a bare preset name (``"s3_connectivity_v1"``,
+``"s3_connectivity"``) or a ``{"$preset": ..., "$with": ...}`` sentinel,
+so the same function works from JSON walkers and from programmatic
+Python code. Version-less aliases (``s3_connectivity``) resolve to the
+latest published version in the family.
+
+See https://github.com/unitysvc/unitysvc-sellers/issues/25 for design.
+"""
+
+from __future__ import annotations
+
+import json
+from copy import deepcopy
+from importlib.resources import files as _files
+from pathlib import Path
+from typing import Any
+
+# Resolved once at import time. Duplicated with __init__ rather than
+# imported to avoid a circular import during package load.
+_EXAMPLES_ROOT = _files(__name__).joinpath("examples")
+
+__all__ = [
+    "PRESETS",
+    "MANIFEST",
+    "ALIASES",
+    "OVERRIDABLE",
+    "doc_preset",
+    "file_preset",
+    "list_presets",
+    "register_jinja_globals",
+]
+
+# Fields a seller may override when expanding a preset. Everything else
+# — category, mime_type, file_path — is tied to the bundled file
+# content and rejected as an override.
+OVERRIDABLE: frozenset[str] = frozenset({"description", "is_public", "is_active", "meta"})
+
+
+def _load_manifest() -> dict[str, Any]:
+    manifest_bytes = _files(__name__).joinpath("_manifest.json").read_bytes()
+    return json.loads(manifest_bytes)
+
+
+def _resolve_example_path(relative_file: str) -> str:
+    target = _EXAMPLES_ROOT.joinpath(relative_file)
+    if not target.is_file():
+        raise FileNotFoundError(
+            f"Manifest references missing file {relative_file!r}. "
+            f"Rebuild with `python tools/build.py`."
+        )
+    return str(Path(str(target)))
+
+
+MANIFEST: dict[str, Any] = _load_manifest()
+_PRESET_RECORDS: dict[str, dict[str, Any]] = {}
+
+for _name, _entry in MANIFEST["presets"].items():
+    _PRESET_RECORDS[_name] = {
+        "category": _entry["category"],
+        "description": _entry["description"],
+        "file_path": _resolve_example_path(_entry["example_file"]),
+        "is_active": _entry["is_active"],
+        "is_public": _entry["is_public"],
+        "meta": dict(_entry.get("meta", {})),
+        "mime_type": _entry["mime_type"],
+    }
+
+# Alias entries share the same underlying record as their target. We
+# store the record under both names so a lookup of either resolves in
+# O(1) without chasing pointers.
+ALIASES: dict[str, str] = dict(MANIFEST.get("aliases", {}))
+for _alias, _target in ALIASES.items():
+    if _target not in _PRESET_RECORDS:
+        raise RuntimeError(
+            f"_manifest.json alias {_alias!r} points at missing preset {_target!r}. "
+            f"Rebuild with `python tools/build.py`."
+        )
+    _PRESET_RECORDS[_alias] = _PRESET_RECORDS[_target]
+
+
+def _make_factory(record: dict[str, Any]):
+    def _factory(**overrides: Any) -> dict[str, Any]:
+        bad = set(overrides) - OVERRIDABLE
+        if bad:
+            raise ValueError(
+                f"Cannot override {sorted(bad)!r} — these fields are tied to the file content. "
+                f"Allowed overrides: {sorted(OVERRIDABLE)!r}"
+            )
+        out = deepcopy(record)
+        for key, value in overrides.items():
+            if key == "meta" and isinstance(value, dict) and isinstance(out.get("meta"), dict):
+                out["meta"] = {**out["meta"], **value}
+            else:
+                out[key] = value
+        return out
+
+    return _factory
+
+
+PRESETS: dict[str, Any] = {name: _make_factory(record) for name, record in _PRESET_RECORDS.items()}
+
+
+# --- Source parsing --------------------------------------------------------
+
+
+def _parse_source(source: Any) -> tuple[str, dict[str, Any]]:
+    """Normalise a preset reference to ``(name, overrides)``.
+
+    Accepts either a bare name string or a ``{"$preset": ..., "$with": ...}``
+    sentinel dict. Returns ``(name, {})`` for string sources since
+    bare-name callers supply overrides as kwargs instead.
+    """
+    if isinstance(source, str):
+        return source, {}
+
+    if not isinstance(source, dict):
+        raise TypeError(
+            f"Expected a preset name string or a $preset sentinel dict, "
+            f"got {type(source).__name__}"
+        )
+
+    if "$preset" not in source:
+        raise ValueError(f"Node is not a preset sentinel (missing '$preset'): {source!r}")
+
+    unknown = set(source) - {"$preset", "$with"}
+    if unknown:
+        raise ValueError(
+            f"Unknown keys in preset sentinel: {sorted(unknown)!r}. "
+            f"Only '$preset' and '$with' are allowed."
+        )
+
+    name = source["$preset"]
+    if not isinstance(name, str):
+        raise ValueError(f"'$preset' must be a string, got {type(name).__name__}")
+
+    overrides = source.get("$with") or {}
+    if not isinstance(overrides, dict):
+        raise ValueError(f"'$with' must be an object, got {type(overrides).__name__}")
+
+    return name, overrides
+
+
+def _lookup(name: str, pool: dict[str, Any], what: str) -> Any:
+    try:
+        return pool[name]
+    except KeyError:
+        raise KeyError(
+            f"Unknown preset: {name!r}. Available {what}s: {sorted(pool)!r}"
+        ) from None
+
+
+# --- Public API ------------------------------------------------------------
+
+
+def doc_preset(source: Any, **overrides: Any) -> dict[str, Any]:
+    """Return a fully-populated document record for the named preset.
+
+    ``source`` may be a bare preset name (``"s3_connectivity_v1"`` or
+    the version-less alias ``"s3_connectivity"``) or a JSON sentinel
+    ``{"$preset": ..., "$with": {...}}`` as it appears in a parsed
+    ``listing.json``.
+
+    Overrides (``description``, ``is_active``, ``is_public``, ``meta``)
+    may come from ``$with`` when using the sentinel form or from
+    keyword arguments when passing a bare name — but not both at once.
+    Attempting to override ``category``, ``mime_type``, or ``file_path``
+    raises :class:`ValueError` because those are tied to the bundled
+    file content.
+
+    The returned dict is a fresh copy on every call; callers may
+    mutate it freely.
+    """
+    name, sentinel_overrides = _parse_source(source)
+    if sentinel_overrides and overrides:
+        raise ValueError(
+            "Cannot combine keyword overrides with a $preset sentinel's '$with' block — "
+            "pick one."
+        )
+    factory = _lookup(name, PRESETS, "preset")
+    return factory(**(sentinel_overrides or overrides))
+
+
+def file_preset(source: Any) -> str:
+    """Return the raw UTF-8 content of the preset's bundled file.
+
+    ``source`` may be a bare preset name or a ``$preset`` sentinel.
+    Overrides are rejected because file content is immutable — use
+    :func:`doc_preset` if you need a document record with per-field
+    overrides.
+
+    .. note::
+
+       For Jinja2 templates (``.j2`` files), the returned string is
+       the **raw template source** — constructs like
+       ``{% if local_testing %}`` are preserved verbatim. Rendering
+       requires listing / interface / provider context that only the
+       calling SDK knows; the sellers SDK applies that rendering via
+       ``render_template_file`` at upload time. If you're piping the
+       content to a runnable file (e.g.
+       ``usvc_data file-preset ... > smoke.py``) and the preset
+       targets a ``.j2`` file, you'll get a template, not an
+       executable script.
+    """
+    name, sentinel_overrides = _parse_source(source)
+    if sentinel_overrides:
+        raise ValueError(
+            "file_preset does not support '$with' overrides — the file content is immutable. "
+            "Use doc_preset() if you need a document record with per-field overrides."
+        )
+    record = _lookup(name, _PRESET_RECORDS, "preset")
+    return Path(record["file_path"]).read_text(encoding="utf-8")
+
+
+def list_presets() -> tuple[list[str], dict[str, str]]:
+    """Return ``(versioned_names, aliases)``.
+
+    *versioned_names* is the sorted list of concrete preset names
+    (``s3_connectivity_v1``, ...); *aliases* maps each version-less
+    family name to its current latest versioned name
+    (``s3_connectivity`` → ``s3_connectivity_v1``).
+
+    Symmetric with ``usvc_data list`` on the CLI.
+    """
+    return sorted(MANIFEST["presets"]), dict(ALIASES)
+
+
+def register_jinja_globals(env: Any) -> None:
+    """Register every preset factory as a Jinja2 global on *env*.
+
+    Lets generated-repo templates write ``{{ s3_connectivity_v1() | tojson }}``
+    directly in ``listing.json.j2`` instead of the ``$preset`` JSON
+    sentinel. Hand-authored repos use the sentinel path and never need
+    this hook.
+
+    Both concrete names (``s3_connectivity_v1``) and aliases
+    (``s3_connectivity``) are registered.
+    """
+    env.globals.update(PRESETS)