pact_broker 2.85.0 → 2.88.0

data/script/docs/generate-api-docs.rb

@@ -0,0 +1,117 @@
+#!/usr/bin/env ruby
+require "json"
+require "pathname"
+require "fileutils"
+
+EXAMPLES_FILE_PATTERN = "spec/fixtures/approvals/docs_*"
+API_DOCS_DIR = Pathname.new("docs/api")
+
+
+class Category
+  attr_reader :name, :examples, :not_options_examples
+
+  def initialize(name, examples)
+    @name = name
+    @examples = examples
+    @options_example = examples.find { | example | example[:request][:method] == "OPTIONS" }
+    @not_options_examples = examples.select { | example | example[:request][:method] != "OPTIONS" }
+  end
+
+  def path_template
+    not_options_examples.first[:request][:path_template]
+  end
+
+  def allowed_methods
+    if options_example
+      options_example[:response][:headers][:'Access-Control-Allow-Methods'].split(",").collect(&:strip).reject { |m| m == "OPTIONS" }
+    else
+      []
+    end
+  end
+
+  private
+
+  attr_reader :other_examples, :options_example
+
+end
+
+def generate_example_markdown_for_examples(name, examples)
+  category = Category.new(name, examples)
+
+
+  not_options_docs = category.not_options_examples.collect { | example | generate_example_markdown(example) }
+
+  allowed_methods = category.allowed_methods.collect{ | meth| "`#{meth}`"}.join(", ")
+
+"
+## #{name}
+
+Path: `#{category.path_template}`<br/>
+Allowed methods: #{allowed_methods}<br/>
+#{not_options_docs.join("\n")}
+"
+end
+
+def generate_example_markdown(hash)
+  body = nil
+  if hash[:request][:body]
+    body = "Body:
+
+```
+#{JSON.pretty_generate(hash[:request][:body])}
+```
+"
+  end
+
+"
+### #{hash[:request][:method]}
+
+#### Request
+
+Headers: `#{hash[:request][:headers]&.to_json}`<br/>
+#{body}
+
+#### Response
+
+Status: `#{hash[:response][:status]}`<br/>
+Headers: `#{hash[:response][:headers]&.to_json}`<br/>
+Body:
+
+```
+#{body_markdown(hash[:response][:body])}
+```
+"
+end
+
+def body_markdown(body)
+  body.is_a?(Hash) ? JSON.pretty_generate(body) : body
+end
+
+file_names = Dir.glob(EXAMPLES_FILE_PATTERN)
+
+examples = file_names.collect do | file_name |
+  JSON.parse(File.read(file_name), symbolize_names: true)
+end
+
+examples_by_category = examples.group_by { | hash | hash[:category] }
+
+FileUtils.rm_rf(API_DOCS_DIR)
+FileUtils.mkdir_p(API_DOCS_DIR)
+
+examples_by_category.each do | category, category_examples |
+
+  examples_by_name = category_examples.sort_by{ |hash| hash[:order] }.group_by { | hash | hash[:name] }
+
+  docs = examples_by_name.collect do | name, examples_for_name |
+    generate_example_markdown_for_examples(name, examples_for_name)
+  end
+
+  file_name = (API_DOCS_DIR / category.upcase).to_s + ".md"
+  contents = "
+# #{category}
+
+#{docs.join("\n")}
+"
+
+  File.open(file_name, "w") { |file| file << contents }
+end

data/script/docs/generate-configuration-docs.rb

@@ -1,7 +1,16 @@
 #!/usr/bin/env ruby
 
-require "yaml"
+INTRO = <<EOM
+<!-- This is a generated file. Please do not edit it directly. -->
+
+The Pact Broker supports configuration via environment variables or a YAML file.
 
+To configure the application using a YAML file, place it in the location `config/pact_broker.yml`,
+relative to the working directory of the application, or set the environment
+variable `PACT_BROKER_CONF` to the full path to the configuration file.
+EOM
+
+require "yaml"
 $stream = StringIO.new
 
 def write string
