Pacto Roadmap

Pacto Roadmap

Modules

Note: Each of the modules below should actually be a plugin API, so alternate implementations can be plugged in.

The Clerk (Format Conversion API)

Load contracts from non-native formats, and either register them or save them to Pacto format:

Pacto::Clerk.load :apiary, 'path/to/blueprint.json' # Assume Apiary json serialization, no Markdown support at this point

The Stenographer (Logging API)

Record access log in terms of services rather than typical Apache Common Log format. Easier to read/replay. Should be based on rfc #6570 variables for the service:

CreateServer :image => 1234, :flavor => '1 GB Performance'

The Actor(s) (Stubbing and Simulation API)

Simulation: Playback based on simulated consumers rerunning based on code that's similar to what the stenographer logs, just like some test services can playback based on Apache Common Log Format:

Pacto.simulate_consumer do
  CreateServer :image => 1234, :flavor => '1 GB Performance'
end

The Paralegal (Enrichment API)

The paralegal handles... Legal boilerplate: Add extra info to requests (or possibly responses) that are required for simulation to work. MVP - add authentication info (e.g. HTTP Basic Auth vs custom token-based auth).

Discovery: Modify responses in ways that will expose when services are too tightly coupled or not following the HTTP spec properly. MVP - alter the HTTP Header Field Name capitalization (e.g. Location to lOcAtIoN)

The Forensics Expert (Validation API)

Custom validations, often for organizational standards. E.g. check that all responses send a X-Transaction-ID for logging.

Prosecutor (Test Driver):

API for driving tests. Currently exists as rspec and rake tasks. Should create a common (pluggable) API so it's easier to support minitest, thor, whatever.

The Sketch Artist (Report API)

Higher-level summary reports, as opposed to the Stenographers detailed logs. MVP: Summarize which services were called and what violations were detected (as json or similar format).

Major objectives

• API Coverage reports (see polytrix)
• Full uriTemplate (rfc #6570) support - pending Addressable and WebMock releases
• Better Consumer-Driven-Contract support
  • Support value expansion on uriTemplates while simulating consumers to test providers
  • Support request middleware for handling authentication (or similar challenges)
  • Support named request/response examples for simulating or stubbing (default: use first)
• Documentation-Driven Contracts
  • Support apiblueprint (either as a format that can be loaded from directly, or at least a apiblueprint -> Pacto Contract converter)

Required contract changes

• Use uriTemplate (rfc6570)
• Name contracts (useful for API reports or filtering collections)
• Named examples for stubbing/simulating
  • TBD: embed in contract or separate file
  • TBD: templating support? (erb, mustache?)

Tackling tech debt

• Cleaner API
  • Use normal collections when possible, instead of things like Replace ContractRegistry, ValidationRegistry, ContractList
  • Make Validation a first-level citizen:
    • Contract#validate should return a Validation
    • with_pacto block (Pacto test_helper/server_helper) should return a set of Validations
    • Pacto.validations should always return a set of Validations since the last reset
• json-schema draft4 (blocked by json-generator)
• Deprecate/drop
  • json-generator (NB: note json-schema-generator)

Other crazy ideas

Pacto.configuration do |config|
  config.stub_with :pacto # or vcr, rack
                          # this may also be a good way to experiment w/ new vs old pacto stubbing
end

# Load coverage data exported from another process (even a non-Pacto one)
Pacto.build_contracts('contracts/*.json').load_coverage_data('reports/pacto*.json').write_report('reports/api_coverage.html')

# Easily stub collections?
contracts.stub_all
Pacto.middleware.register('Create Server') do |req, values|
  res = req.call
  @servers << req.body if res.successful?
end
# Assumed template used for List Servers stubbing values[:server] becomes local variable "servers"
"""
<% servers.each do |server| %>
  <% server.to_json %>
<% end %>
"""
Pacto.middleware.register('List Servers') do |req, values|
  values[:servers] ||= @servers
  req.call
end


Pacto

Major risks

• json-schema is still a draft. We might not want to 1.0.0 version until json-schema is approved.