Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -9,10 +9,12 @@ operationSource:
service: nats
semanticSha256: 0f6fb3a7c5f1f3c8c780724057ef96ca22a7b2d0c2766f493e22d5f444c88ee8
extension:
id: https://runtimeconditions.io/extensions/nats/service/0.1.0/runtimeconditions.extension.yaml
version: 0.1.0
id: https://runtimeconditions.io/extensions/nats/service/0.2.0/runtimeconditions.extension.yaml
version: 0.2.0
conditionKind: nats.service
interfaceType: service
environmentConfiguration:
envProperties: [url, hostname, port, username, password, token, tls, stream, subject, consumer]
conditionFields:
subject:
inventoryShape: nats.subject
Expand Down
94 changes: 93 additions & 1 deletion catalog/nats/service/tests/test_compile_extension.py
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
ROOT = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(ROOT / "tools"))

from compile_extension import build # noqa: E402
from compile_extension import build, environment_configuration_schema # noqa: E402
from serialization import read_document # noqa: E402


Expand Down Expand Up @@ -89,6 +89,98 @@ def test_rejects_fields_not_declared_for_one_operation(self):
condition = {"kind": "nats.service", "interface": {"type": "service", "operations": [{"resource": "stream", "action": "inspect", "name": "ORDERS", "subjects": ["orders.>"]}]}}
self.assertTrue(list(self.validator.iter_errors(condition)))

def test_nats_owns_configuration_without_extension_dependencies(self):
self.assertEqual(self.extension["metadata"]["version"], "0.2.0")
self.assertFalse(self.extension["spec"].get("dependencies"))
self.assertEqual(self.extension["spec"]["conditionFields"], [
{"name": "configuration", "appliesToKinds": ["nats.service"], "appliesToInterfaceTypes": ["service"]},
])
schemas = [entry for entry in self.extension["spec"]["schemas"] if entry["id"] == "nats-service-configuration"]
self.assertEqual(len(schemas), 1)
domains = [entry for entry in self.extension["spec"]["fieldValues"] if entry["field"].startswith("configuration.")]
self.assertEqual(len(domains), 2)
for domain in domains:
self.assertEqual(domain["values"], self.bridge["extension"]["environmentConfiguration"]["envProperties"])

def test_env_configuration_keeps_only_its_common_dependency(self):
catalog = ROOT.parents[1]
env = read_document(catalog / "rc/env-configuration/env-configuration-v1alpha2.yaml")
self.assertEqual(env["spec"]["dependencies"], [
"https://runtimeconditions.io/extensions/rc/common-integrations/v1alpha2/runtimeconditions.extension.yaml",
])
for group, field in (("conditionFields", "appliesToKinds"), ("fieldValues", "targetKind"), ("schemas", "appliesToKind")):
for entry in env["spec"][group]:
self.assertNotIn("nats.service", entry.get(field, []))
self.assertTrue(any(entry.get("appliesToInterfaceType") == "smtp" for entry in env["spec"]["schemas"]))

def test_smtp_configuration_validates_with_only_common_integrations(self):
catalog = ROOT.parents[1]
common = read_document(catalog / "rc/common-integrations/common-integrations-v1alpha2.yaml")
env = read_document(catalog / "rc/env-configuration/env-configuration-v1alpha2.yaml")
self.assertFalse(common["spec"].get("dependencies"))
condition = {
"kind": "api", "interface": {"type": "smtp", "operations": ["send"]},
"configuration": {"env": [{"property": "hostname", "name": "SMTP_HOST"}]},
}
for extension in (common, env):
for entry in extension["spec"]["schemas"]:
if entry.get("appliesToKind", "api") == "api" and entry.get("appliesToInterfaceType", "smtp") == "smtp":
with self.subTest(extension=extension["metadata"]["id"], schema=entry["id"]):
self.assertEqual(list(Draft202012Validator(entry["schema"]).iter_errors(condition)), [])

def test_corrected_documents_match_the_extension_authoring_schema(self):
catalog = ROOT.parents[1]
schema = read_document(catalog.parent / "tooling/extension-bindings/model/runtimeconditions.extension-semantic.schema.yaml")
validator = Draft202012Validator(schema)
env = read_document(catalog / "rc/env-configuration/env-configuration-v1alpha2.yaml")
for extension in (env, self.extension):
with self.subTest(extension=extension["metadata"]["id"]):
self.assertEqual(list(validator.iter_errors(extension)), [])