@@ -25,6 +34,7 @@ def in_backticks value
 end
 
 docs_dir = File.expand_path("../../../docs", __FILE__)
+configuration_doc_path = File.join(docs_dir, "CONFIGURATION.md")
 environment_variable_file = File.join(docs_dir, "configuration.yml")
 doc = YAML.load(File.read(environment_variable_file))
 
@@ -42,6 +52,8 @@ write "# Pact Broker Configuration\n\n"
 
 write "\n"
 
+write INTRO
+
 doc["groups"].each do | group |
   write "<br/>\n\n"
   write "## #{group["title"]}\n\n<hr/>\n"
@@ -55,9 +67,17 @@ doc["groups"].each do | group |
     write "### #{name}\n\n"
     write "#{metadata["description"]}\n\n"
 
+    write "**YAML configuration key name:** #{in_backticks(name)}<br/>"
+    write "**Environment variable name:** `PACT_BROKER_#{name.upcase}`<br/>"
+    write "**Supported versions:** #{metadata["supported_versions"]}<br/>" if metadata["supported_versions"]
     write "**Required:** #{metadata["required"] || "false"}<br/>" if metadata["required"]
     write "**Format:** #{metadata["format"]}<br/>" if metadata["format"]
-    write "**Default:** #{in_backticks(metadata["default"])}<br/>" if !metadata["default"].nil?
+
+    write "**Default:** #{in_backticks(metadata["default_value"])}<br/>" if !metadata["default_value"].nil?
+    write "**Default:** #{metadata["default_description"]}<br/>" if !metadata["default_description"].nil?
+    if metadata["allowed_values_description"]
+      write "**Allowed values:** #{metadata["allowed_values_description"]}<br/>"
+    end
     if metadata["allowed_values"]
       allowed_values = metadata["allowed_values"].collect{ |val| in_backticks(val) }.join(", ")
       write "**Allowed values:** #{allowed_values}<br/>"
@@ -72,7 +92,7 @@ doc["groups"].each do | group |
   end
 end
 
-File.open(File.join(docs_dir, "CONFIGURATION.md"), "w") { |file| file << $stream.string }
+File.open(configuration_doc_path, "w") { |file| file << $stream.string }
 
 required_env_vars = []
 
@@ -84,3 +104,4 @@ end
 
 puts "Required:"
 puts required_env_vars
+puts configuration_doc_path

data/script/docs/regenerate-api-docs.sh

@@ -0,0 +1,11 @@
+#!/bin/sh
+rm spec/fixtures/approvals/docs_webhooks*
+bundle exec rspec spec/integration/webhooks_documentation_spec.rb
+script/test/approval-all.sh
+bundle exec rspec spec/integration/webhooks_documentation_spec.rb
+script/docs/generate-api-docs.rb
+
+git add spec/integration/webhooks_documentation_spec.rb
+git add spec/fixtures/approvals
+git add docs/api
+git add script/docs/generate-api-docs.rb

data/script/generate-erd

