Document and implement version compatibility rules

docs/api.rst

@@ -109,11 +109,13 @@ Conch provides a HTTP API to perform signing requests.
 
       {
         "issuer": "https://keycloak.example.com/realms/example",
-        "client_id": "clifton"
+        "client_id": "clifton",
+        "version": 1
       }
 
    :>json string issuer: the URL of the OIDC issuer.
    :>json string client_id: the ID of the OIDC client to use when talking to the issuer.
+   :>json integer version: the version of the response. Currently ``1``.
 
 .. http:get:: /public_key
 

docs/index.rst

@@ -37,6 +37,24 @@ The general high-level flow for a client interating with Conch to get a signed c
 
       Conch->>-Client: Signed certificate
 
+Version compatibility
+---------------------
+
+In order to make upgrading reliable and predictable, we define version compatibility explicitly.
+Conch follows `SemVer`_ with the following clarifications:
+
+- Adding a new, required configuration variable is not backwards compatible as it will require a change by the administrator.
+- Adding a new, optional configuration variable is backwards compatible.
+- Changing the meaning of a configuration variable is not backwards compatible.
+- Removing or changing the value of a returned JSON member is not backwards compatible.
+- Adding a new member to a returned JSON object is backwards compatible.
+
+JSON responses will contain a ``version`` member which will be an integer which increments by 1 each time a backwards-incompatible change is made to it.
+
+We commit, as far as we are able, to making upgrading Conch with a ``y`` or ``z`` version number change to be safe
+
+While in pre-1.0, a ``y`` version change will denote a backwards-incompatible change and a ``z`` will denote a backwards-compatible release.
+
 Glossary
 --------
 
@@ -54,3 +72,4 @@ Glossary
       A configurable function which takes claims and creates principals in the SSH certificate.
 
 .. _SSH certificate: https://cvsweb.openbsd.org/src/usr.bin/ssh/PROTOCOL.certkeys?rev=HEAD
+.. _SemVer: https://semver.org/spec/v2.0.0.html

src/main.rs

@@ -426,13 +426,15 @@ async fn issuer(State(state): State<Arc<AppState>>) -> Result<String, AppError>
 struct OidcResponse {
     issuer: openidconnect::IssuerUrl,
     client_id: openidconnect::ClientId,
+    version: u32,
 }
 
 #[tracing::instrument(skip_all)]
 async fn oidc(State(state): State<Arc<AppState>>) -> Result<Json<OidcResponse>, AppError> {
     Ok(Json(OidcResponse {
         issuer: state.provider_metadata.issuer().clone(),
         client_id: state.config.client_id.clone(),
+        version: 1,
     }))
 }
 

tests/integration/basic.hurl

@@ -15,6 +15,7 @@ client_id: jsonpath "$.client_id"
 [Asserts]
 jsonpath "$.issuer" == "http://localhost:8080/realms/conch"
 jsonpath "$.client_id" == "conch"
+jsonpath "$.version" == 1
 
 GET {{conch}}/public_key
 HTTP 200