diff --git a/README.md b/README.md index ff67796..cd3fec0 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,6 @@ Use a tracked GitHub issue, a dedicated branch, and a pull request for every cha The versioned Kafka contracts under `docs/contracts/` are checked by the path-scoped `Validate AsyncAPI contracts` workflow. The dependency-free Ruby validator checks AsyncAPI metadata, Kafka channel and operation wiring, local -references, required event/header metadata, and the declared -`BACKWARD_TRANSITIVE` Schema Registry compatibility policy. Schema Registry -deployment and credentials remain platform responsibilities. +references, required event/header metadata, representative payload examples, +and the declared `BACKWARD_TRANSITIVE` Schema Registry compatibility policy. +Schema Registry deployment and credentials remain platform responsibilities. diff --git a/docs/asyncapi-contracts.md b/docs/asyncapi-contracts.md index 0d09177..b15bcc4 100644 --- a/docs/asyncapi-contracts.md +++ b/docs/asyncapi-contracts.md @@ -230,13 +230,20 @@ before merge. The contract check should: topic-specific DLQ or quarantine policy. 4. Verify the `TopicNameStrategy` subject mapping, schema version, and declared `BACKWARD_TRANSITIVE` compatibility. -5. Validate representative examples against their payload schemas and reject - credentials, tokens, secrets, and obvious customer PII. +5. Validate every representative example against its payload schema, including + required fields, constants, formats, patterns, arrays, and object + properties. The repository validator performs this deterministic local + check without requiring a schema-validation dependency. 6. Compare changed subjects with the prior contract or registry snapshot and reject breaking changes under an existing major subject. 7. Run `git diff --check` and fail on malformed Markdown or accidental literal escape text in documentation. +The repository gate validates the checked-in contract examples. Registry +subject comparison and live compatibility checks remain release/platform +responsibilities because pull requests must not require access to a deployed +registry or production credentials. + Pull-request validation must be deterministic and must not require access to a deployed Kafka cluster, production registry, cloud credentials, or real customer data. A registry integration check may run with an approved diff --git a/scripts/validate_asyncapi_contracts.rb b/scripts/validate_asyncapi_contracts.rb index 0d9ed6e..472ad7e 100644 --- a/scripts/validate_asyncapi_contracts.rb +++ b/scripts/validate_asyncapi_contracts.rb @@ -4,6 +4,7 @@ # Runtime Schema Registry validation remains a platform responsibility. require "yaml" +require "time" CONTRACT_GLOB = File.expand_path("../docs/contracts/*-asyncapi.yml", __dir__) REQUIRED_EVENT_FIELDS = %w[ @@ -41,6 +42,91 @@ def expect(condition, path, message) fail_with(path, message) unless condition end +UUID_PATTERN = /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i + +def normalized_pattern(pattern) + # Some YAML examples use JSON-style escaping while others use a literal + # single backslash. Normalize both forms before constructing the regexp. + pattern.gsub("\\\\", "\\") +end + +def schema_matches?(document, schema, value) + schema = lookup(document, schema["$ref"], "schema validation") if schema["$ref"] + + return false unless schema.fetch("allOf", []).all? { |part| schema_matches?(document, part, value) } + + if schema["oneOf"] + return false unless schema["oneOf"].count { |part| schema_matches?(document, part, value) } == 1 + end + + if schema["anyOf"] + return false unless schema["anyOf"].any? { |part| schema_matches?(document, part, value) } + end + + if schema["if"] + condition_matches = schema_matches?(document, schema["if"], value) + return false if condition_matches && schema["then"] && !schema_matches?(document, schema["then"], value) + return false if !condition_matches && schema["else"] && !schema_matches?(document, schema["else"], value) + end + + return false if schema["not"] && schema_matches?(document, schema["not"], value) + return false if schema["const"] && value != schema["const"] + return false if schema["enum"] && !schema["enum"].include?(value) + + case schema["type"] + when "object" + return false unless value.is_a?(Hash) + when "array" + return false unless value.is_a?(Array) + when "string" + return false unless value.is_a?(String) + when "integer" + return false unless value.is_a?(Integer) + when "number" + return false unless value.is_a?(Numeric) + when "boolean" + return false unless value == true || value == false + when "null" + return false unless value.nil? + end + + return false if schema["minLength"] && (!value.is_a?(String) || value.length < schema["minLength"]) + if schema["pattern"] + return false unless value.is_a?(String) && Regexp.new(normalized_pattern(schema["pattern"])).match?(value) + end + if schema["format"] == "uuid" + return false unless value.is_a?(String) && UUID_PATTERN.match?(value) + elsif schema["format"] == "date-time" + begin + Time.iso8601(value.to_s) + rescue ArgumentError + return false + end + end + + if value.is_a?(Hash) + required = schema.fetch("required", []) + return false unless required.all? { |key| value.key?(key) } + + properties = schema.fetch("properties", {}) + if schema["additionalProperties"] == false + return false unless (value.keys - properties.keys).empty? + end + return false unless properties.all? do |key, property_schema| + !value.key?(key) || schema_matches?(document, property_schema, value[key]) + end + elsif value.is_a?(Array) && schema["items"] + return false unless value.all? { |item| schema_matches?(document, schema["items"], item) } + end + + true +end + +def validate_example(document, schema, value, path) + expect(schema_matches?(document, schema, value), path, + "example payload does not satisfy its declared schema") +end + files = Dir[CONTRACT_GLOB].sort expect(!files.empty?, "docs/contracts", "no AsyncAPI contracts found") @@ -97,6 +183,16 @@ def expect(condition, path, message) "payload must require all common event metadata fields") expect(REQUIRED_HEADER_FIELDS.all? { |field| header_schema.fetch("required", []).include?(field) }, path, "headers must require all common event metadata fields") + + examples = message.fetch("examples", []) + expect(examples.is_a?(Array) && !examples.empty?, path, + "at least one representative payload example is required") + examples.each_with_index do |example, index| + example_path = "#{path}.messages.#{message_name}.examples[#{index}]" + expect(example.is_a?(Hash) && example.key?("payload"), example_path, + "example payload is required") + validate_example(document, payload_schema, example["payload"], example_path) + end end end