Openapi configuration for heartbeat (#65)

* Openapi configuration for heartbeat

* Fix path

* Fix indentation

* Add responses

* Fix path

* Remove extra slash

* Indentation

* Revert file

* Test

* indentation

* Test no public API

* test new platform endpoint

* Add cloudbuild step

* Add error response

* Typo

* Same as existing api key endpoint

* operationID

* Change schemes back

* Remove /platform

* Add openapi-platform.yaml

* Fix syntax

* Delete extra period

* Fix comment

* Fix file name

* New host for platform API

* Consolidate paths under one service

* Add operationId

* Websocket schemes

* Replace heartbeat/ with heartbeat

* Group with tags

* Fix tag descriptions

* Revert cloudbuild

Author: cristinaleonr

cloudbuild/cloudbuild.yaml

@@ -17,23 +17,7 @@ steps:
   - go test ./... -race
   - go test -v ./...
 
-# Deployment of platform specific APIs in sandbox & staging & mlab-ns.
-# NOTE: these services are not meant for the public, e.g. /v2/platform/*
-- name: gcr.io/$PROJECT_ID/gcloud-jsonnet-cbif
-  env:
-  # Use cbif condition: only run these steps in one of these projects.
-  - PROJECT_IN=mlab-sandbox,mlab-staging,mlab-ns
-  args:
-  - cp cloudbuild/app-platform.yaml.template app-platform.yaml
-  - >
-    sed -i
-    -e 's/{{PROJECT}}/$PROJECT_ID/g'
-    -e 's/{{PLATFORM_PROJECT}}/$_PLATFORM_PROJECT/'
-    app-platform.yaml
-  - gcloud config set app/cloud_build_timeout 900
-  - gcloud --project $PROJECT_ID app deploy --promote app-platform.yaml
-
-# Deployment of public APIs in sandbox & staging & mlab-ns. e.g. /v2/nearest/*
+# Deployment of APIs in sandbox & staging & mlab-ns.
 - name: gcr.io/$PROJECT_ID/gcloud-jsonnet-cbif
   env:
   # Use cbif condition: only run these steps in one of these projects.

cmd/heartbeat/README.md

@@ -15,5 +15,6 @@ in the `-heartbeat-url` flag.
 
 ```sh
 $ go build
-$ ./heartbeat -heartbeat-url=ws://locate-dot-mlab-sandbox.appspot.com/v2/platform/heartbeat/
+$ ./heartbeat \
+    -heartbeat-url=ws://locate-dot-mlab-sandbox.appspot.com/v2/platform/heartbeat?key=${API_KEY}
 ```

cmd/heartbeat/main.go

@@ -21,7 +21,7 @@ var (
 )
 
 func init() {
-	flag.StringVar(&heartbeatURL, "heartbeat-url", "ws://localhost:8080/v2/platform/heartbeat/",
+	flag.StringVar(&heartbeatURL, "heartbeat-url", "ws://localhost:8080/v2/platform/heartbeat",
 		"URL for locate service")
 }
 

connection/connection.go

@@ -232,8 +232,8 @@ func (c *Conn) connect() error {
 			if resp != nil {
 				_, retry := retryErrors[resp.StatusCode]
 				if !retry {
-					log.Printf("error trying to establish a connection with %s, err: %v",
-						c.url.String(), err)
+					log.Printf("error trying to establish a connection with %s, err: %v, status: %d",
+						c.url.String(), err, resp.StatusCode)
 					return err
 				}
 			}

connection/connection_test.go

@@ -79,7 +79,7 @@ func Test_Dial_InvalidUrl(t *testing.T) {
 		},
 		{
 			name: "https-invalid-scheme",
-			url:  "https://127.0.0.2:1234/v2/heartbeat/",
+			url:  "https://127.0.0.2:1234/v2/heartbeat",
 		},
 	}
 

connection/testdata/fakeserver.go

@@ -11,9 +11,9 @@ import (
 
 func FakeServer(handler func(http.ResponseWriter, *http.Request)) *httptest.Server {
 	mux := http.NewServeMux()
-	mux.Handle("/v2/heartbeat/", http.HandlerFunc(handler))
+	mux.Handle("/v2/heartbeat", http.HandlerFunc(handler))
 	s := httptest.NewServer(mux)
-	s.URL = strings.Replace(s.URL, "http", "ws", 1) + "/v2/heartbeat/"
+	s.URL = strings.Replace(s.URL, "http", "ws", 1) + "/v2/heartbeat"
 	return s
 }
 

handler/heartbeat_test.go

@@ -17,7 +17,7 @@ func TestClient_Heartbeat_Error(t *testing.T) {
 	rw := httptest.NewRecorder()
 	// The header from this request will not contain the
 	// necessary "upgrade" tokens.
-	req := httptest.NewRequest(http.MethodGet, "/v2/heartbeat/", nil)
+	req := httptest.NewRequest(http.MethodGet, "/v2/heartbeat", nil)
 	c := fakeClient()
 	c.Heartbeat(rw, req)
 

locate.go

@@ -138,7 +138,7 @@ func main() {
 	mux := http.NewServeMux()
 	// PLATFORM APIs
 	// Services report their health to the heartbeat service.
-	mux.HandleFunc("/v2/platform/heartbeat/", http.HandlerFunc(c.Heartbeat))
+	mux.HandleFunc("/v2/platform/heartbeat", http.HandlerFunc(c.Heartbeat))
 	// End to end monitoring requests access tokens for specific targets.
 	mux.Handle("/v2/platform/monitoring/", monitoringChain)
 

openapi.yaml

@@ -29,14 +29,15 @@ produces:
 - "application/json"
 schemes:
 - "https"
+- "wss"
 
 paths:
   # DEPRECATED: original v2beta1 query for "nearest" servers.
   # TODO: remove once clients have migrated.
   "/v2beta1/query/{name}/{type}":
     get:
       description: |-
-        DEPRECATED, use /v2/nearest/ instead.
+        Use /v2/nearest/ instead.
       operationId: "v2beta1-query"
       produces:
       - "application/json"
@@ -56,6 +57,9 @@ paths:
           description: Nearest results.
           schema:
             $ref: "#/definitions/NearestResult"
+      deprecated: true
+      tags:
+        - public
 
   # Shared "nearest" requests without an API key.
   "/v2/nearest/{name}/{type}":
@@ -101,6 +105,8 @@ paths:
             request in the event of error.
           schema:
             $ref: "#/definitions/ErrorResult"
+      tags:
+        - public
 
   # Priority "nearest" requests WITH an API key.
   "/v2/priority/nearest/{name}/{type}":
@@ -141,6 +147,43 @@ paths:
             $ref: "#/definitions/ErrorResult"
       security:
       - api_key: []
+      tags:
+        - public
+
+  "/v2/platform/heartbeat":
+    get:
+      description: |-
+        Platform-specific path.
+      operationId: "v2-platform-heartbeat"
+      responses:
+        '200':
+          description: OK.
+      security:
+      - api_key: []
+      tags:
+        - platform
+
+  "/v2/platform/monitoring/{name}/{type}":
+    get:
+      description: |-
+        Platform-specific path.
+      operationId: "v2-platform-monitoring"
+      parameters:
+        - name: name
+          in: path
+          description: service
+          type: string
+          required: true
+        - name: type
+          in: path
+          description: datatype
+          type: string
+          required: true
+      responses:
+        '200':
+          description: OK.
+      tags:
+        - platform
 
 definitions:
   # Define the query reply without being specific about the structure.
@@ -218,7 +261,13 @@ securityDefinitions:
     type: "apiKey"
     description: |-
       An API key for your client integration restricted to the Locate API and
-      allocated using a self-service signup (TODO: link) or allocated by M-Lab
-      for your client integration (TODO: link).
+      allocated using a self-service [signup](https://docs.google.com/forms/d/e/1FAIpQLSeWMiPSRWHIcg5GVRG-oc5kkefLpR4Nqk4aNYBFK6Wr8jAAdw/viewform)
+      or allocated by M-Lab for your client integration.
     name: "key"
     in: "query"
+
+tags:
+  - name: public
+    description: Public API.
+  - name: platform
+    description: Platform API.