@@ -0,0 +1,55 @@
+#! /usr/bin/env ruby
+
+require "sequel"
+Sequel::Model.plugin :subclasses
+
+DATABASE_CREDENTIALS = {
+  adapter: "postgres",
+  database: ENV["DATABASE"] || "postgres",
+  username: ENV["DATABASE_USERNAME"] || "postgres",
+  password: ENV["DATABASE_PASSWORD"] || "postgres",
+  host: "localhost",
+  :encoding => "utf8"
+}
+Sequel.connect(DATABASE_CREDENTIALS)
+
+$LOAD_PATH.unshift "./lib"
+$LOAD_PATH.unshift "./tasks"
+ENV["RACK_ENV"] = "development"
+require "pact_broker/db/models"
+
+def generate_erd_graphviz()
+  associations = []
+  Sequel::Model.descendents.each do |model|
+    next if model.name.nil?
+    model.associations.each do |a|
+      ar = model.association_reflection(a)
+      associations << [model.name, ar[:type], ar.associated_class.name]
+    end
+  end
+  styles = {
+    :many_to_one=>:bold,
+    :one_to_many=>:solid,
+    :many_to_many=>:dashed,
+    :one_to_one=>:dotted
+  }
+
+  graph = "digraph G {\n"
+  graph += associations.uniq.map{|c, t, ac| "  \"#{c}\" -> \"#{ac}\" [style=#{styles[t]}];"}.sort.join("\n")
+  graph += "\n}"
+
+  graph
+end
+
+puts "Usage:"
+puts "generate-erd [erd-filename]"
+puts "CAUTION: Please make sure that you have graphviz installed"
+puts
+
+GRAPHVIZ_FILENAME = ARGV[0] || "erd"
+
+puts "Generating graphviz file ..."
+File.write("#{GRAPHVIZ_FILENAME}.dot", generate_erd_graphviz())
+
+puts "Converting graphviz file to a pdf"
+`dot -Tpdf "#{GRAPHVIZ_FILENAME}.dot" > "#{GRAPHVIZ_FILENAME}.pdf"`

data/spec/features/create_webhook_spec.rb

@@ -6,10 +6,14 @@ describe "Creating a webhook" do
   let(:headers) { {"CONTENT_TYPE" => "application/json"} }
   let(:response_body) { JSON.parse(subject.body, symbolize_names: true)}
   let(:webhook_json) { webhook_hash.to_json }
+  let(:provider) { nil }
+  let(:consumer) { nil }
   let(:webhook_hash) do
     {
       description: "trigger build",
       enabled: false,
+      provider: provider,
+      consumer: consumer,
       events: [{
         name: "contract_content_changed"
       }],
@@ -23,7 +27,7 @@ describe "Creating a webhook" do
           a: "body"
         }
       }
-    }
+    }.compact
   end
 
   subject { post(path, webhook_json, headers) }
@@ -64,33 +68,74 @@ describe "Creating a webhook" do
 
   context "for a provider" do
     let(:path) { "/webhooks" }
+    let(:provider) { { name: "Some Provider" } }
 
-    before do
-      webhook_hash[:provider] = { name: "Some Provider" }
-    end
-
-    its(:status) { is_expected.to be 201 }
+    its(:status) { is_expected.to eq 201 }
 
     it "creates a webhook without a consumer" do
       subject
       expect(PactBroker::Webhooks::Webhook.first.provider).to_not be nil
       expect(PactBroker::Webhooks::Webhook.first.consumer).to be nil
     end
+
+    context "with label" do
+      let(:provider) { { label: "my_label" } }
+
+      its(:status) { is_expected.to eq 201 }
+
+      it "creates a webhook without explicit consumer and provider with provider label" do
+        subject
+        expect(PactBroker::Webhooks::Webhook.first.provider).to be nil
+        expect(PactBroker::Webhooks::Webhook.first.consumer).to be nil
+        expect(PactBroker::Webhooks::Webhook.first.provider_label).to eq "my_label"
+      end
+    end
+
+    context "with both label and name" do
+      let(:provider) { { name: "Some Provider", label: "my_label" } }
+
+      its(:status) { is_expected.to eq 400 }
+
+      it "returns the validation errors" do
+        expect(response_body[:errors]).to_not be_empty
+      end
+    end
   end
 
   context "for a consumer" do
     let(:path) { "/webhooks" }
-    before do
-      webhook_hash[:consumer] = { name: "Some Consumer" }
-    end
+    let(:consumer) { { name: "Some Consumer" } }
 
-    its(:status) { is_expected.to be 201 }
+    its(:status) { is_expected.to eq 201 }
 
     it "creates a webhook without a provider" do
       subject
       expect(PactBroker::Webhooks::Webhook.first.consumer).to_not be nil
       expect(PactBroker::Webhooks::Webhook.first.provider).to be nil
     end
