// Proto file for Pact plugin interface V1
syntax = "proto3";
import "google/protobuf/struct.proto";
import "google/protobuf/wrappers.proto";
import "google/protobuf/empty.proto";
package io.pact.plugin;
option go_package = "io.pact.plugin";
// Request to verify the plugin has loaded OK
message InitPluginRequest {
// Implementation calling the plugin
string implementation = 1;
// Version of the implementation
string version = 2;
}
// Entry to be added to the core catalogue. Each entry describes one of the features the plugin provides.
// Entries will be stored in the catalogue under the key "plugin/$name/$type/$key".
message CatalogueEntry {
enum EntryType {
// Matcher for contents of messages, requests or response bodies
CONTENT_MATCHER = 0;
// Generator for contents of messages, requests or response bodies
CONTENT_GENERATOR = 1;
// Transport for a network protocol
TRANSPORT = 2;
// Matching rule for content field/values
MATCHER = 3;
// Type of interaction
INTERACTION = 4;
}
// Entry type
EntryType type = 1;
// Entry key
string key = 2;
// Associated data required for the entry. For CONTENT_MATCHER and CONTENT_GENERATOR types, a "content-types"
// value (separated by semi-colons) is required for all the content types the plugin supports.
map<string, string> values = 3;
}
// Response to init plugin, providing the catalogue entries the plugin provides
message InitPluginResponse {
// List of entries the plugin supports
repeated CatalogueEntry catalogue = 1;
}
// Catalogue of Core Pact + Plugin features
message Catalogue {
// List of entries from the core catalogue
repeated CatalogueEntry catalogue = 1;
}
// Message representing a request, response or message body
message Body {
// The content type of the body in MIME format (i.e. application/json)
string contentType = 1;
// Bytes of the actual content
google.protobuf.BytesValue content = 2;
// Enum of content type override. This is a hint on how the content type should be treated.
enum ContentTypeHint {
// Determine the form of the content using the default rules of the Pact implementation
DEFAULT = 0;
// Contents must always be treated as a text form
TEXT = 1;
// Contents must always be treated as a binary form
BINARY = 2;
}
// Content type override to apply (if required). If omitted, the default rules of the Pact implementation
// will be used
ContentTypeHint contentTypeHint = 3;
}
// Request to preform a comparison on an actual body given the expected one
message CompareContentsRequest {
// Expected body from the Pact interaction
Body expected = 1;
// Actual received body
Body actual = 2;
// If unexpected keys or attributes should be allowed. Setting this to false results in additional keys or fields
// will cause a mismatch
bool allow_unexpected_keys = 3;
// Map of expressions to matching rules. The expressions follow the documented Pact matching rule expressions
map<string, MatchingRules> rules = 4;
// Additional data added to the Pact/Interaction by the plugin
PluginConfiguration pluginConfiguration = 5;
}
// Indicates that there was a mismatch with the content type
message ContentTypeMismatch {
// Expected content type (MIME format)
string expected = 1;
// Actual content type received (MIME format)
string actual = 2;
}
// A mismatch for an particular item of content
message ContentMismatch {
// Expected data bytes
google.protobuf.BytesValue expected = 1;
// Actual data bytes
google.protobuf.BytesValue actual = 2;
// Description of the mismatch
string mismatch = 3;
// Path to the item that was matched. This is the value as per the documented Pact matching rule expressions.
string path = 4;
// Optional diff of the contents
string diff = 5;
// Part of the interaction that the mismatch is for: body, headers, metadata, etc.
string mismatchType = 6;
}
// List of content mismatches
message ContentMismatches {
repeated ContentMismatch mismatches = 1;
}
// Response to the CompareContentsRequest with the results of the comparison
message CompareContentsResponse {
// Error message if an error occurred. If this field is set, the remaining fields will be ignored and the
// verification marked as failed
string error = 1;
// There was a mismatch with the types of content. If this is set, the results may not be set.
ContentTypeMismatch typeMismatch = 2;
// Results of the match, keyed by matching rule expression
map<string, ContentMismatches> results = 3;
}
// Request to configure/setup an interaction so that it can be verified later
message ConfigureInteractionRequest {
// Content type of the interaction (MIME format)
string contentType = 1;
// This is data specified by the user in the consumer test
google.protobuf.Struct contentsConfig = 2;
}
// Represents a matching rule
message MatchingRule {
// Type of the matching rule
string type = 1;
// Associated data for the matching rule
google.protobuf.Struct values = 2;
}
// List of matching rules
message MatchingRules {
repeated MatchingRule rule = 1;
}
// Example generator
message Generator {
// Type of generator
string type = 1;
// Associated data for the generator
google.protobuf.Struct values = 2;
}
// Plugin configuration added to the pact file by the ConfigureInteraction step
message PluginConfiguration {
// Data to be persisted against the interaction
google.protobuf.Struct interactionConfiguration = 1;
// Data to be persisted in the Pact file metadata (Global data)
google.protobuf.Struct pactConfiguration = 2;
}
// Response to the configure/setup an interaction request
message InteractionResponse {
// Contents for the interaction
Body contents = 1;
// All matching rules to apply
map<string, MatchingRules> rules = 2;
// Generators to apply
map<string, Generator> generators = 3;
// For message interactions, any metadata to be applied
google.protobuf.Struct messageMetadata = 4;
// Plugin specific data to be persisted in the pact file
PluginConfiguration pluginConfiguration = 5;
// Markdown/HTML formatted text representation of the interaction
string interactionMarkup = 6;
// Type of markup used
enum MarkupType {
// CommonMark format
COMMON_MARK = 0;
// HTML format
HTML = 1;
}
MarkupType interactionMarkupType = 7;
// Description of what part this interaction belongs to (in the case of there being more than one, for instance,
// request/response messages)
string partName = 8;
// All matching rules to apply to any message metadata
map<string, MatchingRules> metadata_rules = 9;
// Generators to apply to any message metadata
map<string, Generator> metadata_generators = 10;
}
// Response to the configure/setup an interaction request
message ConfigureInteractionResponse {
// If an error occurred. In this case, the other fields will be ignored/not set
string error = 1;
// The actual response if no error occurred.
repeated InteractionResponse interaction = 2;
// Plugin specific data to be persisted in the pact file
PluginConfiguration pluginConfiguration = 3;
}
// Request to generate the contents using any defined generators
message GenerateContentRequest {
// Original contents
Body contents = 1;
// Generators to apply
map<string, Generator> generators = 2;
// Additional data added to the Pact/Interaction by the plugin
PluginConfiguration pluginConfiguration = 3;
// Context data provided by the test framework
google.protobuf.Struct testContext = 4;
// The mode of the generation, if running from a consumer test or during provider verification
enum TestMode {
Unknown = 0;
// Running on the consumer side
Consumer = 1;
// Running on the provider side
Provider = 2;
}
TestMode testMode = 5;
// Which part the content is for
enum ContentFor {
Request = 0;
Response = 1;
}
ContentFor contentFor = 6;
}
// Generated body/message response
message GenerateContentResponse {
Body contents = 1;
}
// Request to start a mock server
message StartMockServerRequest {
// Interface to bind to. Will default to the loopback adapter
string hostInterface = 1;
// Port to bind to. Default (or a value of 0) get the OS to open a random port
uint32 port = 2;
// If TLS should be used (if supported by the mock server)
bool tls = 3;
// Pact as JSON to use for the mock server behaviour
string pact = 4;
// Context data provided by the test framework
google.protobuf.Struct testContext = 5;
}
// Response to the start mock server request
message StartMockServerResponse {
oneof response {
// If an error occurred
string error = 1;
// Mock server details
MockServerDetails details = 2;
}
}
// Details on a running mock server
message MockServerDetails {
// Mock server unique ID
string key = 1;
// Port the mock server is running on
uint32 port = 2;
// IP address the mock server is bound to. Probably an IP6 address, but may be IP4
string address = 3;
}
// Request to shut down a running mock server
// TODO: replace this with MockServerRequest in the next major version
message ShutdownMockServerRequest {
// The server ID to shutdown
string serverKey = 1;
}
// Request for a running mock server by ID
message MockServerRequest {
// The server ID to shutdown
string serverKey = 1;
}
// Result of a request that the mock server received
message MockServerResult {
// service + method that was requested
string path = 1;
// If an error occurred trying to handle the request
string error = 2;
// Any mismatches that occurred
repeated ContentMismatch mismatches = 3;
}
// Response to the shut down mock server request
// TODO: replace this with MockServerResults in the next major version
message ShutdownMockServerResponse {
// If the mock status is all ok
bool ok = 1;
// The results of the test run, will contain an entry for each request received by the mock server
repeated MockServerResult results = 2;
}
// Matching results of the mock server.
message MockServerResults {
// If the mock status is all ok
bool ok = 1;
// The results of the test run, will contain an entry for each request received by the mock server
repeated MockServerResult results = 2;
}
// Request to prepare an interaction for verification
message VerificationPreparationRequest {
// Pact as JSON to use for the verification
string pact = 1;
// Interaction key for the interaction from the Pact that is being verified
string interactionKey = 2;
// Any data supplied by the user to verify the interaction
google.protobuf.Struct config = 3;
}
// Request metadata value. Will either be a JSON-like value, or binary data
message MetadataValue {
oneof value {
google.protobuf.Value nonBinaryValue = 1;
bytes binaryValue = 2;
}
}
// Interaction request data to be sent or received for verification
message InteractionData {
// Request/Response body as bytes
Body body = 1;
// Metadata associated with the request/response
map<string, MetadataValue> metadata = 2;
}
// Response for the prepare an interaction for verification request
message VerificationPreparationResponse {
oneof response {
// If an error occurred
string error = 1;
// Interaction data required to construct any request
InteractionData interactionData = 2;
}
}
// Request data to verify an interaction
message VerifyInteractionRequest {
// Interaction data required to construct the request
InteractionData interactionData = 1;
// Any data supplied by the user to verify the interaction
google.protobuf.Struct config = 2;
// Pact as JSON to use for the verification
string pact = 3;
// Interaction key for the interaction from the Pact that is being verified
string interactionKey = 4;
}
message VerificationResultItem {
oneof result {
string error = 1;
ContentMismatch mismatch = 2;
}
}
// Result of running the verification
message VerificationResult {
// Was the verification successful?
bool success = 1;
// Interaction data retrieved from the provider (optional)
InteractionData responseData = 2;
// Any mismatches that occurred
repeated VerificationResultItem mismatches = 3;
// Output for the verification to display to the user
repeated string output = 4;
}
// Result of running the verification
message VerifyInteractionResponse {
oneof response {
// If an error occurred trying to run the verification
string error = 1;
VerificationResult result = 2;
}
}
service PactPlugin {
// Check that the plugin loaded OK. Returns the catalogue entries describing what the plugin provides
rpc InitPlugin(InitPluginRequest) returns (InitPluginResponse);
// Updated catalogue. This will be sent when the core catalogue has been updated (probably by a plugin loading).
rpc UpdateCatalogue(Catalogue) returns (google.protobuf.Empty);
// Request to perform a comparison of some contents (matching request)
rpc CompareContents(CompareContentsRequest) returns (CompareContentsResponse);
// Request to configure/setup the interaction for later verification. Data returned will be persisted in the pact file.
rpc ConfigureInteraction(ConfigureInteractionRequest) returns (ConfigureInteractionResponse);
// Request to generate the content using any defined generators
rpc GenerateContent(GenerateContentRequest) returns (GenerateContentResponse);
// Start a mock server
rpc StartMockServer(StartMockServerRequest) returns (StartMockServerResponse);
// Shutdown a running mock server
// TODO: Replace the message types with MockServerRequest and MockServerResults in the next major version
rpc ShutdownMockServer(ShutdownMockServerRequest) returns (ShutdownMockServerResponse);
// Get the matching results from a running mock server
rpc GetMockServerResults(MockServerRequest) returns (MockServerResults);
// Prepare an interaction for verification. This should return any data required to construct any request
// so that it can be amended before the verification is run
rpc PrepareInteractionForVerification(VerificationPreparationRequest) returns (VerificationPreparationResponse);
// Execute the verification for the interaction.
rpc VerifyInteraction(VerifyInteractionRequest) returns (VerifyInteractionResponse);
}