pact_broker 2.77.0 → 2.80.0

data/lib/pact_broker/diagnostic/app.rb

@@ -1,6 +1,6 @@
-require 'pact_broker/diagnostic/resources/heartbeat'
-require 'pact_broker/diagnostic/resources/dependencies'
-require 'webmachine/adapters/rack_mapped'
+require "pact_broker/diagnostic/resources/heartbeat"
+require "pact_broker/diagnostic/resources/dependencies"
+require "webmachine/adapters/rack_mapped"
 
 module PactBroker
   module Diagnostic
@@ -11,7 +11,7 @@ module PactBroker
       end
 
       def call env
-        if env['PATH_INFO'].start_with? "/diagnostic/"
+        if env["PATH_INFO"].start_with? "/diagnostic/"
           @app.call(env)
         else
           [404, {}, []]
@@ -19,10 +19,10 @@ module PactBroker
       end
 
       def build_diagnostic_app
-        app = Webmachine::Application.new do |app|
-          app.routes do
-            add ['diagnostic','status','heartbeat'], Diagnostic::Resources::Heartbeat, {resource_name: 'diagnostic_heartbeat'}
-            add ['diagnostic','status','dependencies'], Diagnostic::Resources::Dependencies, {resource_name: 'diagnostic_dependencies'}
+        app = Webmachine::Application.new do |webmachine_app|
+          webmachine_app.routes do
+            add ["diagnostic","status","heartbeat"], Diagnostic::Resources::Heartbeat, {resource_name: "diagnostic_heartbeat"}
+            add ["diagnostic","status","dependencies"], Diagnostic::Resources::Dependencies, {resource_name: "diagnostic_dependencies"}
           end
         end
 

data/lib/pact_broker/diagnostic/resources/base_resource.rb

@@ -1,5 +1,5 @@
-require 'webmachine'
-require 'pact_broker/api/resources/authentication'
+require "webmachine"
+require "pact_broker/api/resources/authentication"
 
 module PactBroker
   module Diagnostic

data/lib/pact_broker/diagnostic/resources/dependencies.rb

@@ -1,6 +1,6 @@
-require 'pact_broker/diagnostic/resources/base_resource'
-require 'pact_broker/db'
-require 'pact_broker/logging'
+require "pact_broker/diagnostic/resources/base_resource"
+require "pact_broker/db"
+require "pact_broker/logging"
 
 module PactBroker
   module Diagnostic

data/lib/pact_broker/diagnostic/resources/heartbeat.rb

@@ -1,4 +1,4 @@
-require 'pact_broker/diagnostic/resources/base_resource'
+require "pact_broker/diagnostic/resources/base_resource"
 
 module PactBroker
   module Diagnostic

data/lib/pact_broker/doc/controllers/app.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
-require 'padrino-core'
-require 'redcarpet'
+require "padrino-core"
+require "redcarpet"
 
 Tilt.prefer Tilt::RedcarpetTemplate
 
@@ -9,15 +9,15 @@ module PactBroker
     module Controllers
       class App < Padrino::Application
 
-        set :root, File.join(File.dirname(__FILE__), '..')
+        set :root, File.join(File.dirname(__FILE__), "..")
         set :show_exceptions, true
 
         MAPPINGS = {
-          'webhooks-create' => 'webhooks',
-          'webhooks-webhooks' => 'webhooks',
-          'webhook' => 'webhooks',
-          'can-i-deploy-pacticipant-version-to-tag' => 'can-i-deploy',
-          'pacticipant' => 'pacticipants'
+          "webhooks-create" => "webhooks",
+          "webhooks-webhooks" => "webhooks",
+          "webhook" => "webhooks",
+          "can-i-deploy-pacticipant-version-to-tag" => "can-i-deploy",
+          "pacticipant" => "pacticipants"
         }.freeze
 
         helpers do
@@ -27,7 +27,7 @@ module PactBroker
           end
 
           def resource_exists? rel_name, context = nil
-            File.exist? File.join(self.class.root, 'views', "#{view_name_for(rel_name, context)}.markdown")
+            File.exist? File.join(self.class.root, "views", "#{view_name_for(rel_name, context)}.markdown")
           end
         end
 
@@ -51,7 +51,7 @@ module PactBroker
           # https://www.acunetix.com/blog/articles/automated-detection-of-host-header-attacks/
           # Either use the explicitly configured base url or an empty string,
           # rather than request.base_url, which uses the X-Forwarded headers.
-          env["pactbroker.base_url"] || ''
+          env["pactbroker.base_url"] || ""
         end
       end
     end

