From f11f29ccd08c56a4c3968731bb0d689698127d64 Mon Sep 17 00:00:00 2001
From: Matt Williams <matt@milliams.com>
Date: Mon, 20 Jan 2025 12:00:04 +0000
Subject: [PATCH] Document and implement version compatibility rules

---
 docs/api.rst                 |  4 +++-
 docs/index.rst               | 19 +++++++++++++++++++
 src/main.rs                  |  2 ++
 tests/integration/basic.hurl |  1 +
 4 files changed, 25 insertions(+), 1 deletion(-)

diff --git a/docs/api.rst b/docs/api.rst
index 7df6de9..e5a1bcc 100644
--- a/docs/api.rst
+++ b/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
 
diff --git a/docs/index.rst b/docs/index.rst
index 733f1d7..483d6da 100644
--- a/docs/index.rst
+++ b/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
diff --git a/src/main.rs b/src/main.rs
index 9c73f19..eada3ce 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -426,6 +426,7 @@ 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)]
@@ -433,6 +434,7 @@ async fn oidc(State(state): State<Arc<AppState>>) -> Result<Json<OidcResponse>,
     Ok(Json(OidcResponse {
         issuer: state.provider_metadata.issuer().clone(),
         client_id: state.config.client_id.clone(),
+        version: 1,
     }))
 }
 
diff --git a/tests/integration/basic.hurl b/tests/integration/basic.hurl
index b65b6a8..bbff161 100644
--- a/tests/integration/basic.hurl
+++ b/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