Merge pull request #7198 from TheThingsNetwork/feature/4301-gcs-refac…

…toring

Backport of GCS refactoring

CHANGELOG.md

@@ -15,8 +15,13 @@ For details about compatibility between different releases, see the **Commitment
 
 ### Deprecated
 
+- Experimental RPCs `AuthorizeGateway` and `UnauthorizeGateway` of the Gateway Claiming Server (GCLS).
+- `CUPSRedirection` field of `ClaimGatewayRequest`.
+
 ### Removed
 
+- `authorize` and `unauthorize` sub-commands of the gateway `claim` command.
+
 ### Fixed
 
 - Fix unhandled video stream in QR code scanner

api/ttn/lorawan/v3/api.md

@@ -2924,6 +2924,8 @@ in a future version of The Things Stack.
 
 ### <a name="ttn.lorawan.v3.CUPSRedirection">Message `CUPSRedirection`</a>
 
+DEPRECATED: This message is deprecated and will be removed in a future version of The Things Stack.
+
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
 | `target_cups_uri` | [`string`](#string) |  | CUPS URI for LoRa Basics Station CUPS redirection. |
@@ -2996,7 +2998,7 @@ in a future version of The Things Stack.
 | `collaborator` | [`OrganizationOrUserIdentifiers`](#ttn.lorawan.v3.OrganizationOrUserIdentifiers) |  | Collaborator to grant all rights on the target gateway. |
 | `target_gateway_id` | [`string`](#string) |  | Gateway ID for the target gateway. This must be a unique value. If this is not set, the target ID for the target gateway will be set to `<gateway-eui>`. |
 | `target_gateway_server_address` | [`string`](#string) |  | Target Gateway Server Address for the target gateway. |
-| `cups_redirection` | [`CUPSRedirection`](#ttn.lorawan.v3.CUPSRedirection) |  | Parameters to set CUPS redirection for the gateway. |
+| `cups_redirection` | [`CUPSRedirection`](#ttn.lorawan.v3.CUPSRedirection) |  | Parameters to set CUPS redirection for the gateway. DEPRECATED: This field is deprecated and will be removed in a future version of The Things Stack. |
 | `target_frequency_plan_id` | [`string`](#string) |  | Frequency plan ID of the target gateway. TODO: Remove this field (https://github.com/TheThingsIndustries/lorawan-stack/issues/4024) DEPRECATED: Use target_frequency_plan_ids instead. |
 | `target_frequency_plan_ids` | [`string`](#string) | repeated | Frequency plan IDs of the target gateway. |
 
@@ -3164,18 +3166,20 @@ The GatewayClaimingServer service support claiming and managing gateway claims.
 | Method Name | Request Type | Response Type | Description |
 | ----------- | ------------ | ------------- | ------------|
 | `Claim` | [`ClaimGatewayRequest`](#ttn.lorawan.v3.ClaimGatewayRequest) | [`GatewayIdentifiers`](#ttn.lorawan.v3.GatewayIdentifiers) | Claims a gateway by claim authentication code or QR code and transfers the gateway to the target user. |
-| `AuthorizeGateway` | [`AuthorizeGatewayRequest`](#ttn.lorawan.v3.AuthorizeGatewayRequest) | [`.google.protobuf.Empty`](#google.protobuf.Empty) | AuthorizeGateway allows a gateway to be claimed. |
-| `UnauthorizeGateway` | [`GatewayIdentifiers`](#ttn.lorawan.v3.GatewayIdentifiers) | [`.google.protobuf.Empty`](#google.protobuf.Empty) | UnauthorizeGateway prevents a gateway from being claimed. |
+| `Unclaim` | [`GatewayIdentifiers`](#ttn.lorawan.v3.GatewayIdentifiers) | [`.google.protobuf.Empty`](#google.protobuf.Empty) | Unclaims the gateway. EUI provided in the request are ignored and the end device is looked up by the gateway ID. |
 | `GetInfoByGatewayEUI` | [`GetInfoByGatewayEUIRequest`](#ttn.lorawan.v3.GetInfoByGatewayEUIRequest) | [`GetInfoByGatewayEUIResponse`](#ttn.lorawan.v3.GetInfoByGatewayEUIResponse) | Return whether claiming is available for a given gateway EUI. |
+| `AuthorizeGateway` | [`AuthorizeGatewayRequest`](#ttn.lorawan.v3.AuthorizeGatewayRequest) | [`.google.protobuf.Empty`](#google.protobuf.Empty) | AuthorizeGateway allows a gateway to be claimed. DEPRECATED: Authorizing gateways for claiming is no longer supported and will be removed in a future version of The Things Stack. |
+| `UnauthorizeGateway` | [`GatewayIdentifiers`](#ttn.lorawan.v3.GatewayIdentifiers) | [`.google.protobuf.Empty`](#google.protobuf.Empty) | UnauthorizeGateway prevents a gateway from being claimed. DEPRECATED: Unauthorizing (locking) gateways for claiming is no longer supported and will be removed in a future version of The Things Stack. |
 
 #### HTTP bindings
 
 | Method Name | Method | Pattern | Body |
 | ----------- | ------ | ------- | ---- |
 | `Claim` | `POST` | `/api/v3/gcls/claim` | `*` |
+| `Unclaim` | `DELETE` | `/api/v3/gcls/claim/{gateway_id}` |  |
+| `GetInfoByGatewayEUI` | `POST` | `/api/v3/gcls/claim/info` | `*` |
 | `AuthorizeGateway` | `POST` | `/api/v3/gcls/gateways/{gateway_ids.gateway_id}/authorize` | `*` |
 | `UnauthorizeGateway` | `DELETE` | `/api/v3/gcls/gateways/{gateway_id}/authorize` |  |
-| `GetInfoByGatewayEUI` | `POST` | `/api/v3/gcls/claim/info` | `*` |
 
 ## <a name="ttn/lorawan/v3/devicerepository.proto">File `ttn/lorawan/v3/devicerepository.proto`</a>
 

api/ttn/lorawan/v3/api.swagger.json

@@ -7862,9 +7862,49 @@
         ]
       }
     },
+    "/gcls/claim/{gateway_id}": {
+      "delete": {
+        "summary": "Unclaims the gateway.\nEUI provided in the request are ignored and the end device is looked up by the gateway ID.",
+        "operationId": "GatewayClaimingServer_Unclaim",
+        "responses": {
+          "200": {
+            "description": "A successful response.",
+            "schema": {
+              "type": "object",
+              "properties": {}
+            }
+          },
+          "default": {
+            "description": "An unexpected error response.",
+            "schema": {
+              "$ref": "#/definitions/googlerpcStatus"
+            }
+          }
+        },
+        "parameters": [
+          {
+            "name": "gateway_id",
+            "in": "path",
+            "required": true,
+            "type": "string"
+          },
+          {
+            "name": "eui",
+            "description": "Secondary identifier, which can only be used in specific requests.",
+            "in": "query",
+            "required": false,
+            "type": "string",
+            "format": "string"
+          }
+        ],
+        "tags": [
+          "GatewayClaimingServer"
+        ]
+      }
+    },
     "/gcls/gateways/{gateway_ids.gateway_id}/authorize": {
       "post": {
-        "summary": "AuthorizeGateway allows a gateway to be claimed.",
+        "summary": "AuthorizeGateway allows a gateway to be claimed.\nDEPRECATED: Authorizing gateways for claiming is no longer supported and will be removed in a future version of The\nThings Stack.",
         "operationId": "GatewayClaimingServer_AuthorizeGateway",
         "responses": {
           "200": {
@@ -7904,7 +7944,7 @@
     },
     "/gcls/gateways/{gateway_id}/authorize": {
       "delete": {
-        "summary": "UnauthorizeGateway prevents a gateway from being claimed.",
+        "summary": "UnauthorizeGateway prevents a gateway from being claimed.\nDEPRECATED: Unauthorizing (locking) gateways for claiming is no longer supported and will be removed in a future\nversion of The Things Stack.",
         "operationId": "GatewayClaimingServer_UnauthorizeGateway",
         "responses": {
           "200": {
@@ -20451,7 +20491,8 @@
           "type": "string",
           "description": "The Device Claiming Server will fill this field with a The Things Stack API Key."
         }
-      }
+      },
+      "description": "DEPRECATED: This message is deprecated and will be removed in a future version of The Things Stack."
     },
     "v3ClaimEndDeviceRequest": {
       "type": "object",
@@ -20520,7 +20561,7 @@
         },
         "cups_redirection": {
           "$ref": "#/definitions/v3CUPSRedirection",
-          "description": "Parameters to set CUPS redirection for the gateway."
+          "description": "Parameters to set CUPS redirection for the gateway.\nDEPRECATED: This field is deprecated and will be removed in a future version of The Things Stack."
         },
         "target_frequency_plan_id": {
           "type": "string",

api/ttn/lorawan/v3/deviceclaimingserver.proto

@@ -286,7 +286,9 @@ service EndDeviceBatchClaimingServer {
   }
 }
 
+// DEPRECATED: This message is deprecated and will be removed in a future version of The Things Stack.
 message CUPSRedirection {
+  option deprecated = true;
   // CUPS URI for LoRa Basics Station CUPS redirection.
   string target_cups_uri = 1 [(validate.rules).string = {
     uri: true,
@@ -356,7 +358,8 @@ message ClaimGatewayRequest {
   string target_gateway_server_address = 5 [(validate.rules).string.pattern = "^(?:(?:[a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\\-]*[a-zA-Z0-9])\\.)*(?:[A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9\\-]*[A-Za-z0-9])(?::[0-9]{1,5})?$|^$"];
 
   // Parameters to set CUPS redirection for the gateway.
-  CUPSRedirection cups_redirection = 6;
+  // DEPRECATED: This field is deprecated and will be removed in a future version of The Things Stack.
+  CUPSRedirection cups_redirection = 6 [deprecated = true];
 
   // Frequency plan ID of the target gateway.
   // TODO: Remove this field (https://github.com/TheThingsIndustries/lorawan-stack/issues/4024)
@@ -429,24 +432,36 @@ service GatewayClaimingServer {
     };
   }
 
+  // Unclaims the gateway.
+  // EUI provided in the request are ignored and the end device is looked up by the gateway ID.
+  rpc Unclaim(GatewayIdentifiers) returns (google.protobuf.Empty) {
+    option (google.api.http) = {delete: "/gcls/claim/{gateway_id}"};
+  }
+
+  // Return whether claiming is available for a given gateway EUI.
+  rpc GetInfoByGatewayEUI(GetInfoByGatewayEUIRequest) returns (GetInfoByGatewayEUIResponse) {
+    option (google.api.http) = {
+      post: "/gcls/claim/info",
+      body: "*"
+    };
+  }
+
   // AuthorizeGateway allows a gateway to be claimed.
+  // DEPRECATED: Authorizing gateways for claiming is no longer supported and will be removed in a future version of The
+  // Things Stack.
   rpc AuthorizeGateway(AuthorizeGatewayRequest) returns (google.protobuf.Empty) {
+    option deprecated = true;
     option (google.api.http) = {
       post: "/gcls/gateways/{gateway_ids.gateway_id}/authorize",
       body: "*"
     };
   }
 
   // UnauthorizeGateway prevents a gateway from being claimed.
+  // DEPRECATED: Unauthorizing (locking) gateways for claiming is no longer supported and will be removed in a future
+  // version of The Things Stack.
   rpc UnauthorizeGateway(GatewayIdentifiers) returns (google.protobuf.Empty) {
+    option deprecated = true;
     option (google.api.http) = {delete: "/gcls/gateways/{gateway_id}/authorize"};
   }
-
-  // Return whether claiming is available for a given gateway EUI.
-  rpc GetInfoByGatewayEUI(GetInfoByGatewayEUIRequest) returns (GetInfoByGatewayEUIResponse) {
-    option (google.api.http) = {
-      post: "/gcls/claim/info",
-      body: "*"
-    };
-  }
 }