data/lib/pact_broker/doc/views/can-i-deploy.markdown

@@ -8,7 +8,9 @@ A simplified resource that accepts the same parameters as the basic usage of the
 
 * _pacticipant_: The name of the pacticipant (application) you want to deploy (required).
 * _version_: The version of the pacticipant (application) you want to deploy (required).
-* _to_: The tag used to identify the environment into which you wish to deploy the application (eg. `test` or `prod`). This assumes you have already tagged the currently deployed versions of each of the integrated applications with the same tag. To be specific, the logic checks if the application version you have specified is compatible with the latest versions _for the specified tag_ of all the other applications it is integrated with. This parameter is optional - if not specified, it checks for compatiblity with the latest version of all the integrated applications.
+* _environment_: The name of the environment into which the pacticipant (application) is to be deployed. 
+* _to_: The tag used to identify the environment into which you wish to deploy the application (eg. `test` or `prod`). Deprecated - use the `environment=ENVIRONMENT` parameter in preference to the `to=TAG` parameter as deployments and environments are now explictly supported.
+* _ignore[]_: The name of the pacticipant to ignore when determining if it is safe to deploy (optional). May be used multiple times.
 
 
-If you have an environment that you identify with the tag `prod`, and each time you deployed an application to the prod environment you tagged the relevant application version in the Pact Broker with the tag `prod`, then calling `/can-i-deploy?pacticipant=Foo&version=734137278d&to=prod` will check that version 734137278d of Foo has a successful verification result with each of the integrated application versions that are currently in prod. That is, it is safe to deploy.
+If you have an environment that you identify with the name `prod`, and each time you deployed an application to the prod environment you recorded the deployment of relevant application version in the Pact Broker using `record-deployment`, then calling `/can-i-deploy?pacticipant=Foo&version=734137278d&environment=prod` will check that version 734137278d of Foo has a successful verification result with each of the integrated application versions that are currently in prod. That is, it is safe to deploy.

data/lib/pact_broker/doc/views/index/environment.markdown

@@ -0,0 +1,37 @@
+# Environment
+
+Allowed methods: `GET`, `PUT`, `DELETE`
+
+Path: `/environment/{uuid}`
+
+## Viewing an environment
+
+Example:
+
+    curl http://${PACT_BROKER_HOST}/environments/79060381-269c-4769-9894-9ec3cab44729 \
+      -H "Accept: application/hal+json"
+    {
+      "uuid": "79060381-269c-4769-9894-9ec3cab44729",
+      "name": "test",
+      "displayName": "Test",
+      "production": false
+    }
+
+## Updating an environment
+
+Example:
+
+    curl -X PUT http://${PACT_BROKER_HOST}/environments/79060381-269c-4769-9894-9ec3cab44729 \
+      -H "Content-Type: application/json" \
+      -H "Accept: application/hal+json" \
+      -d '{
+          "name": "test",
+          "displayName": "Test",
+          "production": false
+        }'
+
+## Deleting an environment
+
+Example:
+
+    curl -v -X DELETE http://${PACT_BROKER_HOST}/environments/79060381-269c-4769-9894-9ec3cab44729

data/lib/pact_broker/doc/views/index/environments.markdown

@@ -0,0 +1,53 @@
+# Environments
+
+Allowed methods: `GET`, `POST`
+
+Path: `/environments`
+
+## Creating an environment
+
+Send a POST to `/environments` with the environment payload.
+
+Example:
+
+    curl http://${PACT_BROKER_HOST}/environments \
+      -H "Content-Type: application/json" \
+      -H "Accept: application/hal+json" \
+      -d '{
+          "name": "test",
+          "displayName": "Test",
+          "production": false
+        }'
+
+Alternatively, you can use the HAL Browser.
+
+* Click on the `API Browser` link at the top of the Pact Broker index page.
+* In the `Links` section on the left, locate the `pb:environments` relation, and click on the yellow `!` "Perform non-GET request" button.
+* In the `Body:` text box, fill in the required JSON properties.
+* Click `Make Request`.
+
+Properties:
+
+* `uuid`: System generated unique identifier.
+* `name`: Must be unique. No spaces allowed. This will be the name used in the `can-i-deploy` and `record-deployment` CLI commands. eg. "payments-sit-1"
+* `displayName`: A more verbose name for the environment. "Payments Team SIT 1"
+* `production`: Whether or not this environment is a production environment.
+
+If all the services in the Broker are deployed to the same "public" internet, then there only needs to be one Production environment. If there are multiple segregated production environments (eg. when maintaining on-premises software for multiple customers ) then you should create a separate production Environment for each logical deployment environment.
+
+## Listing environments
+
+`GET /environments`
+
+    {
+      "_embedded": {
+        "environments": [
+          {
+            "uuid": "79060381-269c-4769-9894-9ec3cab44729",
+            "name": "production",
+            "displayName": "Production",
+            "production": true
+          }
+        ]
+      }
+    }

