From 788b3fa5294d7acb54e547c158c307924f69f60e Mon Sep 17 00:00:00 2001 From: Colin Lacy Date: Sat, 14 Nov 2026 10:59:40 +0000 Subject: [PATCH 1/3] adds smtp to common, nats to env --- catalog/rc/common-integrations/README.md | 26 ++- .../common-integrations-v1alpha2.yaml | 159 +++++++++++++ catalog/rc/env-configuration/README.md | 27 ++- .../env-configuration-v1alpha2.yaml | 213 ++++++++++++++++++ tooling/extension-bindings/packages.yaml | 14 +- 5 files changed, 427 insertions(+), 12 deletions(-) create mode 100644 catalog/rc/common-integrations/common-integrations-v1alpha2.yaml create mode 100644 catalog/rc/env-configuration/env-configuration-v1alpha2.yaml diff --git a/catalog/rc/common-integrations/README.md b/catalog/rc/common-integrations/README.md index e114db6..1b6ac84 100644 --- a/catalog/rc/common-integrations/README.md +++ b/catalog/rc/common-integrations/README.md @@ -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. @@ -16,7 +16,11 @@ This extension is not part of the core Runtime Conditions Profile vocabulary. Pr ```yaml extensions: +<<<<<<< HEAD - https://runtimeconditions.io/extensions/rc/common-integrations/v1alpha1/runtimeconditions.extension.yaml +======= + - https://runtimeconditions.io/extensions/rc/common-integrations:v1alpha2 +>>>>>>> a7547c2 (adds smtp to common, nats to env) ``` This extension defines: @@ -49,6 +53,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. @@ -240,7 +259,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 @@ -270,7 +290,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 diff --git a/catalog/rc/common-integrations/common-integrations-v1alpha2.yaml b/catalog/rc/common-integrations/common-integrations-v1alpha2.yaml new file mode 100644 index 0000000..b6ff0c3 --- /dev/null +++ b/catalog/rc/common-integrations/common-integrations-v1alpha2.yaml @@ -0,0 +1,159 @@ +apiVersion: runtimeconditions.io/v1alpha1 +kind: RuntimeConditionsExtensionDefinition +metadata: + id: https://runtimeconditions.io/extensions/rc/common-integrations/v1alpha2/runtimeconditions.extension.yaml + version: v1alpha2 +spec: + kinds: + - {name: api} + - {name: datastore} + - {name: cache} + interfaceTypes: + - {name: http, targetKind: api} + - {name: relational, targetKind: datastore} + - {name: document, targetKind: datastore} + - {name: key_value, targetKind: cache} + - {name: smtp, targetKind: api} + interfaceFields: + - {name: spec, targetKind: api, targetType: http} + - {name: operations, targetKind: api, targetType: http} + - {name: engine, targetKind: datastore, targetType: relational} + - {name: engine, targetKind: datastore, targetType: document} + - {name: engine, targetKind: cache, targetType: key_value} + - {name: operations, targetKind: api, targetType: smtp} + fieldValues: + - {field: interface.spec.format, targetKind: api, targetType: http, values: [openapi]} + - field: interface.operations[].method + targetKind: api + targetType: http + values: [GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS, TRACE] + - field: interface.engine + targetKind: datastore + targetType: relational + values: [postgres, mysql, mariadb, sqlserver, oracle, sqlite] + - field: interface.engine + targetKind: datastore + targetType: document + values: [mongodb, couchbase] + - field: interface.engine + targetKind: cache + targetType: key_value + values: [redis, memcached] + - {field: 'interface.operations[]', targetKind: api, targetType: smtp, values: [send]} + schemas: + - id: api-http-interface + appliesToKind: api + appliesToInterfaceType: http + description: Validates HTTP API integration conditions. + schema: + $schema: https://json-schema.org/draft/2020-12/schema + type: object + required: [kind, interface] + properties: + kind: {const: api} + interface: + type: object + required: [type] + properties: + type: {const: http} + spec: + type: object + required: [format, uri] + properties: + format: {const: openapi} + uri: {type: string, minLength: 1} + version: + type: string + pattern: ^(?:=?[0-9]+\.[0-9]+\.[0-9]+|[<>]=?[0-9]+\.[0-9]+\.[0-9]+|\^[0-9]+\.[0-9]+\.[0-9]+|~[0-9]+\.[0-9]+\.[0-9]+)$ + additionalProperties: false + operations: + type: array + minItems: 1 + items: + type: object + required: [method, path] + properties: + method: {enum: [GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS, TRACE]} + path: {type: string, minLength: 1} + requestBodySchema: {$ref: '#/$defs/simpleSchema'} + responseSchema: {$ref: '#/$defs/simpleSchema'} + additionalProperties: false + anyOf: + - {required: [spec]} + - {required: [operations]} + additionalProperties: true + additionalProperties: true + $defs: + simpleSchema: + oneOf: + - {type: string, enum: [string, number, integer, boolean, 'null']} + - {type: object, additionalProperties: {$ref: '#/$defs/simpleSchema'}} + - {type: array, minItems: 1, maxItems: 1, items: {$ref: '#/$defs/simpleSchema'}} + - id: datastore-relational-interface + appliesToKind: datastore + appliesToInterfaceType: relational + description: Validates relational datastore integration conditions. + schema: + $schema: https://json-schema.org/draft/2020-12/schema + type: object + required: [kind, interface] + properties: + kind: {const: datastore} + interface: + type: object + required: [type] + properties: + type: {const: relational} + engine: {enum: [postgres, mysql, mariadb, sqlserver, oracle, sqlite]} + additionalProperties: true + additionalProperties: true + - id: datastore-document-interface + appliesToKind: datastore + appliesToInterfaceType: document + description: Validates document datastore integration conditions. + schema: + $schema: https://json-schema.org/draft/2020-12/schema + type: object + required: [kind, interface] + properties: + kind: {const: datastore} + interface: + type: object + required: [type] + properties: {type: {const: document}, engine: {enum: [mongodb, couchbase]}} + additionalProperties: true + additionalProperties: true + - id: cache-key-value-interface + appliesToKind: cache + appliesToInterfaceType: key_value + description: Validates key/value cache integration conditions. + schema: + $schema: https://json-schema.org/draft/2020-12/schema + type: object + required: [kind, interface] + properties: + kind: {const: cache} + interface: + type: object + required: [type] + properties: {type: {const: key_value}, engine: {enum: [redis, memcached]}} + additionalProperties: true + additionalProperties: true + - id: api-smtp-interface + appliesToKind: api + appliesToInterfaceType: smtp + description: Validates SMTP email submission requirements. + schema: + $schema: https://json-schema.org/draft/2020-12/schema + type: object + required: [kind, interface] + properties: + kind: {const: api} + interface: + type: object + required: [type, operations] + properties: + type: {const: smtp} + operations: {type: array, minItems: 1, uniqueItems: true, items: {enum: [send]}} + additionalProperties: true + additionalProperties: true diff --git a/catalog/rc/env-configuration/README.md b/catalog/rc/env-configuration/README.md index 9840d11..ec514e9 100644 --- a/catalog/rc/env-configuration/README.md +++ b/catalog/rc/env-configuration/README.md @@ -6,7 +6,7 @@ This document defines a first-party Runtime Conditions extension for declaring workload configuration inputs that are provided through environment variables. -The machine-readable extension definition is [env-configuration-v1alpha1.yaml](env-configuration-v1alpha1.yaml). +The current machine-readable definition is [env-configuration-v1alpha2.yaml](env-configuration-v1alpha2.yaml). The previous [v1alpha1 definition](env-configuration-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. @@ -16,13 +16,23 @@ This extension is not part of the core Runtime Conditions Profile vocabulary. Pr ```yaml extensions: +<<<<<<< HEAD - https://runtimeconditions.io/extensions/rc/common-integrations/v1alpha1/runtimeconditions.extension.yaml - https://runtimeconditions.io/extensions/rc/env-configuration/v1alpha1/runtimeconditions.extension.yaml +======= + - https://runtimeconditions.io/extensions/rc/common-integrations:v1alpha2 + - https://runtimeconditions.io/extensions/rc/env-configuration:v1alpha2 + - https://runtimeconditions.io/extensions/nats/service:0.1.0 +>>>>>>> a7547c2 (adds smtp to common, nats to env) ``` This extension defines the Condition field `configuration`. +<<<<<<< HEAD This extension depends on `https://runtimeconditions.io/extensions/rc/common-integrations/v1alpha1/runtimeconditions.extension.yaml` for the common Condition kinds and interface types referenced by its standard property validation table. +======= +This release depends on common-integrations `v1alpha2` and NATS service `0.1.0`. Immutable definition URIs identify those dependencies in the definition and binding metadata; generated profiles use the namespaced `:` references above. Regenerated binding packages therefore depend on both providers' native packages. +>>>>>>> a7547c2 (adds smtp to common, nats to env) This extension owns the unqualified Condition field name `configuration` only within the common integration scopes listed in this document. Other extensions @@ -150,12 +160,20 @@ The following standard connection properties are defined by this extension: | `database` | Database name, schema name, logical database number, or equivalent datastore selector | | `token` | Bearer token, API token, or equivalent credential | | `tls` | Whether TLS is required or enabled | +| `tlsMode` | SMTP transport mode; the application interprets `disabled`, `starttls`, or `implicit` | +| `fromAddress` | Configured SMTP sender address | +| `toAddress` | Configured SMTP recipient address | +| `stream` | Actual NATS JetStream stream name | +| `subject` | Actual NATS subject used by the application; does not add a subject filter to the NATS consume operation | +| `consumer` | Actual NATS JetStream consumer name | Allowed properties are validated against the Condition `kind` and `interface.type`. | Condition | Allowed properties | | --------- | ------------------ | | `kind: api`, `interface.type: http` | `url`, `baseUrl`, `hostname`, `port`, `scheme`, `username`, `password`, `token`, `tls` | +| `kind: api`, `interface.type: smtp` | `url`, `hostname`, `port`, `username`, `password`, `tlsMode`, `fromAddress`, `toAddress` | +| `kind: nats.service`, `interface.type: service` | `url`, `hostname`, `port`, `username`, `password`, `token`, `tls`, `stream`, `subject`, `consumer` | | `kind: datastore`, `interface.type: relational` | `url`, `hostname`, `port`, `scheme`, `username`, `password`, `database`, `tls` | | `kind: datastore`, `interface.type: document` | `url`, `hostname`, `port`, `scheme`, `username`, `password`, `database`, `tls` | | `kind: cache`, `interface.type: key_value` | `url`, `hostname`, `port`, `scheme`, `username`, `password`, `database`, `token`, `tls` | @@ -168,7 +186,7 @@ Extensions that define additional Condition kinds or interface types MAY define A Condition that uses this extension is invalid if: -- `configuration` appears and `https://runtimeconditions.io/extensions/rc/env-configuration/v1alpha1/runtimeconditions.extension.yaml` is not declared +- `configuration` appears and the applicable env-configuration release is not declared - `configuration` contains neither `env` nor `alternatives` - `configuration` contains both `env` and `alternatives` - `configuration.env` is present but empty @@ -200,8 +218,13 @@ workload: version: v1.2.3 extensions: +<<<<<<< HEAD - https://runtimeconditions.io/extensions/rc/common-integrations/v1alpha1/runtimeconditions.extension.yaml - https://runtimeconditions.io/extensions/rc/env-configuration/v1alpha1/runtimeconditions.extension.yaml +======= + - https://runtimeconditions.io/extensions/rc/common-integrations:v1alpha2 + - https://runtimeconditions.io/extensions/rc/env-configuration:v1alpha2 +>>>>>>> a7547c2 (adds smtp to common, nats to env) conditions: - name: todos-api diff --git a/catalog/rc/env-configuration/env-configuration-v1alpha2.yaml b/catalog/rc/env-configuration/env-configuration-v1alpha2.yaml new file mode 100644 index 0000000..bb9103e --- /dev/null +++ b/catalog/rc/env-configuration/env-configuration-v1alpha2.yaml @@ -0,0 +1,213 @@ +apiVersion: runtimeconditions.io/v1alpha1 +kind: RuntimeConditionsExtensionDefinition +metadata: + id: https://runtimeconditions.io/extensions/rc/env-configuration/v1alpha2/runtimeconditions.extension.yaml + version: v1alpha2 +spec: + dependencies: ['https://runtimeconditions.io/extensions/rc/common-integrations/v1alpha2/runtimeconditions.extension.yaml', + 'https://runtimeconditions.io/extensions/nats/service/0.1.0/runtimeconditions.extension.yaml'] + conditionFields: + - {name: configuration, appliesToKinds: [api], appliesToInterfaceTypes: [http]} + - name: configuration + appliesToKinds: [datastore] + appliesToInterfaceTypes: [relational, document] + - {name: configuration, appliesToKinds: [cache], appliesToInterfaceTypes: [key_value]} + - {name: configuration, appliesToKinds: [api], appliesToInterfaceTypes: [smtp]} + - {name: configuration, appliesToKinds: [nats.service], appliesToInterfaceTypes: [service]} + fieldValues: + - field: configuration.env[].property + targetKind: api + targetType: http + values: [url, baseUrl, hostname, port, scheme, username, password, token, tls] + - field: configuration.alternatives[].env[].property + targetKind: api + targetType: http + values: [url, baseUrl, hostname, port, scheme, username, password, token, tls] + - field: configuration.env[].property + targetKind: datastore + targetType: relational + values: [url, hostname, port, scheme, username, password, database, tls] + - field: configuration.alternatives[].env[].property + targetKind: datastore + targetType: relational + values: [url, hostname, port, scheme, username, password, database, tls] + - field: configuration.env[].property + targetKind: datastore + targetType: document + values: [url, hostname, port, scheme, username, password, database, tls] + - field: configuration.alternatives[].env[].property + targetKind: datastore + targetType: document + values: [url, hostname, port, scheme, username, password, database, tls] + - field: configuration.env[].property + targetKind: cache + targetType: key_value + values: [url, hostname, port, scheme, username, password, database, token, tls] + - field: configuration.alternatives[].env[].property + targetKind: cache + targetType: key_value + values: [url, hostname, port, scheme, username, password, database, token, tls] + - field: configuration.env[].property + targetKind: api + targetType: smtp + values: [url, hostname, port, username, password, tlsMode, fromAddress, toAddress] + - field: configuration.alternatives[].env[].property + targetKind: api + targetType: smtp + values: [url, hostname, port, username, password, tlsMode, fromAddress, toAddress] + - field: configuration.env[].property + targetKind: nats.service + targetType: service + values: [url, hostname, port, username, password, token, tls, stream, subject, consumer] + - field: configuration.alternatives[].env[].property + targetKind: nats.service + targetType: service + values: [url, hostname, port, username, password, token, tls, stream, subject, consumer] + schemas: + - id: configuration-shape + description: Validates the environment configuration field shape. + schema: + $schema: https://json-schema.org/draft/2020-12/schema + type: object + properties: + 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 + additionalProperties: true + $defs: + envList: {type: array, minItems: 1, uniqueItems: true, items: {$ref: '#/$defs/envInput'}} + envInput: + type: object + required: [property, name] + properties: + property: {type: string, minLength: 1} + name: {type: string, pattern: '^[A-Za-z_][A-Za-z0-9_]*$'} + sensitive: {type: boolean} + required: {type: boolean} + additionalProperties: false + - id: configuration-properties-api-http + appliesToKind: api + appliesToInterfaceType: http + description: Validates allowed environment configuration properties for HTTP API integrations. + schema: + $schema: https://json-schema.org/draft/2020-12/schema + type: object + properties: {configuration: {$ref: '#/$defs/configuration'}} + additionalProperties: true + $defs: + allowedProperty: {enum: [url, baseUrl, hostname, port, scheme, username, password, token, tls]} + configuration: + type: object + properties: + env: {type: array, items: {$ref: '#/$defs/envInput'}} + alternatives: + type: array + items: {type: object, properties: {env: {type: array, items: {$ref: '#/$defs/envInput'}}}} + envInput: {type: object, properties: {property: {$ref: '#/$defs/allowedProperty'}}} + - id: configuration-properties-datastore-relational + appliesToKind: datastore + appliesToInterfaceType: relational + description: Validates allowed environment configuration properties for relational datastore integrations. + schema: + $schema: https://json-schema.org/draft/2020-12/schema + type: object + properties: {configuration: {$ref: '#/$defs/configuration'}} + additionalProperties: true + $defs: + allowedProperty: {enum: [url, hostname, port, scheme, username, password, database, tls]} + configuration: + type: object + properties: + env: {type: array, items: {$ref: '#/$defs/envInput'}} + alternatives: + type: array + items: {type: object, properties: {env: {type: array, items: {$ref: '#/$defs/envInput'}}}} + envInput: {type: object, properties: {property: {$ref: '#/$defs/allowedProperty'}}} + - id: configuration-properties-datastore-document + appliesToKind: datastore + appliesToInterfaceType: document + description: Validates allowed environment configuration properties for document datastore integrations. + schema: + $schema: https://json-schema.org/draft/2020-12/schema + type: object + properties: {configuration: {$ref: '#/$defs/configuration'}} + additionalProperties: true + $defs: + allowedProperty: {enum: [url, hostname, port, scheme, username, password, database, tls]} + configuration: + type: object + properties: + env: {type: array, items: {$ref: '#/$defs/envInput'}} + alternatives: + type: array + items: {type: object, properties: {env: {type: array, items: {$ref: '#/$defs/envInput'}}}} + envInput: {type: object, properties: {property: {$ref: '#/$defs/allowedProperty'}}} + - id: configuration-properties-cache-key-value + appliesToKind: cache + appliesToInterfaceType: key_value + description: Validates allowed environment configuration properties for key/value cache integrations. + schema: + $schema: https://json-schema.org/draft/2020-12/schema + type: object + properties: {configuration: {$ref: '#/$defs/configuration'}} + additionalProperties: true + $defs: + allowedProperty: {enum: [url, hostname, port, scheme, username, password, database, token, tls]} + configuration: + type: object + properties: + env: {type: array, items: {$ref: '#/$defs/envInput'}} + alternatives: + type: array + items: {type: object, properties: {env: {type: array, items: {$ref: '#/$defs/envInput'}}}} + envInput: {type: object, properties: {property: {$ref: '#/$defs/allowedProperty'}}} + - id: configuration-properties-api-smtp + appliesToKind: api + appliesToInterfaceType: smtp + description: Validates environment configuration properties for api/smtp. + schema: + $schema: https://json-schema.org/draft/2020-12/schema + type: object + properties: {configuration: {$ref: '#/$defs/configuration'}} + additionalProperties: true + $defs: + allowedProperty: {enum: [url, hostname, port, username, password, tlsMode, fromAddress, toAddress]} + configuration: + type: object + properties: + env: {type: array, items: {$ref: '#/$defs/envInput'}} + alternatives: + type: array + items: {type: object, properties: {env: {type: array, items: {$ref: '#/$defs/envInput'}}}} + envInput: {type: object, properties: {property: {$ref: '#/$defs/allowedProperty'}}} + - id: configuration-properties-nats-service-service + appliesToKind: nats.service + appliesToInterfaceType: service + description: Validates environment configuration properties for nats.service/service. + schema: + $schema: https://json-schema.org/draft/2020-12/schema + type: object + properties: {configuration: {$ref: '#/$defs/configuration'}} + additionalProperties: true + $defs: + allowedProperty: {enum: [url, hostname, port, username, password, token, tls, stream, subject, consumer]} + configuration: + type: object + properties: + env: {type: array, items: {$ref: '#/$defs/envInput'}} + alternatives: + type: array + items: {type: object, properties: {env: {type: array, items: {$ref: '#/$defs/envInput'}}}} + envInput: {type: object, properties: {property: {$ref: '#/$defs/allowedProperty'}}} diff --git a/tooling/extension-bindings/packages.yaml b/tooling/extension-bindings/packages.yaml index d3dbd04..2b674f2 100644 --- a/tooling/extension-bindings/packages.yaml +++ b/tooling/extension-bindings/packages.yaml @@ -31,7 +31,7 @@ packages: publicationMode: registry registryId: npm common-integrations: - rootExtension: https://runtimeconditions.io/extensions/rc/common-integrations/v1alpha1/runtimeconditions.extension.yaml + rootExtension: https://runtimeconditions.io/extensions/rc/common-integrations/v1alpha2/runtimeconditions.extension.yaml coreProfileSchemaVersion: 0.4.0 languages: go: @@ -44,7 +44,7 @@ packages: python: coordinate: runtimeconditions-common-integrations name: runtimeconditions_common_integrations - version: 0.1.0 + version: 0.2.0 sourceDirectory: bindings/common-integrations/python languageVersion: 3.12.10 publicationMode: registry @@ -58,7 +58,7 @@ packages: publicationMode: registry registryId: npm env-configuration: - rootExtension: https://runtimeconditions.io/extensions/rc/env-configuration/v1alpha1/runtimeconditions.extension.yaml + rootExtension: https://runtimeconditions.io/extensions/rc/env-configuration/v1alpha2/runtimeconditions.extension.yaml coreProfileSchemaVersion: 0.4.0 languages: go: @@ -71,7 +71,7 @@ packages: python: coordinate: runtimeconditions-env-configuration name: runtimeconditions_env_configuration - version: 0.1.0 + version: 0.2.0 sourceDirectory: bindings/env-configuration/python languageVersion: 3.12.10 publicationMode: registry @@ -145,14 +145,14 @@ packages: go: coordinate: runtimeconditions.io/x/nats/service name: service - version: 0.1.0 + version: 0.1.1 sourceDirectory: bindings/nats-service/go languageVersion: 1.25.0 publicationMode: github-tag python: coordinate: runtimeconditions-nats-service name: runtimeconditions_nats_service - version: 0.1.0 + version: 0.1.1 sourceDirectory: bindings/nats-service/python languageVersion: 3.12.10 publicationMode: registry @@ -160,7 +160,7 @@ packages: typescript: coordinate: '@runtimeconditions/nats-service' name: '@runtimeconditions/nats-service' - version: 0.1.0 + version: 0.1.1 sourceDirectory: bindings/nats-service/typescript languageVersion: 20.19.6 publicationMode: registry From 09f163fccaba837f921178426d62acae886ad3f2 Mon Sep 17 00:00:00 2001 From: Colin Lacy Date: Sat, 14 Nov 2026 11:29:19 +0000 Subject: [PATCH 2/3] moves nats configs to the nats ext --- .../service-operations-semantic-bridge.yaml | 6 +- .../service/tests/test_compile_extension.py | 94 ++++++++++++++++++- .../nats/service/tools/compile_extension.py | 59 ++++++++++++ catalog/rc/env-configuration/README.md | 11 +-- .../env-configuration-v1alpha2.yaml | 31 +----- 5 files changed, 160 insertions(+), 41 deletions(-) diff --git a/catalog/nats/service/model/service-operations-semantic-bridge.yaml b/catalog/nats/service/model/service-operations-semantic-bridge.yaml index 114813f..5fa7b1c 100644 --- a/catalog/nats/service/model/service-operations-semantic-bridge.yaml +++ b/catalog/nats/service/model/service-operations-semantic-bridge.yaml @@ -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 diff --git a/catalog/nats/service/tests/test_compile_extension.py b/catalog/nats/service/tests/test_compile_extension.py index bf51fe3..bf8bbd6 100644 --- a/catalog/nats/service/tests/test_compile_extension.py +++ b/catalog/nats/service/tests/test_compile_extension.py @@ -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 @@ -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() diff --git a/catalog/nats/service/tools/compile_extension.py b/catalog/nats/service/tools/compile_extension.py index 2ea3234..be801fc 100644 --- a/catalog/nats/service/tools/compile_extension.py +++ b/catalog/nats/service/tools/compile_extension.py @@ -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) @@ -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} @@ -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']}") diff --git a/catalog/rc/env-configuration/README.md b/catalog/rc/env-configuration/README.md index ec514e9..075ee22 100644 --- a/catalog/rc/env-configuration/README.md +++ b/catalog/rc/env-configuration/README.md @@ -22,17 +22,16 @@ extensions: ======= - https://runtimeconditions.io/extensions/rc/common-integrations:v1alpha2 - https://runtimeconditions.io/extensions/rc/env-configuration:v1alpha2 +<<<<<<< HEAD - https://runtimeconditions.io/extensions/nats/service:0.1.0 >>>>>>> a7547c2 (adds smtp to common, nats to env) +======= +>>>>>>> cb26e7f (moves nats configs to the nats ext) ``` This extension defines the Condition field `configuration`. -<<<<<<< HEAD -This extension depends on `https://runtimeconditions.io/extensions/rc/common-integrations/v1alpha1/runtimeconditions.extension.yaml` for the common Condition kinds and interface types referenced by its standard property validation table. -======= This release depends on common-integrations `v1alpha2` and NATS service `0.1.0`. Immutable definition URIs identify those dependencies in the definition and binding metadata; generated profiles use the namespaced `:` references above. Regenerated binding packages therefore depend on both providers' native packages. ->>>>>>> a7547c2 (adds smtp to common, nats to env) This extension owns the unqualified Condition field name `configuration` only within the common integration scopes listed in this document. Other extensions @@ -163,9 +162,6 @@ The following standard connection properties are defined by this extension: | `tlsMode` | SMTP transport mode; the application interprets `disabled`, `starttls`, or `implicit` | | `fromAddress` | Configured SMTP sender address | | `toAddress` | Configured SMTP recipient address | -| `stream` | Actual NATS JetStream stream name | -| `subject` | Actual NATS subject used by the application; does not add a subject filter to the NATS consume operation | -| `consumer` | Actual NATS JetStream consumer name | Allowed properties are validated against the Condition `kind` and `interface.type`. @@ -173,7 +169,6 @@ Allowed properties are validated against the Condition `kind` and `interface.typ | --------- | ------------------ | | `kind: api`, `interface.type: http` | `url`, `baseUrl`, `hostname`, `port`, `scheme`, `username`, `password`, `token`, `tls` | | `kind: api`, `interface.type: smtp` | `url`, `hostname`, `port`, `username`, `password`, `tlsMode`, `fromAddress`, `toAddress` | -| `kind: nats.service`, `interface.type: service` | `url`, `hostname`, `port`, `username`, `password`, `token`, `tls`, `stream`, `subject`, `consumer` | | `kind: datastore`, `interface.type: relational` | `url`, `hostname`, `port`, `scheme`, `username`, `password`, `database`, `tls` | | `kind: datastore`, `interface.type: document` | `url`, `hostname`, `port`, `scheme`, `username`, `password`, `database`, `tls` | | `kind: cache`, `interface.type: key_value` | `url`, `hostname`, `port`, `scheme`, `username`, `password`, `database`, `token`, `tls` | diff --git a/catalog/rc/env-configuration/env-configuration-v1alpha2.yaml b/catalog/rc/env-configuration/env-configuration-v1alpha2.yaml index bb9103e..7046084 100644 --- a/catalog/rc/env-configuration/env-configuration-v1alpha2.yaml +++ b/catalog/rc/env-configuration/env-configuration-v1alpha2.yaml @@ -4,8 +4,7 @@ metadata: id: https://runtimeconditions.io/extensions/rc/env-configuration/v1alpha2/runtimeconditions.extension.yaml version: v1alpha2 spec: - dependencies: ['https://runtimeconditions.io/extensions/rc/common-integrations/v1alpha2/runtimeconditions.extension.yaml', - 'https://runtimeconditions.io/extensions/nats/service/0.1.0/runtimeconditions.extension.yaml'] + dependencies: ['https://runtimeconditions.io/extensions/rc/common-integrations/v1alpha2/runtimeconditions.extension.yaml'] conditionFields: - {name: configuration, appliesToKinds: [api], appliesToInterfaceTypes: [http]} - name: configuration @@ -13,7 +12,6 @@ spec: appliesToInterfaceTypes: [relational, document] - {name: configuration, appliesToKinds: [cache], appliesToInterfaceTypes: [key_value]} - {name: configuration, appliesToKinds: [api], appliesToInterfaceTypes: [smtp]} - - {name: configuration, appliesToKinds: [nats.service], appliesToInterfaceTypes: [service]} fieldValues: - field: configuration.env[].property targetKind: api @@ -55,14 +53,6 @@ spec: targetKind: api targetType: smtp values: [url, hostname, port, username, password, tlsMode, fromAddress, toAddress] - - field: configuration.env[].property - targetKind: nats.service - targetType: service - values: [url, hostname, port, username, password, token, tls, stream, subject, consumer] - - field: configuration.alternatives[].env[].property - targetKind: nats.service - targetType: service - values: [url, hostname, port, username, password, token, tls, stream, subject, consumer] schemas: - id: configuration-shape description: Validates the environment configuration field shape. @@ -192,22 +182,3 @@ spec: type: array items: {type: object, properties: {env: {type: array, items: {$ref: '#/$defs/envInput'}}}} envInput: {type: object, properties: {property: {$ref: '#/$defs/allowedProperty'}}} - - id: configuration-properties-nats-service-service - appliesToKind: nats.service - appliesToInterfaceType: service - description: Validates environment configuration properties for nats.service/service. - schema: - $schema: https://json-schema.org/draft/2020-12/schema - type: object - properties: {configuration: {$ref: '#/$defs/configuration'}} - additionalProperties: true - $defs: - allowedProperty: {enum: [url, hostname, port, username, password, token, tls, stream, subject, consumer]} - configuration: - type: object - properties: - env: {type: array, items: {$ref: '#/$defs/envInput'}} - alternatives: - type: array - items: {type: object, properties: {env: {type: array, items: {$ref: '#/$defs/envInput'}}}} - envInput: {type: object, properties: {property: {$ref: '#/$defs/allowedProperty'}}} From 1a99fcbb1c571bc63ca0ff4bae8e060644fe2e62 Mon Sep 17 00:00:00 2001 From: Colin Lacy Date: Sat, 14 Nov 2026 11:32:46 +0000 Subject: [PATCH 3/3] cleans up rebase --- catalog/rc/common-integrations/README.md | 4 ---- catalog/rc/env-configuration/README.md | 14 -------------- 2 files changed, 18 deletions(-) diff --git a/catalog/rc/common-integrations/README.md b/catalog/rc/common-integrations/README.md index 1b6ac84..4325e7f 100644 --- a/catalog/rc/common-integrations/README.md +++ b/catalog/rc/common-integrations/README.md @@ -16,11 +16,7 @@ This extension is not part of the core Runtime Conditions Profile vocabulary. Pr ```yaml extensions: -<<<<<<< HEAD - - https://runtimeconditions.io/extensions/rc/common-integrations/v1alpha1/runtimeconditions.extension.yaml -======= - https://runtimeconditions.io/extensions/rc/common-integrations:v1alpha2 ->>>>>>> a7547c2 (adds smtp to common, nats to env) ``` This extension defines: diff --git a/catalog/rc/env-configuration/README.md b/catalog/rc/env-configuration/README.md index 075ee22..80fc2df 100644 --- a/catalog/rc/env-configuration/README.md +++ b/catalog/rc/env-configuration/README.md @@ -16,17 +16,8 @@ This extension is not part of the core Runtime Conditions Profile vocabulary. Pr ```yaml extensions: -<<<<<<< HEAD - - https://runtimeconditions.io/extensions/rc/common-integrations/v1alpha1/runtimeconditions.extension.yaml - - https://runtimeconditions.io/extensions/rc/env-configuration/v1alpha1/runtimeconditions.extension.yaml -======= - https://runtimeconditions.io/extensions/rc/common-integrations:v1alpha2 - https://runtimeconditions.io/extensions/rc/env-configuration:v1alpha2 -<<<<<<< HEAD - - https://runtimeconditions.io/extensions/nats/service:0.1.0 ->>>>>>> a7547c2 (adds smtp to common, nats to env) -======= ->>>>>>> cb26e7f (moves nats configs to the nats ext) ``` This extension defines the Condition field `configuration`. @@ -213,13 +204,8 @@ workload: version: v1.2.3 extensions: -<<<<<<< HEAD - - https://runtimeconditions.io/extensions/rc/common-integrations/v1alpha1/runtimeconditions.extension.yaml - - https://runtimeconditions.io/extensions/rc/env-configuration/v1alpha1/runtimeconditions.extension.yaml -======= - https://runtimeconditions.io/extensions/rc/common-integrations:v1alpha2 - https://runtimeconditions.io/extensions/rc/env-configuration:v1alpha2 ->>>>>>> a7547c2 (adds smtp to common, nats to env) conditions: - name: todos-api