+
+    context "with label" do
+      let(:consumer) { { label: "my_label" } }
+
+      its(:status) { is_expected.to eq 201 }
+
+      it "creates a webhook without explicit consumer and provider with consumer label" do
+        subject
+        expect(PactBroker::Webhooks::Webhook.first.provider).to be nil
+        expect(PactBroker::Webhooks::Webhook.first.consumer).to be nil
+        expect(PactBroker::Webhooks::Webhook.first.consumer_label).to eq "my_label"
+      end
+    end
+
+    context "with both label and name" do
+      let(:consumer) { { name: "Some Consumer", label: "my_label" } }
+
+      its(:status) { is_expected.to eq 400 }
+
+      it "returns the validation errors" do
+        expect(response_body[:errors]).to_not be_empty
+      end
+    end
   end
 
   context "with no consumer or provider" do

data/spec/features/get_pact_spec.rb

@@ -6,7 +6,7 @@ describe "retrieving a pact" do
     let(:path) { "/pacts/provider/a%20provider/consumer/a%20consumer/version/1.2.3A" }
 
     before do
-      TestDataBuilder.new.create_pact_with_hierarchy("A Consumer", "1.2.3a", "A Provider").and_return(:pact)
+      td.create_pact_with_hierarchy("A Consumer", "1.2.3a", "A Provider").and_return(:pact)
     end
 
     context "when case sensitivity is turned on" do
@@ -35,8 +35,7 @@ describe "retrieving a pact" do
     let(:path) { "/pacts/provider/a%20provider/consumer/a%20consumer/latest/PROD" }
 
     before do
-      TestDataBuilder.new
-        .create_consumer("A Consumer")
+      td.create_consumer("A Consumer")
         .create_consumer_version("1.2.3")
         .create_consumer_version_tag("prod")
         .create_provider("A Provider")

data/spec/fixtures/approvals/docs_webhooks_executing_a_saved_webhook_options.approved.json

@@ -0,0 +1,20 @@
+{
+  "category": "Webhooks",
+  "name": "Executing a saved webhook",
+  "order": 33,
+  "request": {
+    "method": "OPTIONS",
+    "path_template": "/webhooks/:uuid/execute",
+    "path": "/webhooks/d2181b32-8b03-4daf-8cc0-d9168b2f6fac/execute",
+    "headers": {
+      "Accept": "application/hal+json"
+    }
+  },
+  "response": {
+    "status": 200,
+    "headers": {
+      "Access-Control-Allow-Methods": "POST, OPTIONS"
+    },
+    "body": ""
+  }
+}

data/spec/fixtures/approvals/docs_webhooks_executing_a_saved_webhook_post.approved.json

@@ -0,0 +1,43 @@
+{
+  "category": "Webhooks",
+  "name": "Executing a saved webhook",
+  "order": 35,
+  "request": {
+    "method": "POST",
+    "path_template": "/webhooks/:uuid/execute",
+    "path": "/webhooks/d2181b32-8b03-4daf-8cc0-d9168b2f6fac/execute",
+    "headers": {
+      "Content-Type": "application/json",
+      "Accept": "application/hal+json"
+    }
+  },
+  "response": {
+    "status": 200,
+    "headers": {
+      "Content-Type": "application/hal+json;charset=utf-8"
+    },
+    "body": {
+      "request": {
+        "headers": {
+          "accept": "*/*",
+          "user-agent": "Pact Broker v2.87.0",
+          "content-type": "application/json"
+        },
+        "body": {
+          "pactUrl": "http://example.org/pacts/provider/Bar/consumer/Foo/pact-version/3e193ecb37ad04b43ce974a38352c704b2e0ed6b/metadata/Y3ZuPTImdz10cnVl"
+        },
+        "url": "/example"
+      },
+      "response": {
+        "status": 200,
+        "headers": {
+        },
+        "body": ""
+      },
+      "logs": "[2021-09-01T10:07:21Z] DEBUG: Webhook context {\"base_url\":\"http://example.org\",\"event_name\":\"test\"}\n[2021-09-01T10:07:21Z] INFO: HTTP/1.1 POST https://example.org/example\n[2021-09-01T10:07:21Z] INFO: accept: */*\n[2021-09-01T10:07:21Z] INFO: user-agent: Pact Broker v2.87.0\n[2021-09-01T10:07:21Z] INFO: content-type: application/json\n[2021-09-01T10:07:21Z] INFO: {\"pactUrl\":\"http://example.org/pacts/provider/Bar/consumer/Foo/pact-version/3e193ecb37ad04b43ce974a38352c704b2e0ed6b/metadata/Y3ZuPTImdz10cnVl\"}\n[2021-09-01T10:07:21Z] INFO: HTTP/1.0 200 \n[2021-09-01T10:07:21Z] INFO: \n",
+      "success": true,
+      "_links": {
+      }
+    }
+  }
+}