data/lib/pact_broker/doc/views/index/latest-pact-versions.markdown

@@ -1,5 +1,5 @@
 # Latest pact versions
 
-Allowed methods: GET
+Allowed methods: `GET`
 
 A list of the latest pact versions for each consumer/provider pair. The "latest" is determined by inspecting the consumer version used when each pact was published.

data/lib/pact_broker/doc/views/index/pacticipant-version-tag.markdown

@@ -1,6 +1,7 @@
 # Pacticipant version tag
 
 Allowed methods: `GET`, `PUT`, `DELETE`
+
 Path: `/pacticipants/{pacticipant}/versions/{version}/tags/{tag}`
 
 To create a tag, send an empty request with the URL specified above and `Content-Type` of `application/json`.

data/lib/pact_broker/doc/views/index/pacticipants.markdown

@@ -1,14 +1,36 @@
 # Pacticipants
 
-Allowed methods: GET, PATCH, DELETE
+Allowed methods: `GET`, `PATCH`, `DELETE`
+
+Path: `/pacticipants`
 
 "Pacticipant" - a party that participates in a pact (ie. a Consumer or a Provider).
 
-### Creating pacticipants
+## Creating pacticipants
+
+### When publishing pacts
+
 Participants are created automatically when a pact is published to the pact broker. The name is based on the URL compontents used to publish the pact (ie. /pacts/provider/$PROVIDER\_NAME/consumer/$CONSUMER\_NAME/version/$CONSUMER\_VERSION), not on the contents of the pact, as the Pact Broker is designed to be agnostic of the actual pact format as much as possible.
 
+### Explicitly
+
+```
+$ curl -X POST http://pact-broker/pacticipants \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/hal+json" \
+  -d '{ "name": "my-consumer", "displayName": "My Consumer" }'
+```
+
+Properties:
+
+`name`: The name that will be used to identify the pacticipant in URLs.
+`displayName`: The name to display in the UI
+`repositoryUrl`: The URL at which to view the repository in a browser.
+`repositoryName`: The name of the repository, without any namespace.
+`repositoryNamespace`: The namespace of the repository (called "organization" in Github).
+
+## Deleting pacticipants
 
-### Deleting pacticipants
 Deleting a pacticipant will delete all associated pacts, versions, tags and webhooks. To delete a pacticipant, send a DELETE request to the relevant pacticipant URL via the HAL browser or any other HTTP client.
 
     $ curl -X DELETE http://pact-broker/pacticipants/My%20Consumer

data/lib/pact_broker/doc/views/index/publish-contracts.markdown

