Skip to content

Commit f2d2e6e

Browse files
stephen-solteszstephen-soltesz
authored
Add openapi.yaml spec and enable endpoints for locate API (#21)
* Add neubot and fake wehe targets * Add endpoints_api_service config for locate service * Add OpenAPI spec for M-Lab Locate API * Deploy openapi service deploy
1 parent 1e397fc commit f2d2e6e

File tree

6 files changed

+253
-3
lines changed

6 files changed

+253
-3
lines changed

‎cloudbuild/app.yaml.mlab-ns‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,11 @@ runtime: custom
22
env: flex
33
service: locate
44

5+
endpoints_api_service:
6+
# NOTE: "name" MUST match the "host" name from openapi.yaml
7+
name: locate-dot-mlab-ns.appspot.com
8+
rollout_strategy: managed
9+
510
resources:
611
cpu: 2
712
memory_gb: 8

‎cloudbuild/app.yaml.mlab-sandbox‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,11 @@ runtime: custom
22
env: flex
33
service: locate
44

5+
endpoints_api_service:
6+
# NOTE: "name" MUST match the "host" name from openapi.yaml
7+
name: locate-dot-mlab-sandbox.appspot.com
8+
rollout_strategy: managed
9+
510
resources:
611
cpu: 2
712
memory_gb: 8

‎cloudbuild/app.yaml.mlab-staging‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,11 @@ runtime: custom
22
env: flex
33
service: locate
44

5+
endpoints_api_service:
6+
# NOTE: "name" MUST match the "host" name from openapi.yaml
7+
name: locate-dot-mlab-staging.appspot.com
8+
rollout_strategy: managed
9+
510
resources:
611
cpu: 2
712
memory_gb: 8

‎cloudbuild/cloudbuild.yaml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,3 +35,6 @@ steps:
3535
args:
3636
- cp cloudbuild/app.yaml.$PROJECT_ID app.yaml
3737
- gcloud --project $PROJECT_ID app deploy --promote app.yaml
38+
# After deploying the new service, deploy the openapi spec.
39+
- sed -i -e "s/{{PROJECT}}/$PROJECT_ID/" openapi.yaml
40+
- gcloud endpoints services deploy openapi.yaml

‎openapi.yaml‎

Lines changed: 224 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,224 @@
1+
# Copyright 2020, locate Authors.
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# https://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
# [START swagger]
16+
swagger: "2.0"
17+
info:
18+
description: |-
19+
The locate API provides consistent, expected measurement quality for M-Lab
20+
clients.
21+
title: "M-Lab Locate API"
22+
version: "2.0.0"
23+
host: "locate-dot-{{PROJECT}}.appspot.com"
24+
# [END swagger]
25+
26+
consumes:
27+
- "application/json"
28+
produces:
29+
- "application/json"
30+
schemes:
31+
- "https"
32+
33+
paths:
34+
# DEPRECATED: original v2beta1 query for "nearest" servers.
35+
# TODO: remove once clients have migrated.
36+
"/v2beta1/query/{name}/{type}":
37+
get:
38+
description: |-
39+
DEPRECATED, use /v2/nearest/ instead.
40+
operationId: "v2beta1-query"
41+
produces:
42+
- "application/json"
43+
parameters:
44+
- name: name
45+
in: path
46+
type: string
47+
required: true
48+
description: name
49+
- name: type
50+
in: path
51+
type: string
52+
required: true
53+
description: type
54+
responses:
55+
'200':
56+
description: Nearest results.
57+
schema:
58+
$ref: "#/definitions/NearestResult"
59+
60+
# Shared "nearest" requests without an API key.
61+
"/v2/nearest/{name}/{type}":
62+
get:
63+
description: |-
64+
Find the nearest healthy service.
65+
66+
All requests are scheduled as part of a "shared" resource pool. This
67+
is a good choice for small client integrations. When the platform is
68+
overloaded and the locate API must choose which requests to allow and
69+
which to block, priority is given to requests using explicit API keys
70+
to the /v2/priority/* resource.
71+
72+
This resource does not require an API key. All requests to this resource
73+
are managed collectively as if they all used a single API key.
74+
75+
operationId: "v2-shared-nearest"
76+
produces:
77+
- "application/json"
78+
parameters:
79+
- name: name
80+
in: path
81+
description: The service name, e.g. "ndt", "neubot", "wehe", etc.
82+
type: string
83+
required: true
84+
- name: type
85+
in: path
86+
description: The service type, e.g. "ndt7", "dash", "replay", etc.
87+
type: string
88+
required: true
89+
responses:
90+
# NOTE: non-number values are a schema error for the config, despite
91+
# openapi documentation.
92+
'200':
93+
description: The result of the nearest request. Clients should use the
94+
next request fields to schedule the next request in the event of
95+
error or batch scheduling.
96+
schema:
97+
$ref: "#/definitions/NearestResult"
98+
'500':
99+
description: An error occurred while looking for the service.
100+
Clients should use the next request fields to schedule the next
101+
request in the event of error.
102+
schema:
103+
$ref: "#/definitions/ErrorResult"
104+
105+
# Priority "nearest" requests WITH an API key.
106+
"/v2/priority/nearest/{name}/{type}":
107+
get:
108+
description: |-
109+
Find the nearest healthy service.
110+
111+
This resource requires an API key. When the system is under sufficient
112+
load that the locate API must choose which requests to allow and which
113+
to reject, these requests are prioritized over "shared" requests.
114+
115+
operationId: "v2-priority-nearest"
116+
produces:
117+
- "application/json"
118+
parameters:
119+
- name: name
120+
in: path
121+
description: service
122+
type: string
123+
required: true
124+
- name: type
125+
in: path
126+
description: datatype
127+
type: string
128+
required: true
129+
responses:
130+
'200':
131+
description: The result of the nearest request. Clients should use the
132+
next request fields to schedule the next request for batch
133+
scheduling.
134+
schema:
135+
$ref: "#/definitions/NearestResult"
136+
'500':
137+
description: An error occurred while looking for the service.
138+
Clients should use the next request fields to schedule the next
139+
request in the event of error.
140+
schema:
141+
$ref: "#/definitions/ErrorResult"
142+
security:
143+
- api_key: []
144+
145+
definitions:
146+
# Define the query reply without being specific about the structure.
147+
ErrorResult:
148+
type: object
149+
properties:
150+
error:
151+
type: object
152+
properties:
153+
type:
154+
type: string
155+
description: The error type.
156+
title:
157+
type: string
158+
description: A descriptive title for this error.
159+
status:
160+
type: integer
161+
description: The HTTP status code of this error, e.g. 4xx or 5xx.
162+
detail:
163+
type: string
164+
instance:
165+
type: string
166+
next_request:
167+
$ref: "#/definitions/NextRequest"
168+
169+
NearestResult:
170+
type: object
171+
properties:
172+
next_request:
173+
$ref: "#/definitions/NextRequest"
174+
description: The next request defines the earliest time that a client
175+
should make a new request using the included URL.
176+
results:
177+
type: array
178+
items:
179+
type: object
180+
properties:
181+
machine:
182+
type: string
183+
description: The machine name that all URLs reference.
184+
location:
185+
type: object
186+
additionalProperties: {}
187+
description: The machine location metadata.
188+
urls:
189+
type: object
190+
additionalProperties: {}
191+
description: Specific service URLs with access tokens.
192+
193+
NextRequest:
194+
type: object
195+
properties:
196+
nbf:
197+
type: string
198+
description: |-
199+
"not before" defines the time after which the URL will
200+
become valid. This value is the same time used in "nbf" field of
201+
the underlying JSON Web Token (JWT) claim. To show this equivalence,
202+
we use the same name.
203+
exp:
204+
type: string
205+
description: |-
206+
Expires defines the time after which the URL will be invalid.
207+
Expires will always be greater than NotBefore. This value is the
208+
same time used in the "exp" field of the underlying JWT claim.
209+
url:
210+
type: string
211+
description: |-
212+
URL should be used to make the next request to the location service.
213+
214+
securityDefinitions:
215+
# This section configures basic authentication with an API key.
216+
# Paths configured with api_key security require an API key for all requests.
217+
api_key:
218+
type: "apiKey"
219+
description: |-
220+
An API key for your client integration restricted to the Locate API and
221+
allocated using a self-service signup (TODO: link) or allocated by M-Lab
222+
for your client integration (TODO: link).
223+
name: "key"
224+
in: "query"

‎static/configs.go‎

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -40,8 +40,14 @@ var Configs = map[string]Ports{
4040
URL("ws", ":3001", "/ndt_protocol"),
4141
URL("wss", ":3010", "/ndt_protocol"),
4242
},
43+
"neubot/dash": {
44+
URL("wss", "", "/v0/envelope/access"),
45+
},
4346
"wehe/replay": {
44-
URL("https", "", "/v0/allow"),
47+
URL("wss", "", "/v0/envelope/access"),
48+
},
49+
"iperf/test": {
50+
URL("wss", "", "/v0/envelope/access"),
4551
},
4652
}
4753

@@ -51,6 +57,8 @@ type Ports []url.URL
5157
// LegacyServices associates legacy mlab-ns experiment target names with their
5258
// v2 equivalent.
5359
var LegacyServices = map[string]string{
54-
"ndt/ndt5": "ndt_ssl",
55-
"ndt/ndt7": "ndt7",
60+
"neubot/dash": "neubot",
61+
"wehe/replay": "ndt_ssl", // TODO: replace with heartbeat health.
62+
"ndt/ndt5": "ndt_ssl",
63+
"ndt/ndt7": "ndt7",
5664
}

0 commit comments

Comments
 (0)