Minimal client API versioning

changelog.d/0-release-notes/api-version-prefix

@@ -0,0 +1 @@
+For wire.com operators: to enable versioned API paths, make sure that nginz is deployed.

changelog.d/1-api-changes/api-version-endpoint

@@ -0,0 +1 @@
+Added minimal API version support: a list of supported API versions can be found at the endpoint `GET /api-version`. Versions can be selected by adding a prefix of the form `/vN` to every route, where `N` is the desired version number (so for example `/v1/conversations` to access version 1 of the `/conversations` endpoint).

charts/nginz/templates/conf/_nginx.conf.tpl

@@ -207,7 +207,7 @@ http {
     }
 
     {{ range $path := .Values.nginx_conf.disabled_paths }}
-      location {{ $path }} {
+      location ~* ^(/v[0-9]+)?{{ $path }} {
 
         return 404;
       }
@@ -227,7 +227,10 @@ http {
     rewrite ^/api-docs{{ $location.path }}  {{ $location.path }}/api-docs?base_url=https://{{ $.Values.nginx_conf.env }}-nginz-https.{{ $.Values.nginx_conf.external_env_domain }}/ break;
             {{- end }}
 
-    location {{ $location.path }} {
+    {{- $versioned := ternary $location.versioned true (hasKey $location "versioned") -}}
+    {{- $path := printf "%s%s" (ternary "(/v[0-9]+)?" "" $versioned) $location.path }}
+
+    location ~* ^{{ $path }} {
 
         # remove access_token from logs, see 'Note sanitized_request' above.
         set $sanitized_request $request;

charts/nginz/values.yaml

@@ -43,13 +43,13 @@ nginx_conf:
   #   title: "Production"
   disabled_paths:
   - /conversations/last-events
-  - ~* ^/conversations/([^/]*)/knock
-  - ~* ^/conversations/([^/]*)/hot-knock
-  - ~* ^/conversations/([^/]*)/messages
-  - ~* ^/conversations/([^/]*)/client-messages
-  - ~* ^/conversations/([^/]*)/events
-  - ~* ^/conversations/([^/]*)/call
-  - ~* ^/conversations/([^/]*)/call/state
+  - /conversations/([^/]*)/knock
+  - /conversations/([^/]*)/hot-knock
+  - /conversations/([^/]*)/messages
+  - /conversations/([^/]*)/client-messages
+  - /conversations/([^/]*)/events
+  - /conversations/([^/]*)/call
+  - /conversations/([^/]*)/call/state
   - /search/top
   - /search/common
   # -- The origins from which we allow CORS requests. These are combined with 'external_env_domain' to form a full url
@@ -59,12 +59,12 @@ nginx_conf:
     - account
   upstreams:
     cargohold:
-    - path: ~* ^/conversations/([^/]*)/assets
+    - path: /conversations/([^/]*)/assets
       envs:
       - all
       max_body_size: "0"
       disable_request_buffering: true
-    - path: ~* ^/conversations/([^/]*)/otr/assets
+    - path: /conversations/([^/]*)/otr/assets
       envs:
       - all
       max_body_size: "0"
@@ -96,7 +96,7 @@ nginx_conf:
     - path: /list-users
       envs:
       - all
-    - path: ~* ^/api/swagger.json$
+    - path: /api/swagger.json$
       disable_zauth: true
       envs:
       - all
@@ -110,7 +110,7 @@ nginx_conf:
     - path: /connections
       envs:
       - all
-    - path: ~* ^/list-connections$
+    - path: /list-connections$
       envs:
       - all
     - path: /invitations
@@ -162,7 +162,7 @@ nginx_conf:
     - path: /bot/users
       envs:
       - all
-    - path: ~* ^/conversations/([^/]*)/bots
+    - path: /conversations/([^/]*)/bots
       envs:
       - all
     - path: /invitations/info
@@ -196,41 +196,49 @@ nginx_conf:
       - staging
       disable_zauth: true
       basic_auth: true
+      versioned: false
     - path: /i/users/login-code
       envs:
       - staging
       disable_zauth: true
       basic_auth: true
+      versioned: false
     - path: /i/users/invitation-code
       envs:
       - staging
       disable_zauth: true
       basic_auth: true
-    - path: ~* ^/i/users/([^/]*)/rich-info
+      versioned: false
+    - path: /i/users/([^/]*)/rich-info
       envs:
       - staging
       disable_zauth: true
       basic_auth: true
-    - path: ~* ^/i/teams/([^/]*)/suspend
+      versioned: false
+    - path: /i/teams/([^/]*)/suspend
       envs:
       - staging
       disable_zauth: true
       basic_auth: true
-    - path: ~* ^/i/teams/([^/]*)/unsuspend
+      versioned: false
+    - path: /i/teams/([^/]*)/unsuspend
       envs:
       - staging
       disable_zauth: true
       basic_auth: true
+      versioned: false
     - path: /i/provider/activation-code
       envs:
       - staging
       disable_zauth: true
       basic_auth: true
-    - path: ~* ^/i/legalhold/whitelisted-teams(.*)
+      versioned: false
+    - path: /i/legalhold/whitelisted-teams(.*)
       envs:
         - staging
       disable_zauth: true
       basic_auth: true
+      versioned: false
     - path: /cookies
       envs:
       - all
@@ -253,17 +261,17 @@ nginx_conf:
     - path: /search
       envs:
       - all
-    - path: ~* ^/teams/([^/]*)/invitations(.*)
+    - path: /teams/([^/]*)/invitations(.*)
       envs:
       - all
-    - path: ~* ^/teams/([^/]*)/services(.*)
+    - path: /teams/([^/]*)/services(.*)
       envs:
       - all
-    - path: ~* ^/teams/invitations/info$
+    - path: /teams/invitations/info$
       envs:
       - all
       disable_zauth: true
-    - path: ~* ^/teams/invitations/by-email$
+    - path: /teams/invitations/by-email$
       envs:
       - all
       disable_zauth: true
@@ -272,13 +280,14 @@ nginx_conf:
       - staging
       disable_zauth: true
       basic_auth: true
+      versioned: false
     - path: /calls
       envs:
       - all
-    - path: ~* ^/teams/([^/]*)/size$
+    - path: /teams/([^/]*)/size$
       envs:
       - all
-    - path: ~* ^/teams/([^/]*)/search$
+    - path: /teams/([^/]*)/search$
       envs:
       - all
     - path: /verification-code/send
@@ -290,12 +299,12 @@ nginx_conf:
       disable_zauth: true
       envs:
       - all
-    - path: ~* ^/conversations/([^/]*)/otr/messages
+    - path: /conversations/([^/]*)/otr/messages
       envs:
       - all
       max_body_size: 40m
       body_buffer_size: 256k
-    - path: ~* ^/conversations/([^/]*)/([^/]*)/proteus/messages
+    - path: /conversations/([^/]*)/([^/]*)/proteus/messages
       envs:
       - all
       max_body_size: 40m
@@ -317,57 +326,60 @@ nginx_conf:
       envs:
       - all
       doc: true
-    - path: ~* ^/teams$
+    - path: /teams$
       envs:
       - all
-    - path: ~* ^/teams/([^/]*)$
+    - path: /teams/([^/]*)$
       envs:
       - all
-    - path: ~* ^/teams/([^/]*)/members(.*)
+    - path: /teams/([^/]*)/members(.*)
       envs:
       - all
-    - path: ~* ^/teams/([^/]*)/get-members-by-ids-using-post(.*)
+    - path: /teams/([^/]*)/get-members-by-ids-using-post(.*)
       envs:
       - all
-    - path: ~* ^/teams/([^/]*)/conversations(.*)
+    - path: /teams/([^/]*)/conversations(.*)
       envs:
       - all
-    - path: ~* ^/teams/([^/]*)/members/csv$
+    - path: /teams/([^/]*)/members/csv$
       envs:
       - all
-    - path: ~* ^/teams/([^/]*)/legalhold(.*)
+    - path: /teams/([^/]*)/legalhold(.*)
       envs:
       - all
-    - path: ~* ^/i/teams/([^/]*)/legalhold(.*)
+    - path: /i/teams/([^/]*)/legalhold(.*)
       envs:
       - staging
       disable_zauth: true
       basic_auth: true
-    - path: ~* ^/custom-backend/by-domain/([^/]*)$
+      versioned: false
+    - path: /custom-backend/by-domain/([^/]*)$
       disable_zauth: true
       envs:
       - all
-    - path: ~* ^/i/custom-backend/by-domain/([^/]*)$
+    - path: /i/custom-backend/by-domain/([^/]*)$
       disable_zauth: true
       basic_auth: true
       envs:
       - staging
-    - path: ~* ^/teams/api-docs
+      versioned: false
+    - path: /teams/api-docs
       envs:
       - all
       disable_zauth: true
-    - path: ~* ^/teams/([^/]*)/features
+    - path: /teams/([^/]*)/features
       envs:
       - all
-    - path: ~* ^/teams/([^/]*)/features/([^/])*
+    - path: /teams/([^/]*)/features/([^/])*
       envs:
       - all
-    - path: ~* /i/teams/([^/]*)/features/([^/]*)
+    - path: /i/teams/([^/]*)/features/([^/]*)
       envs:
       - staging
       disable_zauth: true
       basic_auth: true
-    - path: ~* ^/feature-configs(.*)
+      versioned: false
+    - path: /feature-configs(.*)
       envs:
       - all
     - path: /galley-api/swagger-ui
@@ -395,6 +407,7 @@ nginx_conf:
       basic_auth: true
       envs:
       - staging
+      versioned: false
     - path: /sso-initiate-bind
       envs:
       - all
@@ -436,7 +449,7 @@ nginx_conf:
       envs:
       - all
       disable_zauth: true
-    - path: ~* ^/teams/([^/]*)/billing(.*)
+    - path: /teams/([^/]*)/billing(.*)
       envs:
       - all
     calling-test:

libs/wire-api/package.yaml

@@ -90,6 +90,8 @@ library:
   - wire-message-proto-lens
   - x509
   - wai
+  - wai-extra
+  - wai-utilities
   - wai-websockets
   - websockets
 

libs/wire-api/src/Wire/API/Routes/Version.hs

@@ -0,0 +1,80 @@
+-- This file is part of the Wire Server implementation.
+--
+-- Copyright (C) 2022 Wire Swiss GmbH <[email protected]>
+--
+-- This program is free software: you can redistribute it and/or modify it under
+-- the terms of the GNU Affero General Public License as published by the Free
+-- Software Foundation, either version 3 of the License, or (at your option) any
+-- later version.
+--
+-- This program is distributed in the hope that it will be useful, but WITHOUT
+-- ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+-- FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
+-- details.
+--
+-- You should have received a copy of the GNU Affero General Public License along
+-- with this program. If not, see <https://www.gnu.org/licenses/>.
+
+module Wire.API.Routes.Version where
+
+import Control.Lens ((?~))
+import Data.Aeson (FromJSON, ToJSON (..))
+import qualified Data.Aeson as Aeson
+import Data.Schema
+import qualified Data.Swagger as S
+import qualified Data.Text as Text
+import qualified Data.Text.Read as Text
+import Imports
+import Servant
+import Servant.Swagger
+import Wire.API.Routes.Named
+import Wire.API.VersionInfo
+
+data Version = V0 | V1
+  deriving stock (Eq, Ord, Bounded, Enum, Show)
+  deriving (FromJSON, ToJSON) via (Schema Version)
+
+instance ToSchema Version where
+  schema =
+    enum @Integer "Version" . mconcat $
+      [ element 0 V0,
+        element 1 V1
+      ]
+
+readVersionNumber :: Text -> Maybe Integer
+readVersionNumber v = do
+  ('v', rest) <- Text.uncons v
+  case Text.decimal rest of
+    Right (n, "") -> pure n
+    _ -> Nothing
+
+mkVersion :: Integer -> Maybe Version
+mkVersion n = case Aeson.fromJSON (Aeson.Number (fromIntegral n)) of
+  Aeson.Error _ -> Nothing
+  Aeson.Success v -> pure v
+
+supportedVersions :: [Version]
+supportedVersions = [minBound .. maxBound]
+
+newtype VersionInfo = VersionInfo {vinfoSupported :: [Version]}
+  deriving (FromJSON, ToJSON, S.ToSchema) via (Schema VersionInfo)
+
+instance ToSchema VersionInfo where
+  schema =
+    (S.schema . S.example ?~ toJSON (VersionInfo supportedVersions))
+      (VersionInfo <$> vinfoSupported .= vinfoSchema schema)
+
+type VersionAPI =
+  Named
+    "get-version"
+    ( "api-version"
+        :> Get '[JSON] VersionInfo
+    )
+
+versionAPI :: Applicative m => ServerT VersionAPI m
+versionAPI =
+  Named @"get-version" $
+    pure . VersionInfo $ supportedVersions
+
+versionSwagger :: S.Swagger
+versionSwagger = toSwagger (Proxy @VersionAPI)