[management] add openapi specs and generate types for port forwarding proxy (#3236)

management/server/http/api/openapi.yml

@@ -29,6 +29,9 @@ tags:
     description: View information about the account and network events.
   - name: Accounts
     description: View information about the accounts.
+  - name: Proxies
+    description: Interact with and view information about the proxy.
+    x-cloud-only: true
 components:
   schemas:
     Account:
@@ -1581,6 +1584,193 @@ components:
         - initiator_email
         - target_id
         - meta
+    ProxyCreateRequest:
+      type: object
+      properties:
+        peer_id:
+          description: ID of the peer that is used as a proxy
+          type: string
+          example: ch8i4ug6lnn4g9hqv7m0
+        enabled:
+          description: Defines if a proxy is enabled
+          type: boolean
+          example: true
+        fallback:
+          description: Defines if a proxy can be used as a fallback if no proxy can be found in the region of the forwarded peer
+          type: boolean
+          example: true
+      required:
+        - peer_id
+        - enabled
+        - fallback
+    ProxyUpdateRequest:
+      type: object
+      properties:
+        enabled:
+          description: Defines if a proxy is enabled
+          type: boolean
+          example: true
+        fallback:
+          description: Defines if a proxy can be used as a fallback if no proxy can be found in the region of the forwarded peer
+          type: boolean
+          example: true
+      required:
+        - enabled
+        - fallback
+    Proxy:
+      type: object
+      properties:
+        id:
+          description: ID of the proxy
+          type: string
+          example: ch8i4ug6lnn4g9hqv7m0
+        peer_id:
+          description: ID of the peer that is used as a proxy
+          type: string
+          example: x7p3kqf2rdd8j5zxw4n9
+        ingress_ip:
+          description: Ingress IP address of the proxy where the traffic arrives
+          type: string
+          example: 192.34.0.123
+        available_ports:
+          description: Number of available ports left on the proxy
+          type: integer
+          example: 45765
+        enabled:
+          description: Indicates if a proxy is enabled
+          type: boolean
+          example: true
+        connected:
+          description: Indicates if a proxy is connected to the management server
+          type: boolean
+          example: true
+        fallback:
+          description: Indicates if a proxy can be used as a fallback if no proxy can be found in the region of the forwarded peer
+          type: boolean
+          example: true
+        region:
+          description: Region of the proxy
+          type: string
+          example: germany
+      required:
+        - id
+        - peer_id
+        - ingress_ip
+        - available_ports
+        - enabled
+        - connected
+        - fallback
+        - region
+    ProxyConfigurationRequest:
+      type: object
+      properties:
+        name:
+          description: Name of the proxy configuration
+          type: string
+          example: Proxy Configuration 1
+        enabled:
+          description: Indicates if a proxy configuration is enabled
+          type: boolean
+          example: true
+        port_ranges:
+          description: List of port ranges that are forwarded by the proxy
+          type: array
+          items:
+            $ref: '#/components/schemas/ProxyConfigurationRequestPortRange'
+      required:
+        - name
+        - enabled
+        - port_ranges
+    ProxyConfigurationRequestPortRange:
+      type: object
+      properties:
+        start:
+          description: The starting port of the range of forwarded ports
+          type: integer
+          example: 80
+        end:
+          description: The ending port of the range of forwarded ports
+          type: integer
+          example: 320
+        protocol:
+          description: The protocol accepted by the port range
+          type: string
+          enum: [ "tcp", "udp" ]
+          example: tcp
+      required:
+        - start
+        - end
+        - protocol
+    ProxyConfiguration:
+      type: object
+      properties:
+        id:
+          description: ID of the proxy configuration
+          type: string
+          example: ch8i4ug6lnn4g9hqv7m0
+        name:
+          description: Name of the proxy configuration
+          type: string
+          example: Proxy Configuration 1
+        proxy_id:
+          description: ID of the proxy that forwards the ports
+          type: string
+          example: x7p3kqf2rdd8j5zxw4n9
+        region:
+          description: Region of the proxy
+          type: string
+          example: germany
+        enabled:
+          description: Indicates if a proxy configuration is enabled
+          type: boolean
+          example: true
+        ingress_ip:
+          description: Ingress IP address of the proxy where the traffic arrives
+          type: string
+          example:
+        port_range_mappings:
+          description: List of port ranges that are allowed to be used by the proxy
+          type: array
+          items:
+            $ref: '#/components/schemas/ProxyConfigurationPortMapping'
+      required:
+        - id
+        - name
+        - proxy_id
+        - region
+        - enabled
+        - ingress_ip
+        - port_range_mappings
+    ProxyConfigurationPortMapping:
+      type: object
+      properties:
+        translated_start:
+          description: The starting port of the translated range of forwarded ports
+          type: integer
+          example: 80
+        translated_end:
+          description: The ending port of the translated range of forwarded ports
+          type: integer
+          example: 320
+        ingress_start:
+          description: The starting port of the range of ingress ports mapped to the forwarded ports
+          type: integer
+          example: 1080
+        ingress_end:
+          description: The ending port of the range of ingress ports mapped to the forwarded ports
+          type: integer
+          example: 1320
+        protocol:
+          description: Protocol accepted by the ports
+          type: string
+          enum: [ "tcp", "udp" ]
+          example: tcp
+      required:
+        - translated_start
+        - translated_end
+        - ingress_start
+        - ingress_end
+        - protocol
   responses:
     not_found:
       description: Resource not found
@@ -2136,6 +2326,334 @@ paths:
           "$ref": "#/components/responses/forbidden"
         '500':
           "$ref": "#/components/responses/internal_error"
+  /api/peers/{peerId}/proxy_configurations:
+    get:
+      summary: List all Proxy Configurations
+      description: Returns a list of all proxy configurations for a peer
+      tags: [ Peers ]
+      security:
+        - BearerAuth: [ ]
+        - TokenAuth: [ ]
+      parameters:
+        - in: path
+          name: peerId
+          required: true
+          schema:
+            type: string
+          description: The unique identifier of a peer
+        - in: query
+          name: name
+          schema:
+            type: string
+          description: Filters proxy configurations by name
+      responses:
+        '200':
+          description: A JSON Array of Proxy Configurations
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/ProxyConfiguration'
+        '400':
+          "$ref": "#/components/responses/bad_request"
+        '401':
+          "$ref": "#/components/responses/requires_authentication"
+        '403':
+          "$ref": "#/components/responses/forbidden"
+        '500':
+          "$ref": "#/components/responses/internal_error"
+    post:
+      x-cloud-only: true
+      summary: Create a Proxy Configuration
+      description: Creates a new proxy configuration for a peer
+      tags: [ Peers ]
+      security:
+        - BearerAuth: [ ]
+        - TokenAuth: [ ]
+      parameters:
+        - in: path
+          name: peerId
+          required: true
+          schema:
+            type: string
+          description: The unique identifier of a peer
+      requestBody:
+        description: New Proxy Configuration request
+        content:
+          'application/json':
+            schema:
+              $ref: '#/components/schemas/ProxyConfigurationRequest'
+      responses:
+        '200':
+          description: A Proxy Configuration object
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ProxyConfiguration'
+        '400':
+          "$ref": "#/components/responses/bad_request"
+        '401':
+          "$ref": "#/components/responses/requires_authentication"
+        '403':
+          "$ref": "#/components/responses/forbidden"
+        '500':
+          "$ref": "#/components/responses/internal_error"
+  /api/peers/{peerId}/proxy_configurations/{configurationId}:
+    get:
+      x-cloud-only: true
+      summary: Retrieve a Proxy Configuration
+      description: Get information about a proxy configuration
+      tags: [ Peers ]
+      security:
+        - BearerAuth: [ ]
+        - TokenAuth: [ ]
+      parameters:
+        - in: path
+          name: peerId
+          required: true
+          schema:
+            type: string
+          description: The unique identifier of a peer
+        - in: path
+          name: configurationId
+          required: true
+          schema:
+            type: string
+          description: The unique identifier of a proxy configuration
+      responses:
+        '200':
+          description: A Proxy Configuration object
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ProxyConfiguration'
+        '400':
+          "$ref": "#/components/responses/bad_request"
+        '401':
+          "$ref": "#/components/responses/requires_authentication"
+        '403':
+          "$ref": "#/components/responses/forbidden"
+        '500':
+          "$ref": "#/components/responses/internal_error"
+    put:
+      x-cloud-only: true
+      parameters:
+        - in: path
+          name: peerId
+          required: true
+          schema:
+              type: string
+          description: The unique identifier of a peer
+        - in: path
+          name: configurationId
+          required: true
+          schema:
+              type: string
+          description: The unique identifier of a proxy configuration
+      requestBody:
+        description: update a proxy configuration
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ProxyConfigurationRequest'
+      responses:
+        '200':
+          description: A Proxy Configuration object
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ProxyConfiguration'
+        '400':
+          "$ref": "#/components/responses/bad_request"
+        '401':
+          "$ref": "#/components/responses/requires_authentication"
+        '403':
+          "$ref": "#/components/responses/forbidden"
+        '500':
+          "$ref": "#/components/responses/internal_error"
+    delete:
+      x-cloud-only: true
+      summary: Delete a Proxy Configuration
+      description: Delete a proxy configuration
+      tags: [ Peers ]
+      security:
+        - BearerAuth: [ ]
+        - TokenAuth: [ ]
+      parameters:
+        - in: path
+          name: peerId
+          required: true
+          schema:
+            type: string
+          description: The unique identifier of a peer
+        - in: path
+          name: configurationId
+          required: true
+          schema:
+            type: string
+          description: The unique identifier of a proxy configuration
+      responses:
+        '200':
+          description: Delete status code
+          content: { }
+        '400':
+          "$ref": "#/components/responses/bad_request"
+        '401':
+          "$ref": "#/components/responses/requires_authentication"
+        '403':
+          "$ref": "#/components/responses/forbidden"
+        '500':
+          "$ref": "#/components/responses/internal_error"
+  /api/proxies:
+    get:
+      x-cloud-only: true
+      summary: List all Proxies
+      description: Returns a list of all proxies
+      tags: [ Proxies ]
+      security:
+        - BearerAuth: [ ]
+        - TokenAuth: [ ]
+      responses:
+        '200':
+          description: A JSON Array of Proxies
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Proxy'
+        '400':
+          "$ref": "#/components/responses/bad_request"
+        '401':
+          "$ref": "#/components/responses/requires_authentication"
+        '403':
+          "$ref": "#/components/responses/forbidden"
+        '500':
+          "$ref": "#/components/responses/internal_error"
+    post:
+      x-cloud-only: true
+      summary: Create a Proxy
+      description: Creates a new proxy
+      tags: [ Proxies ]
+      security:
+        - BearerAuth: [ ]
+        - TokenAuth: [ ]
+      requestBody:
+        description: New Proxy request
+        content:
+          'application/json':
+            schema:
+              $ref: '#/components/schemas/ProxyCreateRequest'
+      responses:
+        '200':
+          description: A Proxy object
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Proxy'
+        '400':
+          "$ref": "#/components/responses/bad_request"
+        '401':
+          "$ref": "#/components/responses/requires_authentication"
+        '403':
+          "$ref": "#/components/responses/forbidden"
+        '500':
+          "$ref": "#/components/responses/internal_error"
+  /api/proxies/{proxyId}:
+    get:
+      x-cloud-only: true
+      summary: Retrieve a Proxy
+      description: Get information about a proxy
+      tags: [ Proxies ]
+      security:
+        - BearerAuth: [ ]
+        - TokenAuth: [ ]
+      parameters:
+        - in: path
+          name: proxyId
+          required: true
+          schema:
+            type: string
+          description: The unique identifier of a proxy
+      responses:
+        '200':
+          description: A Proxy object
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Proxy'
+        '400':
+          "$ref": "#/components/responses/bad_request"
+        '401':
+          "$ref": "#/components/responses/requires_authentication"
+        '403':
+          "$ref": "#/components/responses/forbidden"
+        '500':
+          "$ref": "#/components/responses/internal_error"
+    put:
+      x-cloud-only: true
+      summary: Update a Proxy
+      description: Update information about a proxy
+      tags: [ Proxies ]
+      security:
+        - BearerAuth: [ ]
+        - TokenAuth: [ ]
+      parameters:
+        - in: path
+          name: proxyId
+          required: true
+          schema:
+              type: string
+          description: The unique identifier of a proxy
+      requestBody:
+        description: update a proxy
+        content:
+          'application/json':
+            schema:
+              $ref: '#/components/schemas/ProxyUpdateRequest'
+      responses:
+        '200':
+          description: A Proxy object
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Proxy'
+        '400':
+          "$ref": "#/components/responses/bad_request"
+        '401':
+          "$ref": "#/components/responses/requires_authentication"
+        '403':
+          "$ref": "#/components/responses/forbidden"
+        '500':
+          "$ref": "#/components/responses/internal_error"
+    delete:
+      x-cloud-only: true
+      summary: Delete a Proxy
+      description: Delete a proxy
+      tags: [ Proxies ]
+      security:
+        - BearerAuth: [ ]
+        - TokenAuth: [ ]
+      parameters:
+        - in: path
+          name: proxyId
+          required: true
+          schema:
+            type: string
+          description: The unique identifier of a proxy
+      responses:
+        '200':
+          description: Delete status code
+          content: { }
+        '400':
+          "$ref": "#/components/responses/bad_request"
+        '401':
+          "$ref": "#/components/responses/requires_authentication"
+        '403':
+          "$ref": "#/components/responses/forbidden"
+        '500':
+          "$ref": "#/components/responses/internal_error"
   /api/setup-keys:
     get:
       summary: List all Setup Keys

management/server/http/api/types.gen.go

@@ -143,6 +143,18 @@ const (
 	PolicyRuleUpdateProtocolUdp  PolicyRuleUpdateProtocol = "udp"
 )
 
+// Defines values for ProxyConfigurationPortMappingProtocol.
+const (
+	ProxyConfigurationPortMappingProtocolTcp ProxyConfigurationPortMappingProtocol = "tcp"
+	ProxyConfigurationPortMappingProtocolUdp ProxyConfigurationPortMappingProtocol = "udp"
+)
+
+// Defines values for ProxyConfigurationRequestPortRangeProtocol.
+const (
+	ProxyConfigurationRequestPortRangeProtocolTcp ProxyConfigurationRequestPortRangeProtocol = "tcp"
+	ProxyConfigurationRequestPortRangeProtocolUdp ProxyConfigurationRequestPortRangeProtocol = "udp"
+)
+
 // Defines values for ResourceType.
 const (
 	ResourceTypeDomain ResourceType = "domain"
@@ -1125,6 +1137,126 @@ type ProcessCheck struct {
 	Processes []Process `json:"processes"`
 }
 
+// Proxy defines model for Proxy.
+type Proxy struct {
+	// AvailablePorts Number of available ports left on the proxy
+	AvailablePorts int `json:"available_ports"`
+
+	// Connected Indicates if a proxy is connected to the management server
+	Connected bool `json:"connected"`
+
+	// Enabled Indicates if a proxy is enabled
+	Enabled bool `json:"enabled"`
+
+	// Fallback Indicates if a proxy can be used as a fallback if no proxy can be found in the region of the forwarded peer
+	Fallback bool `json:"fallback"`
+
+	// Id ID of the proxy
+	Id string `json:"id"`
+
+	// IngressIp Ingress IP address of the proxy where the traffic arrives
+	IngressIp string `json:"ingress_ip"`
+
+	// PeerId ID of the peer that is used as a proxy
+	PeerId string `json:"peer_id"`
+
+	// Region Region of the proxy
+	Region string `json:"region"`
+}
+
+// ProxyConfiguration defines model for ProxyConfiguration.
+type ProxyConfiguration struct {
+	// Enabled Indicates if a proxy configuration is enabled
+	Enabled bool `json:"enabled"`
+
+	// Id ID of the proxy configuration
+	Id string `json:"id"`
+
+	// IngressIp Ingress IP address of the proxy where the traffic arrives
+	IngressIp string `json:"ingress_ip"`
+
+	// Name Name of the proxy configuration
+	Name string `json:"name"`
+
+	// PortRangeMappings List of port ranges that are allowed to be used by the proxy
+	PortRangeMappings []ProxyConfigurationPortMapping `json:"port_range_mappings"`
+
+	// ProxyId ID of the proxy that forwards the ports
+	ProxyId string `json:"proxy_id"`
+
+	// Region Region of the proxy
+	Region string `json:"region"`
+}
+
+// ProxyConfigurationPortMapping defines model for ProxyConfigurationPortMapping.
+type ProxyConfigurationPortMapping struct {
+	// IngressEnd The ending port of the range of ingress ports mapped to the forwarded ports
+	IngressEnd int `json:"ingress_end"`
+
+	// IngressStart The starting port of the range of ingress ports mapped to the forwarded ports
+	IngressStart int `json:"ingress_start"`
+
+	// Protocol Protocol accepted by the ports
+	Protocol ProxyConfigurationPortMappingProtocol `json:"protocol"`
+
+	// TranslatedEnd The ending port of the translated range of forwarded ports
+	TranslatedEnd int `json:"translated_end"`
+
+	// TranslatedStart The starting port of the translated range of forwarded ports
+	TranslatedStart int `json:"translated_start"`
+}
+
+// ProxyConfigurationPortMappingProtocol Protocol accepted by the ports
+type ProxyConfigurationPortMappingProtocol string
+
+// ProxyConfigurationRequest defines model for ProxyConfigurationRequest.
+type ProxyConfigurationRequest struct {
+	// Enabled Indicates if a proxy configuration is enabled
+	Enabled bool `json:"enabled"`
+
+	// Name Name of the proxy configuration
+	Name string `json:"name"`
+
+	// PortRanges List of port ranges that are forwarded by the proxy
+	PortRanges []ProxyConfigurationRequestPortRange `json:"port_ranges"`
+}
+
+// ProxyConfigurationRequestPortRange defines model for ProxyConfigurationRequestPortRange.
+type ProxyConfigurationRequestPortRange struct {
+	// End The ending port of the range of forwarded ports
+	End int `json:"end"`
+
+	// Protocol The protocol accepted by the port range
+	Protocol ProxyConfigurationRequestPortRangeProtocol `json:"protocol"`
+
+	// Start The starting port of the range of forwarded ports
+	Start int `json:"start"`
+}
+
+// ProxyConfigurationRequestPortRangeProtocol The protocol accepted by the port range
+type ProxyConfigurationRequestPortRangeProtocol string
+
+// ProxyCreateRequest defines model for ProxyCreateRequest.
+type ProxyCreateRequest struct {
+	// Enabled Defines if a proxy is enabled
+	Enabled bool `json:"enabled"`
+
+	// Fallback Defines if a proxy can be used as a fallback if no proxy can be found in the region of the forwarded peer
+	Fallback bool `json:"fallback"`
+
+	// PeerId ID of the peer that is used as a proxy
+	PeerId string `json:"peer_id"`
+}
+
+// ProxyUpdateRequest defines model for ProxyUpdateRequest.
+type ProxyUpdateRequest struct {
+	// Enabled Defines if a proxy is enabled
+	Enabled bool `json:"enabled"`
+
+	// Fallback Defines if a proxy can be used as a fallback if no proxy can be found in the region of the forwarded peer
+	Fallback bool `json:"fallback"`
+}
+
 // Resource defines model for Resource.
 type Resource struct {
 	// Id ID of the resource
@@ -1448,6 +1580,12 @@ type UserRequest struct {
 	Role string `json:"role"`
 }
 
+// GetApiPeersPeerIdProxyConfigurationsParams defines parameters for GetApiPeersPeerIdProxyConfigurations.
+type GetApiPeersPeerIdProxyConfigurationsParams struct {
+	// Name Filters proxy configurations by name
+	Name *string `form:"name,omitempty" json:"name,omitempty"`
+}
+
 // GetApiUsersParams defines parameters for GetApiUsers.
 type GetApiUsersParams struct {
 	// ServiceUser Filters users and returns either regular users or service users
@@ -1493,6 +1631,12 @@ type PutApiNetworksNetworkIdRoutersRouterIdJSONRequestBody = NetworkRouterReques
 // PutApiPeersPeerIdJSONRequestBody defines body for PutApiPeersPeerId for application/json ContentType.
 type PutApiPeersPeerIdJSONRequestBody = PeerRequest
 
+// PostApiPeersPeerIdProxyConfigurationsJSONRequestBody defines body for PostApiPeersPeerIdProxyConfigurations for application/json ContentType.
+type PostApiPeersPeerIdProxyConfigurationsJSONRequestBody = ProxyConfigurationRequest
+
+// PutApiPeersPeerIdProxyConfigurationsConfigurationIdJSONRequestBody defines body for PutApiPeersPeerIdProxyConfigurationsConfigurationId for application/json ContentType.
+type PutApiPeersPeerIdProxyConfigurationsConfigurationIdJSONRequestBody = ProxyConfigurationRequest
+
 // PostApiPoliciesJSONRequestBody defines body for PostApiPolicies for application/json ContentType.
 type PostApiPoliciesJSONRequestBody = PolicyUpdate
 
@@ -1505,6 +1649,12 @@ type PostApiPostureChecksJSONRequestBody = PostureCheckUpdate
 // PutApiPostureChecksPostureCheckIdJSONRequestBody defines body for PutApiPostureChecksPostureCheckId for application/json ContentType.
 type PutApiPostureChecksPostureCheckIdJSONRequestBody = PostureCheckUpdate
 
+// PostApiProxiesJSONRequestBody defines body for PostApiProxies for application/json ContentType.
+type PostApiProxiesJSONRequestBody = ProxyCreateRequest
+
+// PutApiProxiesProxyIdJSONRequestBody defines body for PutApiProxiesProxyId for application/json ContentType.
+type PutApiProxiesProxyIdJSONRequestBody = ProxyUpdateRequest
+
 // PostApiRoutesJSONRequestBody defines body for PostApiRoutes for application/json ContentType.
 type PostApiRoutesJSONRequestBody = RouteRequest