A platform for community discussion. Free, open, simple.
DEV: Enforce workflow node output contracts in specs (#44554)
Régis Hanolf7f08d9ef1f1
diff --git a/.skills/discourse-workflow-nodes/SKILL.md b/.skills/discourse-workflow-nodes/SKILL.mdindex e2c71b05956..63b586f8f2c 100644--- a/.skills/discourse-workflow-nodes/SKILL.md+++ b/.skills/discourse-workflow-nodes/SKILL.md@@ -22,7 +22,7 @@ Shape entities only with `DiscourseWorkflows::EntitySerializers` (`lib/discourse- Name every helper that shapes an entity for output `serialize_<entity>` (`serialize_badge`, `serialize_group`, `serialize_timer`, `serialize_assignee`, `serialize_channel`, `serialize_event`...), never `<entity>_data`; `node_entity_builders_spec` fails on `def <entity>_data`.- Don't wrap a shared builder in a node-private helper; call it directly.-- `serialize_topic_list_item` (`DiscourseWorkflows::TopicListItemSerializer`) carries plugin-added list fields (assign `assigned_to_*`, solved `has_accepted_answer`, voting `can_vote`/`vote_count`...); `serialize_topic` (`DiscourseWorkflows::TopicSerializer`) adds posters, participants and custom fields.+- `serialize_topic_list_item` (`DiscourseWorkflows::TopicListItemSerializer`) carries plugin-added list fields (assign `assigned_to_*`, solved `has_accepted_answer`, voting `can_vote`/`vote_count`...); `serialize_topic` (`DiscourseWorkflows::TopicSerializer`) adds posters, participants and custom fields. Both emit every `TOPIC_PROPERTIES` key.- Outside a `NodeType`, call them on the module: `DiscourseWorkflows::EntitySerializers.serialize_user(...)`.- Never use `BasicUserSerializer` or `TopicListItemSerializer` in node files; `node_entity_builders_spec` fails if you do.- Groups: `BasicGroupSerializer` (`BASIC_GROUP_PROPERTIES`) or `WebHookGroupSerializer` (`GROUP_SCHEMA`).@@ -33,3 +33,21 @@ Shape entities only with `DiscourseWorkflows::EntitySerializers` (`lib/discourse- Actions that may no-op output `changed` (boolean), computed by comparing state before and after (see badge, group, post_like).- Actions that mutate a topic also return `topic`.- Cap user lists with a named constant (e.g. `PostEventScoping::MAX_GOING_USERNAMES`).++## Output contracts++`node_output_contracts_spec` has a `user_defined_output` opt-out list. A node belongs there only if the user writes its output shape (code, sql, set_fields, workflow_call, manual). If the shape can be derived from config, override `self.output_schemas` instead.++- Use `"type": [..., "null"]` for keys that are always emitted but may be nil.+- Use `"x-optional": true` for keys that are only emitted on some paths, such as DM-only `usernames`, or `tags` when the guardian can't see them. Optional objects may be `{}`.+- `schema_serializer_sync_spec` fails when a declared serializer key is never emitted.++## Specs++Every node spec asserts the real output against the declared contract:++```ruby+expect(output).to match_node_output_schema(DiscourseWorkflows::Nodes::Foo::V1, configuration: config)+```++The matcher is strict: every declared property is required unless `x-optional`, and types must match. Run plugin specs with `LOAD_PLUGINS=1 bin/rspec`.diff --git a/plugins/chat/lib/discourse_workflows/nodes/send_chat_message/v1.rb b/plugins/chat/lib/discourse_workflows/nodes/send_chat_message/v1.rbindex 9aad68bd303..9fc6646280c 100644--- a/plugins/chat/lib/discourse_workflows/nodes/send_chat_message/v1.rb+++ b/plugins/chat/lib/discourse_workflows/nodes/send_chat_message/v1.rb@@ -51,12 +51,14 @@ if defined?(DiscourseWorkflows)},"username" => {"type" => "string",+ "x-optional" => true,},"usernames" => {"type" => "array","items" => {"type" => "string",},+ "x-optional" => true,},},},diff --git a/plugins/discourse-ai/discourse_workflows/nodes/classify/v1.rb b/plugins/discourse-ai/discourse_workflows/nodes/classify/v1.rbindex 2078e539cc6..b88399443a8 100644--- a/plugins/discourse-ai/discourse_workflows/nodes/classify/v1.rb+++ b/plugins/discourse-ai/discourse_workflows/nodes/classify/v1.rb@@ -180,6 +180,7 @@ if defined?(DiscourseWorkflows)properties["level"] = { "type" => "string" }endend+ properties.each { |key, property| property["x-optional"] = true if key != "type" }{ "type" => "object", "properties" => properties }enddiff --git a/plugins/discourse-assign/lib/discourse_assign/workflows/schema.rb b/plugins/discourse-assign/lib/discourse_assign/workflows/schema.rbindex a45b4731758..61fdde16f03 100644--- a/plugins/discourse-assign/lib/discourse_assign/workflows/schema.rb+++ b/plugins/discourse-assign/lib/discourse_assign/workflows/schema.rb@@ -7,7 +7,7 @@ module DiscourseAssign"$schema" => DiscourseWorkflows::Schema::DRAFT_URI,"type" => "object","properties" => {- "assignee" => DiscourseWorkflows::Schema::ASSIGNEE_PROPERTIES,+ "assignee" => DiscourseWorkflows::Schema::ASSIGNEE_PROPERTIES.merge("x-optional" => true),"previously_assigned" => DiscourseWorkflows::Schema::ASSIGNEE_PROPERTIES,},}.freezediff --git a/plugins/discourse-workflows/lib/discourse_workflows/schema.rb b/plugins/discourse-workflows/lib/discourse_workflows/schema.rbindex 4398e411225..20c27afb081 100644--- a/plugins/discourse-workflows/lib/discourse_workflows/schema.rb+++ b/plugins/discourse-workflows/lib/discourse_workflows/schema.rb@@ -57,6 +57,7 @@ module DiscourseWorkflows"username": { "type": ["string", "null"], "description": "Username of the topic author" },"tags": {"type": "array",+ "x-optional": true,"items": {"type": "object","properties": {@@ -68,7 +69,7 @@ module DiscourseWorkflows},"first_post_id": { "type": ["integer", "null"] },"visible": { "type": "boolean" },- "visibility_reason_id": { "type": "integer" },+ "visibility_reason_id": { "type": "integer", "x-optional": true },"closed": { "type": "boolean" },"archived": { "type": "boolean" },"created_at": { "type": "string", "format": "date-time" },@@ -81,11 +82,11 @@ module DiscourseWorkflows{"id": { "type": "integer" },"raw": { "type": "string" },- "raw_truncated": { "type": "boolean" },- "raw_original_length": { "type": "integer" },- "cooked": { "type": "string" },- "cooked_truncated": { "type": "boolean" },- "cooked_original_length": { "type": "integer" },+ "raw_truncated": { "type": "boolean", "x-optional": true },+ "raw_original_length": { "type": "integer", "x-optional": true },+ "cooked": { "type": "string", "x-optional": true },+ "cooked_truncated": { "type": "boolean", "x-optional": true },+ "cooked_original_length": { "type": "integer", "x-optional": true },"post_number": { "type": "integer" },"post_type": { "type": "integer" },"reply_to_post_number": { "type": ["integer", "null"] },@@ -304,7 +305,7 @@ module DiscourseWorkflows"query": { "type": "object" },"method": { "type": "string" },"webhook_url": { "type": "string" },- "raw_body": { "type": "string" }+ "raw_body": { "type": "string", "x-optional": true }}JSONdiff --git a/plugins/discourse-workflows/spec/lib/discourse_workflows/executor/error_workflow_trigger_spec.rb b/plugins/discourse-workflows/spec/lib/discourse_workflows/executor/error_workflow_trigger_spec.rbindex a38a15801cd..38a4b2fe7d8 100644--- a/plugins/discourse-workflows/spec/lib/discourse_workflows/executor/error_workflow_trigger_spec.rb+++ b/plugins/discourse-workflows/spec/lib/discourse_workflows/executor/error_workflow_trigger_spec.rb@@ -144,15 +144,14 @@ RSpec.describe DiscourseWorkflows::Executor::ErrorWorkflowTrigger dotrigger_data =Jobs::DiscourseWorkflows::ExecuteWorkflow.jobs.last["args"].first["trigger_data"]- expect(trigger_data["workflow"]).to include("id" => be_present, "name" => be_present)expect(trigger_data["execution"]).to include("id" => be_present,"url" => include("/admin/plugins/discourse-workflows/workflows/"),- "retryOf" => nil,"error" => include("message" => "something broke", "name" => "StandardError"),"lastNodeExecuted" => "My Node","mode" => "trigger",)+ expect(trigger_data).to match_node_output_schema(DiscourseWorkflows::Nodes::Error::V1)endit "passes the failed run's trigger data through so the error workflow can re-drive it" dodiff --git a/plugins/discourse-workflows/spec/lib/discourse_workflows/match_node_output_schema_spec.rb b/plugins/discourse-workflows/spec/lib/discourse_workflows/match_node_output_schema_spec.rbindex 6d7df061b47..8e3b4097219 100644--- a/plugins/discourse-workflows/spec/lib/discourse_workflows/match_node_output_schema_spec.rb+++ b/plugins/discourse-workflows/spec/lib/discourse_workflows/match_node_output_schema_spec.rb@@ -102,6 +102,41 @@ RSpec.describe RSpec::Matchers, "#match_node_output_schema" do)end+ describe "strict mode" do+ let(:loose_node) do+ Class.new do+ def self.output_schemas(_configuration = {}, input_schemas: [])+ [+ {+ "type" => "object",+ "properties" => {+ "name" => {+ "type" => "string",+ },+ "extra" => {+ "type" => "object",+ "x-optional" => true,+ },+ },+ },+ ]+ end+ end+ end++ it "requires declared properties even when the schema omits required" do+ output = { extra: {} }++ expect(output).not_to match_node_output_schema(loose_node)+ end++ it "allows x-optional properties to be absent" do+ output = { name: "Ada" }++ expect(output).to match_node_output_schema(loose_node)+ end+ end+it "rejects non-Hash output" dooutput = [{ profile: { name: "Ada" } }]diff --git a/plugins/discourse-workflows/spec/lib/discourse_workflows/node_output_contracts_spec.rb b/plugins/discourse-workflows/spec/lib/discourse_workflows/node_output_contracts_spec.rbindex 2b1705a35c3..b9bf4f3f939 100644--- a/plugins/discourse-workflows/spec/lib/discourse_workflows/node_output_contracts_spec.rb+++ b/plugins/discourse-workflows/spec/lib/discourse_workflows/node_output_contracts_spec.rb@@ -23,6 +23,34 @@ RSpec.describe DiscourseWorkflows::NodeType doexpect(overriding.reject(&:output_schema_resolver)).to be_emptyend+ it "requires every node without a user-defined output to declare it" do+ user_defined_output = %w[+ action:code+ action:data_table+ action:form+ action:modal+ action:set_fields+ action:split_out+ action:sql+ action:workflow_call+ flow:sticky_note+ trigger:form+ trigger:manual+ trigger:workflow_call+ ]++ undeclared =+ DiscourseWorkflows::Registry+ .nodes(include_disabled_plugins: true)+ .select do |node_class|+ next false if user_defined_output.include?(node_class.identifier)+ next false if node_class.singleton_class.instance_methods(false).include?(:output_schemas)+ Array(node_class.description.fetch(:output_contracts)).empty?+ end++ expect(undeclared.map(&:identifier)).to be_empty+ end+it "preserves declarations through nodes that only forward or reorder items" donode_classes = [DiscourseWorkflows::Nodes::Log::V1,diff --git a/plugins/discourse-workflows/spec/lib/discourse_workflows/nodes/http_request_spec.rb b/plugins/discourse-workflows/spec/lib/discourse_workflows/nodes/http_request_spec.rbindex bce1a517af5..84970c8a54d 100644--- a/plugins/discourse-workflows/spec/lib/discourse_workflows/nodes/http_request_spec.rb+++ b/plugins/discourse-workflows/spec/lib/discourse_workflows/nodes/http_request_spec.rb@@ -42,7 +42,7 @@ RSpec.describe DiscourseWorkflows::Nodes::HttpRequest::V1 do"headers" => include("content-type" => "application/json"),"status_code" => 200,)- expect(result).to have_key("status_message")+ expect(result).to match_node_output_schema(described_class, configuration: config)endit "splits top-level JSON array responses into separate output items" dodiff --git a/plugins/discourse-workflows/spec/lib/discourse_workflows/nodes/post_edited/v1_spec.rb b/plugins/discourse-workflows/spec/lib/discourse_workflows/nodes/post_edited/v1_spec.rbindex 07237020227..1eb50bfa111 100644--- a/plugins/discourse-workflows/spec/lib/discourse_workflows/nodes/post_edited/v1_spec.rb+++ b/plugins/discourse-workflows/spec/lib/discourse_workflows/nodes/post_edited/v1_spec.rb@@ -66,8 +66,6 @@ RSpec.describe DiscourseWorkflows::Nodes::PostEdited::V1 do)expect(output[:revision][:changes]).to include("raw")expect(output).to match_node_output_schema(described_class)- editor_schema = described_class.output_schemas.first.dig("properties", "editor")- expect(editor_schema).to include("properties" => DiscourseWorkflows::Schema::USER_PROPERTIES)endit "returns post and topic data" dodiff --git a/plugins/discourse-workflows/spec/lib/discourse_workflows/nodes/topic_spec.rb b/plugins/discourse-workflows/spec/lib/discourse_workflows/nodes/topic_spec.rbindex af9cb82a937..3fd5d1ac9d6 100644--- a/plugins/discourse-workflows/spec/lib/discourse_workflows/nodes/topic_spec.rb+++ b/plugins/discourse-workflows/spec/lib/discourse_workflows/nodes/topic_spec.rb@@ -562,16 +562,12 @@ RSpec.describe DiscourseWorkflows::Nodes::Topic::V1 doexpect(topic_data["tags"].map { |topic_tag| topic_tag["name"] }).to contain_exactly(tag.name,)- expect(topic_data["posts_count"]).to be_present- expect(topic_data["views"]).to be_present- expect(topic_data["like_count"]).to be_present- expect(topic_data["created_at"]).to be_present- expect(topic_data["bumped_at"]).to be_presentexpect(post_data).to include("id" => topic_1.first_post.id,"topic_id" => topic_1.id,"trust_level" => user.trust_level,)+ expect(topic_entry).to match_node_output_schema(described_class)endit "preloads selected custom fields when requested" dodiff --git a/plugins/discourse-workflows/spec/support/matchers/match_node_output_schema.rb b/plugins/discourse-workflows/spec/support/matchers/match_node_output_schema.rbindex 6140b11807e..882b78f9ff0 100644--- a/plugins/discourse-workflows/spec/support/matchers/match_node_output_schema.rb+++ b/plugins/discourse-workflows/spec/support/matchers/match_node_output_schema.rb@@ -2,26 +2,43 @@RSpec::Matchers.define :match_node_output_schema do |node_class, configuration: {}, input_schemas: [], output_index: 0|match do |output|- @resolved_schema = nil- @validation_errors = []- @non_hash_output = !output.is_a?(Hash)+ next false if (@non_hash_output = !output.is_a?(Hash))- if @non_hash_output- false- else- @resolved_schema =- node_class.output_schemas(configuration, input_schemas: input_schemas)[output_index] || {}-- if @resolved_schema.blank?- false- else- @validation_errors =- JSONSchemer.schema(@resolved_schema).validate(output.deep_stringify_keys).to_a- @validation_errors.empty?+ @resolved_schema =+ node_class.output_schemas(configuration, input_schemas: input_schemas)[output_index] || {}+ next false if @resolved_schema.blank?++ @validation_errors =+ JSONSchemer+ .schema(require_declared_properties(@resolved_schema))+ .validate(output.deep_stringify_keys)+ .to_a+ @validation_errors.empty?+ end++ def require_declared_properties(schema)+ case schema+ when Hash+ strict = schema.transform_values { |value| require_declared_properties(value) }+ return strict if !schema["properties"].is_a?(Hash)++ strict["required"] = schema["properties"].reject { |_, value| optional?(value) }.keys+ strict["properties"] = strict["properties"].to_h do |name, value|+ next name, value if !optional?(value) || value["type"] != "object"+ [name, { "anyOf" => [{ "type" => "object", "maxProperties" => 0 }, value] }]end+ strict+ when Array+ schema.map { |value| require_declared_properties(value) }+ else+ schemaendend+ def optional?(schema)+ schema.is_a?(Hash) && schema["x-optional"]+ end+failure_message do |output|node_name = node_class.name.presence || node_class.to_s