data/spec/fixtures/approvals/docs_webhooks_executing_an_unsaved_webhook_options.approved.json

@@ -0,0 +1,20 @@
+{
+  "category": "Webhooks",
+  "name": "Executing an unsaved webhook",
+  "order": 37,
+  "request": {
+    "method": "OPTIONS",
+    "path_template": "/webhooks/execute",
+    "path": "/webhooks/execute",
+    "headers": {
+      "Accept": "application/hal+json"
+    }
+  },
+  "response": {
+    "status": 200,
+    "headers": {
+      "Access-Control-Allow-Methods": "POST, OPTIONS"
+    },
+    "body": ""
+  }
+}

data/spec/fixtures/approvals/docs_webhooks_executing_an_unsaved_webhook_post.approved.json

@@ -0,0 +1,63 @@
+{
+  "category": "Webhooks",
+  "name": "Executing an unsaved webhook",
+  "order": 39,
+  "request": {
+    "method": "POST",
+    "path_template": "/webhooks/execute",
+    "path": "/webhooks/execute",
+    "headers": {
+      "Content-Type": "application/json",
+      "Accept": "application/hal+json"
+    },
+    "body": {
+      "description": "an example webhook",
+      "events": [
+        {
+          "name": "contract_content_changed"
+        }
+      ],
+      "request": {
+        "method": "POST",
+        "url": "https://example.org/example",
+        "username": "username",
+        "password": "password",
+        "headers": {
+          "Accept": "application/json"
+        },
+        "body": {
+          "pactUrl": "${pactbroker.pactUrl}"
+        }
+      }
+    }
+  },
+  "response": {
+    "status": 200,
+    "headers": {
+      "Content-Type": "application/hal+json;charset=utf-8"
+    },
+    "body": {
+      "request": {
+        "headers": {
+          "accept": "application/json",
+          "user-agent": "Pact Broker v2.87.0",
+          "authorization": "**********"
+        },
+        "body": {
+          "pactUrl": "http://example.org/pacts/provider/Bar/consumer/Foo/pact-version/3e193ecb37ad04b43ce974a38352c704b2e0ed6b/metadata/Y3ZuPTImdz10cnVl"
+        },
+        "url": "/example"
+      },
+      "response": {
+        "status": 200,
+        "headers": {
+        },
+        "body": ""
+      },
+      "logs": "[2021-09-01T10:07:21Z] DEBUG: Webhook context {\"base_url\":\"http://example.org\",\"event_name\":\"test\"}\n[2021-09-01T10:07:21Z] INFO: HTTP/1.1 POST https://example.org/example\n[2021-09-01T10:07:21Z] INFO: accept: application/json\n[2021-09-01T10:07:21Z] INFO: user-agent: Pact Broker v2.87.0\n[2021-09-01T10:07:21Z] INFO: authorization: **********\n[2021-09-01T10:07:21Z] INFO: {\"pactUrl\":\"http://example.org/pacts/provider/Bar/consumer/Foo/pact-version/3e193ecb37ad04b43ce974a38352c704b2e0ed6b/metadata/Y3ZuPTImdz10cnVl\"}\n[2021-09-01T10:07:21Z] INFO: HTTP/1.0 200 \n[2021-09-01T10:07:21Z] INFO: \n",
+      "success": true,
+      "_links": {
+      }
+    }
+  }
+}

