wip: stub server update docs

website/docs/docs/stubs.md

@@ -21,10 +21,8 @@ Hosted API stubs are useful for several use cases, such as:
 | 1       | ✅         |
 | 1.1     | ✅         |
 | 2       | ✅         |
-| 3       | ❌         |
-| 4+      | ❌         |
-
-_NOTE: Whilst currently only versions 1 and 2 of the [pact specification](https://github.com/pact-foundation/pact-specification/) are currently fully supported. Pacts using the v3 format or beyond may be used, however any matching rules will be ignored._
+| 3       | ✅         |
+| 4+      | ✅         |
 
 ## Basic Use
 
@@ -33,6 +31,7 @@ To use the stub:
 1. You must first publish a contract.
 1. Find the path to the pact contract you'd like to stub. (If you're not familiar with the PactFlow API, the simplest way to get this is to click "View Pact" from the dashboard and select "API Browser" at the top of the screen to see the URL).
 1. Append `/stub/` to the pact file path to get the base path of an instant stub
+1. Pass in your PactFlow Bearer token in the `Authentication` header
 
 ## Stub URL format
 
@@ -43,6 +42,8 @@ Stub URLs will have one of the following formats:
 | Description | URL |
 | ----------- | --- |
 | Latest for integration | `/pacts/provider/:provider/consumer/:consumer/latest/stub` |
+| Latest for a given environment | `/pacts/provider/:provider/consumer/:consumer/latest/environment/:environment/stub` |
+| Latest for a given branch | `/pacts/provider/:provider/consumer/:consumer/latest/branch/:branch/stub` |
 | Latest for a given tag | `/pacts/provider/:provider/consumer/:consumer/latest/:tag/stub` |
 | Latest for a consumer version | `/pacts/provider/:provider/consumer/:consumer/:version/stub` |
 
@@ -52,13 +53,32 @@ For example, assuming you wanted to use the latest version of a particular contr
 https://<yourdomain>.pactflow.io/pacts/provider/:provider/consumer/:consumer/latest/stub
 ```
 
+## Configuration
+
+You can configure the behaviour of the stub service at runtime, using HTTP headers sent with the stub requests.
+
+| Header | Type | Description | Default |
+|--------|------|-------------|---------|
+| `pactflow-stub-cors` | boolean  | Automatically respond to OPTIONS requests and return default CORS headers | `true` |
+| `pactflow-stub-cors-referer` | boolean | Set the CORS Access-Control-Allow-Origin header to the Referer | true |
+| `pactflow-stub-provider-state` | string | Provider state regular expression to filter the responses by | |
+| `pactflow-stub-provider-state-header-name` | string | Name of the header parameter containing the provider state to be used in case multiple matching interactions are found | |
+| `pactflow-stub-empty-provider-state` | boolean | Include empty provider states when filtering with pactflow-stub-provider-state | `false` |
+| `pactflow-stub-authorization` | string | Used in place of the `Authorization` header, which is consumed by the PactFlow API. If not present, Authorization headers are ignored when matching interactions. | |
+
 ## Stub behaviour
 
 Pact contracts may define multiple overlapping requests - for example when there are provider states.
 
-Where multiple matching interactions are found, the interactions will be sorted by response status, and the first one will be returned. This may lead to non-deterministic behaviour.
+If the request matches any interactions, it will return the first response based on the order in the pact file.
+
+If the request does not match, it will return the errors from the interaction with the least number of mismatches, followed by the order in the Pact file.
+
+**Example**
+
+Given a pact with two interactions with query `a=1` and `a=1&b=2&c=4`. If the stub server receives a request with query `a=1&b=2`, you get the error that query parameter b was not expected, instead of query parameter c is missing.
 
-_NOTE: Only versions 1 and 2 of the [pact specification](https://github.com/pact-foundation/pact-specification/) are currently fully supported. Pacts using the v3 format may be used, however, any matching features added in v3 will currently be ignored._
+The same principle applies with headers.
 
 ## Example
 
@@ -160,6 +180,20 @@ By default, [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) reque
 | `Access-Control-Allow-Credentials` | `true` | Credentials may be sent in CORS requests |
 
 
+## Authentication
+
+The `Authorization` header cannot be used natively in PactFlow stubs, as this header is reserved for use by PactFlow to authenticate all calls into the platform.
+
+If your interactions use this header, you can pass the value into the `pactflow-stub-authorization` header instead. When matching interactions, the stub server will treat it as if it were the `Authorization` header.
+
+Refer to the (Configuration)[#configuration] section for more.
+
+## Limitations
+
+### 1. Support for headers with underscores
+
+TBC
+
 ## Finding the URL to a pact resource
 
 ### Via the User Interface