def test_nats_configuration_validates_without_env_configuration(self):
schema = environment_configuration_schema(self.bridge["extension"]["environmentConfiguration"])
validator = Draft202012Validator(schema)
self.assertEqual(list(validator.iter_errors({})), [])
for prop in self.bridge["extension"]["environmentConfiguration"]["envProperties"]:
entry = {"property": prop, "name": "NATS_INPUT", "sensitive": True, "required": False}
for config in ({"env": [entry]}, {"alternatives": [{"env": [entry]}, {"env": [entry]}]}):
with self.subTest(property=prop, configuration=config):
self.assertEqual(list(validator.iter_errors({"configuration": config})), [])

def test_nats_configuration_rejects_invalid_inputs(self):
validator = Draft202012Validator(environment_configuration_schema(self.bridge["extension"]["environmentConfiguration"]))
valid = {"property": "url", "name": "NATS_URL"}
invalid = [
{}, {"env": []}, {"alternatives": [{"env": [valid]}]},
{"env": [valid], "alternatives": [{"env": [valid]}, {"env": [valid]}]},
{"env": [{"property": "database", "name": "DB"}]},
{"env": [{"property": "url", "name": "bad-name"}]},
{"env": [{**valid, "sensitive": "true"}]},
{"env": [{**valid, "required": "false"}]},
{"env": [{**valid, "value": "not-a-declaration-field"}]},
]
for config in invalid:
with self.subTest(configuration=config):
self.assertTrue(list(validator.iter_errors({"configuration": config})))

def test_rejects_invalid_configuration_authoring(self):
for config in (None, {}, {"envProperties": []}, {"envProperties": "url"},
{"envProperties": ["url", "url"]}, {"envProperties": [""]},
{"envProperties": [None]}, {"envProperties": ["url"], "unknown": True}):
with self.subTest(configuration=config):
with self.assertRaisesRegex(ValueError, "environmentConfiguration"):
environment_configuration_schema(config)

def test_legacy_inputs_preserve_the_existing_release_in_memory(self):
bridge = copy.deepcopy(self.bridge)
del bridge["extension"]["environmentConfiguration"]
bridge["extension"].update(
id="https://runtimeconditions.io/extensions/nats/service/0.1.0/runtimeconditions.extension.yaml", version="0.1.0",
)
extension, mapping = build(self.inventory, bridge)
self.assertEqual(extension, read_document(ROOT / "releases/0.1.0/runtimeconditions.extension.yaml"))
self.assertEqual(mapping, read_document(ROOT / "model/generated/nats-service-mapping.yaml"))


