Merge pull request #218 from nspcc-dev/217-tls-ext-addr

Use `external-address` directly for Swagger docs

CHANGELOG.md

@@ -4,6 +4,13 @@ This document outlines major changes between releases.
 
 ## [Unreleased]
 
+### Updating from 0.9.0
+
+Notice that the configuration parameter `external-address` in the 
+`server.endpoints` section now also includes the scheme (http/https), not just
+the host and port. If `external-address` is not set, it will be generated from 
+`address` and `tls.enabled`.
+
 ## [0.9.0] - 2024-05-30
 
 ### Added

cmd/neofs-rest-gw/config.go

@@ -144,7 +144,7 @@ func config() *viper.Viper {
 	flagSet.Duration(cfgEndpointKeepAlive, 3*time.Minute, "sets the TCP keep-alive timeouts on accepted connections. It prunes dead TCP connections ( e.g. closing laptop mid-download)")
 	flagSet.Duration(cfgEndpointReadTimeout, 30*time.Second, "maximum duration before timing out read of the request")
 	flagSet.Duration(cfgEndpointWriteTimeout, 30*time.Second, "maximum duration before timing out write of the response")
-	flagSet.String(cfgEndpointExternalAddress, "localhost:8090", "the IP and port to be shown in the API documentation")
+	flagSet.String(cfgEndpointExternalAddress, "", "the full URL address needs to be shown in the API documentation")
 
 	// init server flags
 	BindDefaultFlags(flagSet)

cmd/neofs-rest-gw/main.go

@@ -62,32 +62,34 @@ func main() {
 	e.Group(baseURL, middleware.OapiRequestValidator(swagger))
 	apiserver.RegisterHandlersWithBaseURL(e, neofsAPI, baseURL)
 
+	var serverURL string
 	servers := make(openapi3.Servers, len(serverCfg.Endpoints))
 	for i, endpointInfo := range serverCfg.Endpoints {
 		if endpointInfo.ExternalAddress != "" {
-			var scheme string
-			// Determine the scheme based on whether TLS is enabled and set up e.TLSServer.
-			if endpointInfo.TLS.Enabled {
-				scheme = schemeHTTPS
-				e.TLSServer.ReadTimeout = endpointInfo.ReadTimeout
-				e.TLSServer.WriteTimeout = endpointInfo.WriteTimeout
-				e.TLSServer.IdleTimeout = endpointInfo.KeepAlive
-
-				if endpointInfo.TLS.CertCAFile != "" {
-					ca, err := loadCA(endpointInfo.TLS.CertCAFile)
-					if err != nil {
-						logger.Fatal("reading server certificate", zap.Error(err))
-					}
-					e.TLSServer.TLSConfig = &tls.Config{ClientCAs: ca}
+			serverURL = fmt.Sprintf("%s%s", endpointInfo.ExternalAddress, baseURL)
+		} else {
+			scheme := getScheme(endpointInfo.TLS.Enabled)
+			serverURL = fmt.Sprintf("%s://%s%s", scheme, endpointInfo.Address, baseURL)
+			logger.Info("Endpoint with missing external-address",
+				zap.String("address", endpointInfo.Address),
+				zap.String("set external-address", serverURL))
+		}
+		servers[i] = &openapi3.Server{
+			URL: serverURL,
+		}
+
+		if endpointInfo.TLS.Enabled {
+			e.TLSServer.ReadTimeout = endpointInfo.ReadTimeout
+			e.TLSServer.WriteTimeout = endpointInfo.WriteTimeout
+			e.TLSServer.IdleTimeout = endpointInfo.KeepAlive
+
+			if endpointInfo.TLS.CertCAFile != "" {
+				ca, err := loadCA(endpointInfo.TLS.CertCAFile)
+				if err != nil {
+					logger.Fatal("reading server certificate", zap.Error(err))
 				}
-			} else {
-				scheme = schemeHTTP
-			}
-			servers[i] = &openapi3.Server{
-				URL: fmt.Sprintf("%s://%s%s", scheme, endpointInfo.ExternalAddress, baseURL),
+				e.TLSServer.TLSConfig = &tls.Config{ClientCAs: ca}
 			}
-		} else {
-			logger.Info("Endpoint with missing external-address", zap.String("address", endpointInfo.Address))
 		}
 	}
 	swagger.Servers = servers
@@ -137,3 +139,10 @@ func swaggerDocHandler(c echo.Context) error {
 func redirectHandler(c echo.Context) error {
 	return c.Redirect(http.StatusTemporaryRedirect, docsURL)
 }
+
+func getScheme(tlsEnabled bool) string {
+	if tlsEnabled {
+		return schemeHTTPS
+	}
+	return schemeHTTP
+}

config/config.yaml

@@ -56,8 +56,10 @@ server:
   endpoints:
     # The IP and port to listen on.
     - address: localhost:8081
-      # The IP and port to be shown in the API documentation.
-      external-address: localhost:8091
+      # The full URL address needs to be shown in the API documentation,
+      # including the scheme (http/https), host, and port.
+      # If not set, will be generated from `address` and `tls.enabled`.
+      external-address: https://localhost:8091
       tls:
         # Use TLS for a gRPC connection (min version is TLS 1.2).
         enabled: true
@@ -76,7 +78,7 @@ server:
       write-timeout: 30s
 
     - address: localhost:8080
-      external-address: localhost:8090
+      external-address: http://localhost:8090
       tls:
         enabled: false
         certificate: /path/to/tls/cert

docs/gate-configuration.md

@@ -54,7 +54,7 @@ server:
 | `endpoint.[0].tls.certificate`  | `string`   |                  | The certificate file to use for secure connections.                                                                                                                                 |
 | `endpoint.[0].tls.key`          | `string`   |                  | The private key file to use for secure connections (without passphrase).                                                                                                            |
 | `endpoint.[0].tls.ca`           | `string`   |                  | The certificate authority certificate file to be used with mutual tls auth.                                                                                                         |
-| `endpoint.[0].external-address` | `string`   | `localhost:8090` | The IP and port to be shown in the API documentation.                                                                                                                               |
+| `endpoint.[0].external-address` | `string`   |                  | The full URL address needs to be shown in the API documentation, including the scheme (http/https), host, and port. If not set, will be generated from `address` and `tls.enabled`. |
 
 # `wallet` section