Design: New command(s) for Contract configuration management

[zionts]

Description

With the new Contracts feature, users want to be able to manage the set of contracts they have in their graph within their codebase. This fits in-line with the modern practice of managing configuration in code and using tools like Terraform. Users will be able to author (and create / update) contract configuration in the UI, but we expect the majority of users will want to keep contract configuration in a codebase and manage updates to their configuration in that codebase.

This issue is meant to outline the questions we need to answer in deciding on the scope of rover CLI changes, and is not meant to be a source of truth, but rather a home of conversation. The result of this issue should be a set of commands and a DSL that we will scope and build within rover over the next few weeks.

User stories and scale

We can expect users may have anywhere from one to dozens of contracts within their graph. The following user stories are a brief sketch of what users should be able to do using rover

• As a contract maintainer, I want to create one or more contracts in my graph via a CI process, upon merging to my main branch in order to track changes to my contract in my codebase.
• As a contract maintainer, I want to update existing contracts in my graph via a CI process, upon merging to my main branch
• As a contract maintainer, I want to create or update existing contracts in my graph manually using the CLI and have feedback before I take an action as to what it will do and confirmation that it has happened
• As a consumer, I want to be able to pull schemas for existing contracts in order to power local development workflows and other developer tools

Some ideas of management commands

We could define a contract noun. That might look something like this:

rover contract provision engine@ios --config ~/config.yaml

We could allow contract management at the graph level of the hierarchy. That might look something like this:

rover graph manage-contracts ~/contract-config-directory/

or, the single config at a time version:

rover graph manage-contract ~/contract-1.yaml

What does the DSL for Contract Configuration look like?

Currently, we are thinking this will be a YAML file for readability and better diffs in git. We expect that users will rarely author contract configurations by hand but will likely edit them by hand. We expect authorship to be an experience that is mostly UI-driven. A rough sketch of how this could look:

---
target-variant: prod-public
source-variant: production
filter:
  includes:
  - public
  excludes:
  - internal

Questions

What should the ref look like for a contract?

Because contracts will create defined variants (with some limitations), we could continue to use the @ symbol as a separator.

Should we have separate commands for creating and updating contract configurations?

Since users are using rover for automation, it would be most convenient that the command to create & update are the same. This would allow users to add one command that they do not need to change for both creating & updating the contract, much how "push" works

What should the hierarchy and the verb / noun structure look like?

If we think that we'll add much more surface area beneath contracts, then we should consider having a dedicated contract noun. If we think that the surface area will not grow much over time, it will probably be over-kill to have a dedicated noun. If we want a contract to feel like a normal variant, we should consider reusing the existing commands around variants.

Should we allow users to update multiple contracts at once?

We could go either way on this one. It would be convenient to not have to add a command but instead just add a file to a directory to create another contract. If this would be a large increase in scope, then we should start without it.

How should contract names and variants work side by side?

Contracts will be normal variants, with some exceptions.

• Users cannot publish a schema directly to a contract.
• Contract variants do not have subgraphs
• Contract variants have a "source" variant from which they are updated, upon publishing and applying filter rules

As such, you should imagine that graph fetch and graph check could continue to work for contracts, for instance.

[EverlastingBugstopper]

$ rover graph publish my-graph@contract --schema manual-schema.gql` 
error: You cannot publish a schema to my-graph@contract because contracts are derived from filters applied to a source variant.
    Try publishing a contract with `rover contract publish`

---

subgraphs:
  films:
    schema: 
      file: ./subgraphs/films.graphql
    routing_url: "https://example.com/films/graphql"
  people:
    schema: 
      file: ./subgraphs/people.graphql
    routing_url: "https://example.com/films/graphql"

contracts:
  admin:
    target-variant: prod-public
    source-variant: production
    filter:
      includes:
      - public
      - internal
  user:
    target-variant: prod-public
    source-variant: production
    filter:
      includes:
      - public
      excludes:
      - internal

$ rover contract publish my-graph@admin--config config.yml
Publishing contract my-graph@admin using credentials from the default profile.

---

$ rover graph fetch my-graph@admin` 
error: You cannot fetch my-graph@adminusing this command because it is a contract.
    Try fetching this contract with `rover contract fetch`

---

$ rover contract fetch my-graph@admin
SDL:

...

---

$ rover contract describe my-graph@admin
Getting info about contract my-graph@admin using credentials from the default profile.
YAML:

admin:
  target-variant: prod-public
  source-variant: production
  filter:
    includes:
    - public
    excludes:
    - internal

---

^ This seems pretty nice - I think we should likely add another noun here, even if it's only for fetch and publish just to avoid confusion.

[ndintenfass]

Contract "fetching" shouldn't retrieve a schema, right. That's "just" getting a variant's schema using graph fetch - if you're publishing the contract config, you might want to fetch that, but retrieving a schema shouldn't be different for a contract variant than from any variant, agreed?

[ndintenfass]

Also, strongly recommend you use graph refs in the source/target, so you don't need to make new semantics if and when this crosses graphs.

[ndintenfass]

You might consider separating the filters from the publishing targets, so you can reuse filters and combine filters. You might also make your filter semantics more specific to "tags" vs other things you'd want to include/exclude (eg: exclude certain subgraphs or exclude based on a regex on entity name).

filters:
  admin:
    include:
      tags:
        - public
        - admin

contracts:
  admin:
    filters:
      - admin
    source: mygraph@main
    target: mygraph@admin

[EverlastingBugstopper]

Closing this as a duplicate of #1421