data/spec/fixtures/approvals/docs_webhooks_logs_of_triggered_webhook_get.approved.json

@@ -0,0 +1,20 @@
+{
+  "category": "Webhooks",
+  "name": "Logs of triggered webhook",
+  "order": 49,
+  "request": {
+    "method": "GET",
+    "path_template": "/triggered-webhooks/:uuid/logs",
+    "path": "/triggered-webhooks/6cd5cc48-db3c-4a4c-a36d-e9bedeb9d91e/logs",
+    "headers": {
+      "Accept": "application/hal+json"
+    }
+  },
+  "response": {
+    "status": 200,
+    "headers": {
+      "Content-Type": "text/plain;charset=utf-8"
+    },
+    "body": "logs"
+  }
+}

data/spec/fixtures/approvals/docs_webhooks_logs_of_triggered_webhook_options.approved.json

@@ -0,0 +1,20 @@
+{
+  "category": "Webhooks",
+  "name": "Logs of triggered webhook",
+  "order": 51,
+  "request": {
+    "method": "OPTIONS",
+    "path_template": "/triggered-webhooks/:uuid/logs",
+    "path": "/triggered-webhooks/6cd5cc48-db3c-4a4c-a36d-e9bedeb9d91e/logs",
+    "headers": {
+      "Accept": "application/hal+json"
+    }
+  },
+  "response": {
+    "status": 200,
+    "headers": {
+      "Access-Control-Allow-Methods": "GET, OPTIONS"
+    },
+    "body": ""
+  }
+}

data/spec/fixtures/approvals/docs_webhooks_pact_webhooks_get.approved.json

@@ -0,0 +1,45 @@
+{
+  "category": "Webhooks",
+  "name": "Pact webhooks",
+  "order": 25,
+  "request": {
+    "method": "GET",
+    "path_template": "/pacts/provider/:provider_name/consumer/:consumer_name/webhooks",
+    "path": "/pacts/provider/Bar/consumer/Foo/webhooks",
+    "headers": {
+      "Accept": "application/hal+json"
+    }
+  },
+  "response": {
+    "status": 200,
+    "headers": {
+      "Content-Type": "application/hal+json;charset=utf-8"
+    },
+    "body": {
+      "_links": {
+        "self": {
+          "title": "Pact webhooks",
+          "href": "http://example.org/pacts/provider/Bar/consumer/Foo/webhooks"
+        },
+        "pb:create": {
+          "title": "POST to create a webhook",
+          "href": "http://example.org/pacts/provider/Bar/consumer/Foo/webhooks"
+        },
+        "pb:webhooks": [
+          {
+            "title": "A webhook for the pact between Foo and Bar",
+            "name": "an example webhook",
+            "href": "http://example.org/webhooks/d2181b32-8b03-4daf-8cc0-d9168b2f6fac"
+          }
+        ],
+        "curies": [
+          {
+            "name": "pb",
+            "href": "http://example.org/doc/webhooks-{rel}",
+            "templated": true
+          }
+        ]
+      }
+    }
+  }
+}

data/spec/fixtures/approvals/docs_webhooks_pact_webhooks_options.approved.json

@@ -0,0 +1,20 @@
+{
+  "category": "Webhooks",
+  "name": "Pact webhooks",
+  "order": 27,
+  "request": {
+    "method": "OPTIONS",
+    "path_template": "/pacts/provider/:provider_name/consumer/:consumer_name/webhooks",
+    "path": "/pacts/provider/Bar/consumer/Foo/webhooks",
+    "headers": {
+      "Accept": "application/hal+json"
+    }
+  },
+  "response": {
+    "status": 200,
+    "headers": {
+      "Access-Control-Allow-Methods": "POST, GET, OPTIONS"
+    },
+    "body": ""
+  }
+}