@@ -0,0 +1,120 @@
+# Publish Contracts
+
+Allowed methods: `POST`
+
+Path: `/contracts/publish`
+
+This is the preferred endpoint with which to publish contracts (previously, contracts were published using multiple calls to different endpoints to create the tag and contract resources). To detect whether this endpoint exists in a particular version of the Pact Broker, make a request to the index resource, and locate the `pb:publish-contracts` relation. Do a `POST` to the href specified for that relation. 
+
+The previous tag and pact endpoints are still supported, however, future features that build on this endpoint may not be able to be backported into those endpoints (eg. publishing pacts with a branch).
+
+## Parameters
+* `pacticipantName`: the name of the application. Required.
+* `pacticipantVersionNumber`: the version number of the application. Required. It is recommended that this should be or include the git SHA. See [http://docs.pact.io/versioning](http://docs.pact.io/versioning).
+* `branch`: The git branch name. Optional but strongly recommended.
+* `tags`: The consumer version tags. Use of the branch parameter is preferred now. Optional.
+* `buildUrl`: The CI/CD build URL. Optional.
+* `contracts`
+  * `consumerName`: the name of the consumer. Required. Must match the pacticipant name and the consumer name inside the pact. While this field may seem redundant currently, this endpoint will be extended to support publication of provider generated, non-pact contracts, and the consumerName and providerName fields will be used to indicate which role the pacticipant is taking in the contract.
+  * `providerName`: the name of the provider. Required.
+  * `specification`: currently, only contracts of type "pact" are supported, but this will be extended in the future. Required.
+  * `contentType`: currently, only contracts with a content type of "application/json" are supported. Required.
+  * `content`: the content of the contract. Must be Base64 encoded. Required.
+  * `onConflict`: Specifies the action to take when a contract for this consumer version already exists with different content. Allowed values are `overwrite`|`merge`. Optional. Defaults to `overwrite`. When `merge` is specified, the interactions are merged into any pre-existing pact. This is required when the tests that generate pact files are split over multiple nodes.
+
+## Example
+
+    POST http://broker/contracts/publish
+    {
+      "pacticipantName": "Foo",
+      "pacticipantVersionNumber": "dc5eb529230038a4673b8c971395bd2922d8b240",
+      "branch": "main",
+      "tags": ["main"],
+      "buildUrl": "https://ci/builds/1234",
+      "contracts": [
+        {
+          "consumerName": "Foo",
+          "providerName": "Bar",
+          "specification": "pact",
+          "contentType": "application/json",
+          "content": "<base64 encoded JSON pact>",
+          "onConflict": "overwrite"
+        }
+      ]
+    }
+    
+    {
+      {
+        "logs": [
+          {
+            "level": "debug",
+            "message": "Created Foo version dc5eb529230038a4673b8c971395bd2922d8b240 with branch main and tags main"
+          },
+          {
+            "level": "info",
+            "message": "Pact published for Foo version dc5eb529230038a4673b8c971395bd2922d8b240 and provider Bar."
+          },
+          {
+            "level": "debug",
+            "message": "  Events detected: contract_published, contract_content_changed (first time any pact published for this consumer with consumer version tagged main)"
+          },
+          {
+            "level": "debug",
+            "message": "  Webhook \"foo webhook\" triggered for event contract_content_changed.\n    See logs at http://example.org/triggered-webhooks/1234/logs\""
+          }
+        ],
+        "_embedded": {
+          "pacticipant": {
+            "name": "Foo",
+            "_links": {
+              "self": {
+                "href": "http://example.org/pacticipants/Foo"
+              }
+            }
+          },
+          "version": {
+            "number": "1",
+            "branch": "main",
+            "buildUrl": "http://ci/builds/1234",
+            "_links": {
+              "self": {
+                "title": "Version",
+                "name": "dc5eb529230038a4673b8c971395bd2922d8b240",
+                "href": "http://example.org/pacticipants/Foo/versions/dc5eb529230038a4673b8c971395bd2922d8b240"
+              }
+            }
+          }
+        },
+        "_links": {
+          "pb:pacticipant": {
+            "title": "Pacticipant",
+            "name": "Foo",
+            "href": "http://example.org/pacticipants/Foo"
+          },
+          "pb:pacticipant-version": {
+            "title": "Pacticipant version",
+            "name": "1",
+            "href": "http://example.org/pacticipants/Foo/versions/dc5eb529230038a4673b8c971395bd2922d8b240"
+          },
+          "pb:pacticipant-version-tags": [
+            {
+              "title": "Tag",
+              "name": "a",
+              "href": "http://example.org/pacticipants/Foo/versions/dc5eb529230038a4673b8c971395bd2922d8b240/tags/a"
+            },
+            {
+              "title": "Tag",
+              "name": "b",
+              "href": "http://example.org/pacticipants/Foo/versions/dc5eb529230038a4673b8c971395bd2922d8b240/tags/b"
+            }
+          ],
+          "pb:contracts": [
+            {
+              "title": "Pact",
+              "name": "Pact between Foo (dc5eb529230038a4673b8c971395bd2922d8b240) and Bar",
+              "href": "http://example.org/pacts/provider/Bar/consumer/Foo/version/dc5eb529230038a4673b8c971395bd2922d8b240"
+            }
+          ]
+        }
+      }
+    }

data/lib/pact_broker/doc/views/provider-pacts-for-verification.markdown

@@ -10,37 +10,48 @@ Returns a deduplicated list of pacts to be verified by the specified provider.
 
 ### Body
 
-Example: This data structure represents the way a user might specify "I want to verify the latest 'master' pact, all 'prod' pacts, and when I publish the verification results, I'm going to tag the provider version with 'master'"
+Example: This data structure represents the way a user might specify "I want to verify the latest 'main' pact, all the pacts for the consumer versions that are currently deployed, and when I publish the verification results, the provider version will be be on the "main" branch.
 
     {
       "consumerVersionSelectors": [
         {
-          "tag": "master",
-          "latest": true
-        },{
-          "tag": "prod"
+          "branch": "main"
+        },
+        {
+          "deployed": true
         }
       ],
-      "providerVersionTags": ["master"],
+      "providerVersionBranch": "main",
       "includePendingStatus": true,
       "includeWipPactsSince": "2020-01-01"
     }
 
+`consumerVersionSelectors.branch`: the branch name of the consumer versions to get the pacts for. Use of this selector requires that the consumer has configured a branch name when publishing the pacts.
+
+`consumerVersionSelectors.fallbackBranch`: the name of the branch to fallback to if the specified `branch` does not exist. This is useful when the consumer and provider use matching branch names to coordinate the development of new features.
+
+`consumerVersionSelectors.deployed`: if the key is specified, can only be set to `true`. Returns the pacts for all versions of the consumer that are currently deployed to any environment. Use of this selector requires that the deployment of the consumer application is recorded in the Pact Broker using the `pact-broker record-deployment` CLI.
 
-`consumerVersionSelectors.tag`: the tag name(s) of the consumer versions to get the pacts for.
+`consumerVersionSelectors.released`: if the key is specified, can only be set to `true`. Returns the pacts for all versions of the consumer that are released and currently supported in any environment. Use of this selector requires that the deployment of the consumer application is recorded in the Pact Broker using the `pact-broker record-release` CLI.
 
-`consumerVersionSelectors.fallbackTag`: the name of the tag to fallback to if the specified `tag` does not exist. This is useful when the consumer and provider use matching branch names to coordinate the development of new features.
+`consumerVersionSelectors.environment`: the name of the environment containing the consumer versions for which to return the pacts. Used to further qualify `{ "deployed": true }` or `{ "released": true }`. Normally, this would not be needed, as it is recommended to verify the pacts for all currently deployed/currently supported released versions.
 
-`consumerVersionSelectors.latest`: true. If the latest flag is omitted, *all* the pacts with the specified tag will be returned. (This might seem a bit weird, but it's done this way to match the syntax used for the matrix query params. See https://docs.pact.io/selectors)
+`consumerVersionSelectors.latest`: true. Used in conjuction with the `tag` and `branch` properties. When used with a `branch`, it may be `true` or the key ommitted (in which case it will be inferred to be `true`). This is because it only makes sense to verify the latest pact for a branch. If a `tag` is specified, and `latest` is `true`, then the latest pact for each of the consumers with that tag will be returned. If a `tag` is specified and the latest flag is *not* set to `true`, *all* the pacts with the specified tag will be returned. (This might seem a bit weird, but it's done this way to match the syntax used for the matrix query params. See https://docs.pact.io/selectors). 
 
-`consumerVersionSelectors.consumer`: allows a selector to only be applied to a certain consumer. This is used when there is an API that has multiple consumers, one of which is a deployed service, and one of which is a mobile consumer. The deployed service only needs the latest production pact verified, where as the mobile consumer may want all the production pacts verified.
+`consumerVersionSelectors.consumer`: allows a selector to only be applied to a certain consumer.
 
-`providerVersionTags`: the tag name(s) for the provider application version that will be published with the verification results. This is used by the Broker to determine whether or not a particular pact is in pending state or not. This parameter can be specified multiple times.
+`providerVersionBranch`: the repository branch name for the provider application version that will be published with the verification results. This is used by the Broker to determine whether or not a particular pact is in pending state or not.
 
 `includePendingStatus`: true|false (default false). When true, a pending boolean will be added to the verificationProperties in the response, and an extra message will appear in the notices array to indicate why this pact is/is not in pending state. This will allow your code to handle the response based on only what is present in the response, and not have to do ifs based on the user's options together with the response. As requested in the "pacts for verification" issue, please print out these messages in the tests if possible. If not possible, perhaps create a separate task which will list the pact URLs and messages for debugging purposes.
 
 `includeWipPactsSince`: Date string. The date from which to include the "work in progress" pacts. See https://docs.pact.io/wip for more information on work in progress pacts.
 
+`consumerVersionSelectors.tag`: the tag name(s) of the consumer versions to get the pacts for. *This field is still supported but it is recommended to use the `branch` in preference now.*
+
+`consumerVersionSelectors.fallbackTag`: the name of the tag to fallback to if the specified `tag` does not exist. This is useful when the consumer and provider use matching branch names to coordinate the development of new features. *This field is still supported but it is recommended to use the `fallbackBranch` in preference now.*
+
+`providerVersionTags`: the tag name(s) for the provider application version that will be published with the verification results. This is used by the Broker to determine whether or not a particular pact is in pending state or not. This parameter can be specified multiple times. *This field is still supported but it is recommended to use the `providerVersionBranch` in preference now.*
+
 ### Response body
 
 `pending` flag and  the "pending reason" notice will only be included if `includePendingStatus` is set to true.