if __name__ == "__main__":
unittest.main()
59 changes: 59 additions & 0 deletions catalog/nats/service/tools/compile_extension.py
Original file line number Diff line number Diff line change
Expand Up @@ -156,6 +156,51 @@ def operation_schema(operation: dict[str, Any], fields: dict[str, dict[str, Any]
return {"type": "object", "required": ["resource", "action", *bindings["required"]], "properties": properties, "additionalProperties": False}


def environment_configuration_schema(configuration: Any) -> dict[str, Any]:
"""Describe NATS-owned environment inputs without importing another extension."""
if not isinstance(configuration, dict) or set(configuration) != {"envProperties"}:
raise ValueError("environmentConfiguration must contain exactly envProperties")
properties = configuration["envProperties"]
if not isinstance(properties, list) or not properties or not all(isinstance(item, str) and item for item in properties):
raise ValueError("environmentConfiguration.envProperties must be a non-empty string list")
if len(set(properties)) != len(properties):
raise ValueError("environmentConfiguration.envProperties must not contain duplicates")
schema = {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {"configuration": {"$ref": "#/$defs/configuration"}},
"$defs": {
"configuration": {
"type": "object",
"oneOf": [
{"required": ["env"], "properties": {"env": {"$ref": "#/$defs/envList"}}, "additionalProperties": False},
{
"required": ["alternatives"],
"properties": {"alternatives": {
"type": "array", "minItems": 2,
"items": {"type": "object", "required": ["env"], "properties": {"env": {"$ref": "#/$defs/envList"}}, "additionalProperties": False},
}},
"additionalProperties": False,
},
],
},
"envList": {"type": "array", "minItems": 1, "uniqueItems": True, "items": {"$ref": "#/$defs/envInput"}},
"envInput": {
"type": "object", "required": ["property", "name"],
"properties": {
"property": {"enum": list(properties)},
"name": {"type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"},
"sensitive": {"type": "boolean"},
"required": {"type": "boolean"},
},
"additionalProperties": False,
},
},
}
Draft202012Validator.check_schema(schema)
return schema


def build(inventory: dict[str, Any], bridge: dict[str, Any]) -> tuple[dict[str, Any], dict[str, Any]]:
inventory_identity, shapes, inventory_operations = inventory_contract(inventory)
extension_config, fields, operations = bridge_contract(bridge, inventory_identity, inventory, shapes, inventory_operations)
Expand Down Expand Up @@ -189,6 +234,18 @@ def build(inventory: dict[str, Any], bridge: dict[str, Any]) -> tuple[dict[str,
],
"schemas": [{"id": "nats-service-interface", "appliesToKind": kind, "appliesToInterfaceType": interface_type, "description": "Validates adapter-actionable NATS connection, subject authorization, and JetStream resource requirements.", "schema": schema}],
}
if "environmentConfiguration" in extension_config:
configuration_schema = environment_configuration_schema(extension_config["environmentConfiguration"])
properties = list(extension_config["environmentConfiguration"]["envProperties"])
spec["conditionFields"] = [{"name": "configuration", "appliesToKinds": [kind], "appliesToInterfaceTypes": [interface_type]}]
spec["fieldValues"].extend(
{"field": path, "targetKind": kind, "targetType": interface_type, "values": list(properties)}
for path in ("configuration.env[].property", "configuration.alternatives[].env[].property")
)
spec["schemas"].append({
"id": "nats-service-configuration", "appliesToKind": kind, "appliesToInterfaceType": interface_type,
"description": "Validates NATS-owned environment configuration inputs.", "schema": configuration_schema,
})
digest = semantic_sha256(spec)
extension = {"apiVersion": "runtimeconditions.io/v1alpha1", "kind": "RuntimeConditionsExtensionDefinition", "metadata": {"id": extension_config["id"], "version": extension_config["version"], "semanticSha256": digest}, "spec": spec}
semantic_body = {"fields": fields, "operations": operations}
Expand Down Expand Up @@ -216,6 +273,8 @@ def main() -> int:
parser.add_argument("--service-mapping-output", type=Path, required=True)
args = parser.parse_args()
extension, service_mapping = build(read_document(args.inventory), read_document(args.bridge))
if args.extension_output.exists() and read_document(args.extension_output) != extension:
parser.error("refusing to replace an existing extension release; select the new version's output path")
write_yaml(args.extension_output, extension)
write_yaml(args.service_mapping_output, service_mapping)
print(f"extension: {extension['metadata']['id']}")
Expand Down
24 changes: 20 additions & 4 deletions catalog/rc/common-integrations/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

This document defines a first-party Runtime Conditions extension for common application runtime integrations.

The machine-readable extension definition is [common-integrations-v1alpha1.yaml](common-integrations-v1alpha1.yaml).
The current machine-readable definition is [common-integrations-v1alpha2.yaml](common-integrations-v1alpha2.yaml). The previous [v1alpha1 definition](common-integrations-v1alpha1.yaml) is preserved.

This extension is not part of the core Runtime Conditions Profile vocabulary. Profiles that use this extension MUST declare it in the top-level `extensions` list.

Expand All @@ -16,7 +16,7 @@ This extension is not part of the core Runtime Conditions Profile vocabulary. Pr

```yaml
extensions:
- https://runtimeconditions.io/extensions/rc/common-integrations/v1alpha1/runtimeconditions.extension.yaml
- https://runtimeconditions.io/extensions/rc/common-integrations:v1alpha2
```

This extension defines:
Expand Down Expand Up @@ -49,6 +49,21 @@ These kinds are intentionally broad so that multiple interaction models or imple

API interfaces describe callable external services.

## SMTP email submission

The `api` kind supports the `smtp` interface for sending email through a standard SMTP client. Provider selection and connection settings belong to the platform and environment configuration.

```yaml
kind: api
interface:
type: smtp
operations: [send]
```

`operations` is required and must be a nonempty list without duplicates. This release supports only `send`. It describes mail submission, not inbox access or email receiving. No SMTP provider names or credentials appear in this interface.

NATS integrations continue to use the separate [NATS service extension](../../nats/service/README.md); this extension adds no NATS vocabulary.

## 3.1 HTTP Interface

The `api` kind supports the `http` interface type.
Expand Down Expand Up @@ -240,7 +255,8 @@ If `engine` is provided, it MUST be valid for the declared cache interface type.

A Condition that uses this extension is invalid if:

- `kind` is `api` and `interface.type` is not `http`
- `kind` is `api` and `interface.type` is neither `http` nor `smtp`
- `interface.type` is `smtp` and `operations` is missing, empty, contains duplicates, or contains a value other than `send`
- `kind` is `datastore` and `interface.type` is not `relational` or `document`
- `kind` is `cache` and `interface.type` is not `key_value`
- `kind` is `api`, `interface.type` is `http`, and neither `spec` nor `operations` is present
Expand Down Expand Up @@ -270,7 +286,7 @@ workload:
version: v1.2.3

extensions:
- https://runtimeconditions.io/extensions/rc/common-integrations/v1alpha1/runtimeconditions.extension.yaml
- https://runtimeconditions.io/extensions/rc/common-integrations:v1alpha2

conditions:
- name: primary-db
Expand Down
Loading
Loading