@serve.zone/dcrouter-apiclient 34.7.1 → 34.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist_ts_apiclient/classes.dcrouterapiclient.d.ts +16 -0
- package/dist_ts_apiclient/classes.dcrouterapiclient.js +26 -1
- package/dist_ts_interfaces/requests/gateway-adoption.d.ts +70 -0
- package/dist_ts_interfaces/requests/gateway-adoption.js +2 -0
- package/dist_ts_interfaces/requests/index.d.ts +1 -0
- package/dist_ts_interfaces/requests/index.js +2 -1
- package/package.json +1 -1
- package/readme.md +23 -0
- package/ts_apiclient/classes.dcrouterapiclient.ts +34 -0
- package/ts_apiclient/readme.md +23 -0
- package/ts_interfaces/requests/gateway-adoption.ts +80 -0
- package/ts_interfaces/requests/index.ts +1 -0
|
@@ -46,6 +46,22 @@ export declare class DcRouterApiClient {
|
|
|
46
46
|
valid: boolean;
|
|
47
47
|
identity?: interfaces.data.IIdentity;
|
|
48
48
|
}>;
|
|
49
|
+
/**
|
|
50
|
+
* Lets the running dcrouter redeem a controller's adoption code (`adoptGatewayWithCode`), for a
|
|
51
|
+
* gateway that serves its own controller's origin and so cannot be adopted with `dcrouter adopt`
|
|
52
|
+
* while it is stopped. `controllerOrigin` is the controller's https origin.
|
|
53
|
+
*
|
|
54
|
+
* dcrouter takes this call from a signed-in administrator only, so it sends the identity of
|
|
55
|
+
* `login()` and nothing else: it does not go through `buildRequestPayload()`, and a configured
|
|
56
|
+
* `apiToken` is never sent. Without a sign-in it throws before anything is sent.
|
|
57
|
+
*
|
|
58
|
+
* A refusal rejects with the `TypedResponseError` dcrouter answered; its `errorData` is
|
|
59
|
+
* `IAdoptGatewayWithCodeRefusalData` (`code`, `controllerCommitted`). The call is sent once and
|
|
60
|
+
* never retried here: on `controllerCommitted: 'unknown'` send the same code once more, and
|
|
61
|
+
* `adoption-code-used` then means the controller committed. The controller session starts at the
|
|
62
|
+
* next start of dcrouter. Traffic hooks never see the request, which carries the code.
|
|
63
|
+
*/
|
|
64
|
+
adoptGatewayWithCode(controllerOrigin: string, code: string): Promise<interfaces.requests.IReq_AdoptGatewayWithCode['response']>;
|
|
49
65
|
request<T extends plugins.typedrequestInterfaces.ITypedRequest>(method: string, requestData: T['request'], options?: IDcRouterRequestOptions): Promise<T['response']>;
|
|
50
66
|
/**
|
|
51
67
|
* Build a request payload with identity and optional API token auto-injected.
|
|
@@ -70,6 +70,31 @@ export class DcRouterApiClient {
|
|
|
70
70
|
return response;
|
|
71
71
|
}
|
|
72
72
|
// =====================
|
|
73
|
+
// Gateway adoption
|
|
74
|
+
// =====================
|
|
75
|
+
/**
|
|
76
|
+
* Lets the running dcrouter redeem a controller's adoption code (`adoptGatewayWithCode`), for a
|
|
77
|
+
* gateway that serves its own controller's origin and so cannot be adopted with `dcrouter adopt`
|
|
78
|
+
* while it is stopped. `controllerOrigin` is the controller's https origin.
|
|
79
|
+
*
|
|
80
|
+
* dcrouter takes this call from a signed-in administrator only, so it sends the identity of
|
|
81
|
+
* `login()` and nothing else: it does not go through `buildRequestPayload()`, and a configured
|
|
82
|
+
* `apiToken` is never sent. Without a sign-in it throws before anything is sent.
|
|
83
|
+
*
|
|
84
|
+
* A refusal rejects with the `TypedResponseError` dcrouter answered; its `errorData` is
|
|
85
|
+
* `IAdoptGatewayWithCodeRefusalData` (`code`, `controllerCommitted`). The call is sent once and
|
|
86
|
+
* never retried here: on `controllerCommitted: 'unknown'` send the same code once more, and
|
|
87
|
+
* `adoption-code-used` then means the controller committed. The controller session starts at the
|
|
88
|
+
* next start of dcrouter. Traffic hooks never see the request, which carries the code.
|
|
89
|
+
*/
|
|
90
|
+
async adoptGatewayWithCode(controllerOrigin, code) {
|
|
91
|
+
if (!this.identity) {
|
|
92
|
+
throw new Error('adoptGatewayWithCode needs a signed-in administrator: call login() first. An API token '
|
|
93
|
+
+ 'does not pass.');
|
|
94
|
+
}
|
|
95
|
+
return await this.request('adoptGatewayWithCode', { identity: this.identity, controllerOrigin, code }, { sensitive: true, maxRetries: 0 });
|
|
96
|
+
}
|
|
97
|
+
// =====================
|
|
73
98
|
// Internal request helper
|
|
74
99
|
// =====================
|
|
75
100
|
async request(method, requestData, options = {}) {
|
|
@@ -94,4 +119,4 @@ export class DcRouterApiClient {
|
|
|
94
119
|
return payload;
|
|
95
120
|
}
|
|
96
121
|
}
|
|
97
|
-
//# sourceMappingURL=data:application/json;base64,
|
|
122
|
+
//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhc3Nlcy5kY3JvdXRlcmFwaWNsaWVudC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzX2FwaWNsaWVudC9jbGFzc2VzLmRjcm91dGVyYXBpY2xpZW50LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBSyxPQUFPLE1BQU0sY0FBYyxDQUFDO0FBQ3hDLE9BQU8sS0FBSyxVQUFVLE1BQU0sMkJBQTJCLENBQUM7QUFFeEQsT0FBTyxFQUFFLFlBQVksRUFBRSxNQUFNLG9CQUFvQixDQUFDO0FBQ2xELE9BQU8sRUFBRSxrQkFBa0IsRUFBRSxNQUFNLDBCQUEwQixDQUFDO0FBQzlELE9BQU8sRUFBRSxlQUFlLEVBQUUsTUFBTSx1QkFBdUIsQ0FBQztBQUN4RCxPQUFPLEVBQUUsb0JBQW9CLEVBQUUsTUFBTSw0QkFBNEIsQ0FBQztBQUNsRSxPQUFPLEVBQUUsWUFBWSxFQUFFLE1BQU0sb0JBQW9CLENBQUM7QUFDbEQsT0FBTyxFQUFFLGFBQWEsRUFBRSxNQUFNLHFCQUFxQixDQUFDO0FBQ3BELE9BQU8sRUFBRSxVQUFVLEVBQUUsTUFBTSxtQkFBbUIsQ0FBQztBQUMvQyxPQUFPLEVBQUUsWUFBWSxFQUFFLE1BQU0sb0JBQW9CLENBQUM7QUFDbEQsT0FBTyxFQUFFLGFBQWEsRUFBRSxNQUFNLHFCQUFxQixDQUFDO0FBQ3BELE9BQU8sRUFBRSxnQkFBZ0IsRUFBRSxNQUFNLDRCQUE0QixDQUFDO0FBQzlELE9BQU8sRUFBRSxVQUFVLEVBQUUsTUFBTSxzQkFBc0IsQ0FBQztBQWVsRCxNQUFNLE9BQU8saUJBQWlCO0lBQ3JCLE9BQU8sQ0FBUztJQUNoQixRQUFRLENBQVU7SUFDbEIsUUFBUSxDQUE2QjtJQUU1QyxvQkFBb0I7SUFDYixNQUFNLENBQWU7SUFDckIsWUFBWSxDQUFxQjtJQUNqQyxTQUFTLENBQWtCO0lBQzNCLGFBQWEsQ0FBdUI7SUFDcEMsS0FBSyxDQUFlO0lBQ3BCLE1BQU0sQ0FBZ0I7SUFDdEIsSUFBSSxD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
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
import * as plugins from '../plugins.js';
|
|
2
|
+
import type * as authInterfaces from '../data/auth.js';
|
|
3
|
+
/**
|
|
4
|
+
* Whether the controller committed the adoption a refused `adoptGatewayWithCode` asked for:
|
|
5
|
+
*
|
|
6
|
+
* - `no`: refused before the controller was dialled, or refused by the controller by name. The
|
|
7
|
+
* adoption code is unspent.
|
|
8
|
+
* - `unknown`: no valid answer arrived. Send the same request once more: `adoption-code-used` then
|
|
9
|
+
* means the controller committed, and a new code is needed.
|
|
10
|
+
* - `yes`: the controller answered, so the code is used up. Under a named refusal nothing was stored
|
|
11
|
+
* on the gateway. Under `internal-error` the gateway's state is not known: read whether it is
|
|
12
|
+
* adopted before a new code is minted.
|
|
13
|
+
*/
|
|
14
|
+
export type TGatewayAdoptionControllerCommitted = 'no' | 'unknown' | 'yes';
|
|
15
|
+
/**
|
|
16
|
+
* The `errorData` of every refused `adoptGatewayWithCode`. `code` names the refusal:
|
|
17
|
+
*
|
|
18
|
+
* - before the dial (`controllerCommitted: 'no'`): `unauthorized`, `admin-identity-required`,
|
|
19
|
+
* `request-invalid`, `adoption-in-progress`, `gateway-session-live`, `database-unsupported`,
|
|
20
|
+
* `address-option` (with `option`), `facts-invalid`;
|
|
21
|
+
* - from the dial: the controller's own refusal by its `@serve.zone/interfaces` connector name,
|
|
22
|
+
* such as `adoption-code-unknown` or `adoption-code-used` (`'no'`), or `controller-no-answer`
|
|
23
|
+
* (`'unknown'`);
|
|
24
|
+
* - after the answer (`'yes'`): `answer-invalid`, `gateway-client-unknown` or a refusal of the
|
|
25
|
+
* connector state, such as `controller-mismatch`, `binding-changed` or `concurrent-change`;
|
|
26
|
+
* - `internal-error` for a failure dcrouter has no name for, with the `controllerCommitted` of the
|
|
27
|
+
* point it happened at.
|
|
28
|
+
*/
|
|
29
|
+
export interface IAdoptGatewayWithCodeRefusalData {
|
|
30
|
+
code: string;
|
|
31
|
+
controllerCommitted: TGatewayAdoptionControllerCommitted;
|
|
32
|
+
/** The dcrouter option an `address-option` refusal names. */
|
|
33
|
+
option?: 'publicIp' | 'proxyIps';
|
|
34
|
+
}
|
|
35
|
+
/**
|
|
36
|
+
* Lets the running dcrouter redeem a controller's adoption code (Linus rulings 88b and 88c): the
|
|
37
|
+
* adoption `dcrouter adopt` performs on a stopped dcrouter, for a gateway that serves its own
|
|
38
|
+
* controller's origin and so cannot reach it while stopped. dcrouter states its facts to
|
|
39
|
+
* `controllerOrigin` (an https origin: scheme, host and port), stores the controller and the
|
|
40
|
+
* credential it answers and revokes every API token of the gateway client the controller is bound
|
|
41
|
+
* to, in one transaction; those tokens are refused from then on. The controller session starts at
|
|
42
|
+
* the next start of dcrouter, not here.
|
|
43
|
+
*
|
|
44
|
+
* Only a signed-in administrator may call it: the request carries an identity and no API token,
|
|
45
|
+
* and a token never passes. One adoption runs at a time (`adoption-in-progress`), and only while
|
|
46
|
+
* the gateway's process runs no controller session, which is a gateway that is not adopted or
|
|
47
|
+
* whose session failed for the process (`gateway-session-live` otherwise). dcrouter never retries.
|
|
48
|
+
*
|
|
49
|
+
* A refusal is a `TypedResponseError` whose `errorData` is `IAdoptGatewayWithCodeRefusalData`. A
|
|
50
|
+
* named refusal writes no document; after `internal-error` with `controllerCommitted: 'yes'` the
|
|
51
|
+
* gateway's state is not known (see `TGatewayAdoptionControllerCommitted`). The answer never carries the credential, and dcrouter never logs the code.
|
|
52
|
+
*/
|
|
53
|
+
export interface IReq_AdoptGatewayWithCode extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_AdoptGatewayWithCode> {
|
|
54
|
+
method: 'adoptGatewayWithCode';
|
|
55
|
+
request: {
|
|
56
|
+
identity: authInterfaces.IIdentity;
|
|
57
|
+
/** The controller's https origin, such as `https://cloudly.example.com`. */
|
|
58
|
+
controllerOrigin: string;
|
|
59
|
+
/** The adoption code the controller issued for this gateway. */
|
|
60
|
+
code: string;
|
|
61
|
+
};
|
|
62
|
+
response: {
|
|
63
|
+
gatewayId: string;
|
|
64
|
+
controllerId: string;
|
|
65
|
+
epoch: number;
|
|
66
|
+
credentialGeneration: number;
|
|
67
|
+
controllerGatewayClientId: string | null;
|
|
68
|
+
revokedTokens: number;
|
|
69
|
+
};
|
|
70
|
+
}
|
|
@@ -0,0 +1,2 @@
|
|
|
1
|
+
import * as plugins from '../plugins.js';
|
|
2
|
+
//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZ2F0ZXdheS1hZG9wdGlvbi5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzX2ludGVyZmFjZXMvcmVxdWVzdHMvZ2F0ZXdheS1hZG9wdGlvbi50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLGVBQWUsQ0FBQyJ9
|
|
@@ -21,6 +21,7 @@ export * from './dns-records.js';
|
|
|
21
21
|
export * from './dns-protected-hostnames.js';
|
|
22
22
|
export * from './dns-mutation-journal.js';
|
|
23
23
|
export * from './gateway-route-dns.js';
|
|
24
|
+
export * from './gateway-adoption.js';
|
|
24
25
|
export * from './acme-config.js';
|
|
25
26
|
export * from './email-domains.js';
|
|
26
27
|
export * from './email-settings.js';
|
|
@@ -21,6 +21,7 @@ export * from './dns-records.js';
|
|
|
21
21
|
export * from './dns-protected-hostnames.js';
|
|
22
22
|
export * from './dns-mutation-journal.js';
|
|
23
23
|
export * from './gateway-route-dns.js';
|
|
24
|
+
export * from './gateway-adoption.js';
|
|
24
25
|
export * from './acme-config.js';
|
|
25
26
|
export * from './email-domains.js';
|
|
26
27
|
export * from './email-settings.js';
|
|
@@ -30,4 +31,4 @@ export * from './workhoster.js';
|
|
|
30
31
|
export * from './security-policy.js';
|
|
31
32
|
export * from './config-events.js';
|
|
32
33
|
export * from './testing.js';
|
|
33
|
-
//# sourceMappingURL=data:application/json;base64,
|
|
34
|
+
//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90c19pbnRlcmZhY2VzL3JlcXVlc3RzL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsWUFBWSxDQUFDO0FBQzNCLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsV0FBVyxDQUFDO0FBQzFCLGNBQWMsWUFBWSxDQUFDO0FBQzNCLGNBQWMscUJBQXFCLENBQUM7QUFDcEMsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxnQkFBZ0IsQ0FBQztBQUMvQixjQUFjLGtCQUFrQixDQUFDO0FBQ2pDLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyx1QkFBdUIsQ0FBQztBQUN0QyxjQUFjLGlCQUFpQixDQUFDO0FBQ2hDLGNBQWMsVUFBVSxDQUFDO0FBQ3pCLGNBQWMsc0JBQXNCLENBQUM7QUFDckMsY0FBYyxzQkFBc0IsQ0FBQztBQUNyQyxjQUFjLHNCQUFzQixDQUFDO0FBQ3JDLGNBQWMsWUFBWSxDQUFDO0FBQzNCLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxvQkFBb0IsQ0FBQztBQUNuQyxjQUFjLGtCQUFrQixDQUFDO0FBQ2pDLGNBQWMsOEJBQThCLENBQUM7QUFDN0MsY0FBYywyQkFBMkIsQ0FBQztBQUMxQyxjQUFjLHdCQUF3QixDQUFDO0FBQ3ZDLGNBQWMsdUJBQXVCLENBQUM7QUFDdEMsY0FBYyxrQkFBa0IsQ0FBQztBQUNqQyxjQUFjLG9CQUFvQixDQUFDO0FBQ25DLGNBQWMscUJBQXFCLENBQUM7QUFDcEMsY0FBYyxvQkFBb0IsQ0FBQztBQUNuQyxjQUFjLGVBQWUsQ0FBQztBQUM5QixjQUFjLGlCQUFpQixDQUFDO0FBQ2hDLGNBQWMsc0JBQXNCLENBQUM7QUFDckMsY0FBYyxvQkFBb0IsQ0FBQztBQUNuQyxjQUFjLGNBQWMsQ0FBQyJ9
|
package/package.json
CHANGED
|
@@ -28,7 +28,7 @@
|
|
|
28
28
|
"MAC authentication"
|
|
29
29
|
],
|
|
30
30
|
"name": "@serve.zone/dcrouter-apiclient",
|
|
31
|
-
"version": "34.
|
|
31
|
+
"version": "34.8.0",
|
|
32
32
|
"type": "module",
|
|
33
33
|
"description": "Object-oriented TypeScript client and shared TypedRequest contracts for the dcrouter OpsServer API.",
|
|
34
34
|
"main": "./dist_ts_apiclient/index.js",
|
package/readme.md
CHANGED
|
@@ -75,6 +75,29 @@ const tokenClient = new DcRouterApiClient({
|
|
|
75
75
|
|
|
76
76
|
`baseUrl` is normalized by removing trailing slashes. Ordinary requests are sent to `${baseUrl}/typedrequest`; log streams use a dedicated TypedSocket connection. `buildRequestPayload()` injects the current identity and optional API token for manager methods.
|
|
77
77
|
|
|
78
|
+
## Gateway Adoption
|
|
79
|
+
|
|
80
|
+
`client.adoptGatewayWithCode(controllerOrigin, code)` lets the running dcrouter redeem a controller's adoption code (dcrouter 34.8.0 and later). It is for a gateway that serves its own controller's origin, which `dcrouter adopt` cannot adopt while dcrouter is stopped.
|
|
81
|
+
|
|
82
|
+
```typescript
|
|
83
|
+
const client = new DcRouterApiClient({ baseUrl: 'https://dcrouter.example.com' });
|
|
84
|
+
await client.login('admin@example.com', 'strong-password');
|
|
85
|
+
|
|
86
|
+
try {
|
|
87
|
+
const adoption = await client.adoptGatewayWithCode('https://cloudly.example.com', adoptionCode);
|
|
88
|
+
console.log(adoption.gatewayId, adoption.controllerId, adoption.revokedTokens);
|
|
89
|
+
// Restart dcrouter now: its controller session starts at the next start.
|
|
90
|
+
} catch (error) {
|
|
91
|
+
// dcrouter's refusal: { code, controllerCommitted: 'no' | 'unknown' | 'yes' }
|
|
92
|
+
console.error((error as { errorData?: { code?: string; controllerCommitted?: string } }).errorData);
|
|
93
|
+
}
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
- dcrouter accepts the call from a signed-in administrator only. The method sends the identity of `login()` and never the client's `apiToken`, and it throws before sending anything when the client is not signed in.
|
|
97
|
+
- The answer holds `gatewayId`, `controllerId`, `epoch`, `credentialGeneration`, `controllerGatewayClientId` and `revokedTokens`, never the credential.
|
|
98
|
+
- A refusal rejects with dcrouter's error; `errorData.controllerCommitted` says what happened to the code. `no`: nothing was committed and the code is unspent, as for `gateway-session-live` or `adoption-in-progress`. `unknown` (`controller-no-answer`): send the same code once more; `adoption-code-used` then means the controller committed and a new code is needed. `yes`: the code is used up. Under a named refusal nothing was stored on the gateway; under `internal-error` its state is not known, so read whether the gateway is adopted before a new code is minted.
|
|
99
|
+
- The call is sent once. Neither the client nor dcrouter retries it, and typed-request traffic hooks do not see it.
|
|
100
|
+
|
|
78
101
|
## Manager Map
|
|
79
102
|
|
|
80
103
|
| Manager | Purpose |
|
|
@@ -102,6 +102,40 @@ export class DcRouterApiClient {
|
|
|
102
102
|
return response;
|
|
103
103
|
}
|
|
104
104
|
|
|
105
|
+
// =====================
|
|
106
|
+
// Gateway adoption
|
|
107
|
+
// =====================
|
|
108
|
+
|
|
109
|
+
/**
|
|
110
|
+
* Lets the running dcrouter redeem a controller's adoption code (`adoptGatewayWithCode`), for a
|
|
111
|
+
* gateway that serves its own controller's origin and so cannot be adopted with `dcrouter adopt`
|
|
112
|
+
* while it is stopped. `controllerOrigin` is the controller's https origin.
|
|
113
|
+
*
|
|
114
|
+
* dcrouter takes this call from a signed-in administrator only, so it sends the identity of
|
|
115
|
+
* `login()` and nothing else: it does not go through `buildRequestPayload()`, and a configured
|
|
116
|
+
* `apiToken` is never sent. Without a sign-in it throws before anything is sent.
|
|
117
|
+
*
|
|
118
|
+
* A refusal rejects with the `TypedResponseError` dcrouter answered; its `errorData` is
|
|
119
|
+
* `IAdoptGatewayWithCodeRefusalData` (`code`, `controllerCommitted`). The call is sent once and
|
|
120
|
+
* never retried here: on `controllerCommitted: 'unknown'` send the same code once more, and
|
|
121
|
+
* `adoption-code-used` then means the controller committed. The controller session starts at the
|
|
122
|
+
* next start of dcrouter. Traffic hooks never see the request, which carries the code.
|
|
123
|
+
*/
|
|
124
|
+
public async adoptGatewayWithCode(
|
|
125
|
+
controllerOrigin: string,
|
|
126
|
+
code: string,
|
|
127
|
+
): Promise<interfaces.requests.IReq_AdoptGatewayWithCode['response']> {
|
|
128
|
+
if (!this.identity) {
|
|
129
|
+
throw new Error('adoptGatewayWithCode needs a signed-in administrator: call login() first. An API token '
|
|
130
|
+
+ 'does not pass.');
|
|
131
|
+
}
|
|
132
|
+
return await this.request<interfaces.requests.IReq_AdoptGatewayWithCode>(
|
|
133
|
+
'adoptGatewayWithCode',
|
|
134
|
+
{ identity: this.identity, controllerOrigin, code },
|
|
135
|
+
{ sensitive: true, maxRetries: 0 },
|
|
136
|
+
);
|
|
137
|
+
}
|
|
138
|
+
|
|
105
139
|
// =====================
|
|
106
140
|
// Internal request helper
|
|
107
141
|
// =====================
|
package/ts_apiclient/readme.md
CHANGED
|
@@ -75,6 +75,29 @@ const tokenClient = new DcRouterApiClient({
|
|
|
75
75
|
|
|
76
76
|
`baseUrl` is normalized by removing trailing slashes. Ordinary requests are sent to `${baseUrl}/typedrequest`; log streams use a dedicated TypedSocket connection. `buildRequestPayload()` injects the current identity and optional API token for manager methods.
|
|
77
77
|
|
|
78
|
+
## Gateway Adoption
|
|
79
|
+
|
|
80
|
+
`client.adoptGatewayWithCode(controllerOrigin, code)` lets the running dcrouter redeem a controller's adoption code (dcrouter 34.8.0 and later). It is for a gateway that serves its own controller's origin, which `dcrouter adopt` cannot adopt while dcrouter is stopped.
|
|
81
|
+
|
|
82
|
+
```typescript
|
|
83
|
+
const client = new DcRouterApiClient({ baseUrl: 'https://dcrouter.example.com' });
|
|
84
|
+
await client.login('admin@example.com', 'strong-password');
|
|
85
|
+
|
|
86
|
+
try {
|
|
87
|
+
const adoption = await client.adoptGatewayWithCode('https://cloudly.example.com', adoptionCode);
|
|
88
|
+
console.log(adoption.gatewayId, adoption.controllerId, adoption.revokedTokens);
|
|
89
|
+
// Restart dcrouter now: its controller session starts at the next start.
|
|
90
|
+
} catch (error) {
|
|
91
|
+
// dcrouter's refusal: { code, controllerCommitted: 'no' | 'unknown' | 'yes' }
|
|
92
|
+
console.error((error as { errorData?: { code?: string; controllerCommitted?: string } }).errorData);
|
|
93
|
+
}
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
- dcrouter accepts the call from a signed-in administrator only. The method sends the identity of `login()` and never the client's `apiToken`, and it throws before sending anything when the client is not signed in.
|
|
97
|
+
- The answer holds `gatewayId`, `controllerId`, `epoch`, `credentialGeneration`, `controllerGatewayClientId` and `revokedTokens`, never the credential.
|
|
98
|
+
- A refusal rejects with dcrouter's error; `errorData.controllerCommitted` says what happened to the code. `no`: nothing was committed and the code is unspent, as for `gateway-session-live` or `adoption-in-progress`. `unknown` (`controller-no-answer`): send the same code once more; `adoption-code-used` then means the controller committed and a new code is needed. `yes`: the code is used up. Under a named refusal nothing was stored on the gateway; under `internal-error` its state is not known, so read whether the gateway is adopted before a new code is minted.
|
|
99
|
+
- The call is sent once. Neither the client nor dcrouter retries it, and typed-request traffic hooks do not see it.
|
|
100
|
+
|
|
78
101
|
## Manager Map
|
|
79
102
|
|
|
80
103
|
| Manager | Purpose |
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
import * as plugins from '../plugins.js';
|
|
2
|
+
import type * as authInterfaces from '../data/auth.js';
|
|
3
|
+
|
|
4
|
+
// ============================================================================
|
|
5
|
+
// Gateway adoption by the running dcrouter (operator call)
|
|
6
|
+
// ============================================================================
|
|
7
|
+
|
|
8
|
+
/**
|
|
9
|
+
* Whether the controller committed the adoption a refused `adoptGatewayWithCode` asked for:
|
|
10
|
+
*
|
|
11
|
+
* - `no`: refused before the controller was dialled, or refused by the controller by name. The
|
|
12
|
+
* adoption code is unspent.
|
|
13
|
+
* - `unknown`: no valid answer arrived. Send the same request once more: `adoption-code-used` then
|
|
14
|
+
* means the controller committed, and a new code is needed.
|
|
15
|
+
* - `yes`: the controller answered, so the code is used up. Under a named refusal nothing was stored
|
|
16
|
+
* on the gateway. Under `internal-error` the gateway's state is not known: read whether it is
|
|
17
|
+
* adopted before a new code is minted.
|
|
18
|
+
*/
|
|
19
|
+
export type TGatewayAdoptionControllerCommitted = 'no' | 'unknown' | 'yes';
|
|
20
|
+
|
|
21
|
+
/**
|
|
22
|
+
* The `errorData` of every refused `adoptGatewayWithCode`. `code` names the refusal:
|
|
23
|
+
*
|
|
24
|
+
* - before the dial (`controllerCommitted: 'no'`): `unauthorized`, `admin-identity-required`,
|
|
25
|
+
* `request-invalid`, `adoption-in-progress`, `gateway-session-live`, `database-unsupported`,
|
|
26
|
+
* `address-option` (with `option`), `facts-invalid`;
|
|
27
|
+
* - from the dial: the controller's own refusal by its `@serve.zone/interfaces` connector name,
|
|
28
|
+
* such as `adoption-code-unknown` or `adoption-code-used` (`'no'`), or `controller-no-answer`
|
|
29
|
+
* (`'unknown'`);
|
|
30
|
+
* - after the answer (`'yes'`): `answer-invalid`, `gateway-client-unknown` or a refusal of the
|
|
31
|
+
* connector state, such as `controller-mismatch`, `binding-changed` or `concurrent-change`;
|
|
32
|
+
* - `internal-error` for a failure dcrouter has no name for, with the `controllerCommitted` of the
|
|
33
|
+
* point it happened at.
|
|
34
|
+
*/
|
|
35
|
+
export interface IAdoptGatewayWithCodeRefusalData {
|
|
36
|
+
code: string;
|
|
37
|
+
controllerCommitted: TGatewayAdoptionControllerCommitted;
|
|
38
|
+
/** The dcrouter option an `address-option` refusal names. */
|
|
39
|
+
option?: 'publicIp' | 'proxyIps';
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/**
|
|
43
|
+
* Lets the running dcrouter redeem a controller's adoption code (Linus rulings 88b and 88c): the
|
|
44
|
+
* adoption `dcrouter adopt` performs on a stopped dcrouter, for a gateway that serves its own
|
|
45
|
+
* controller's origin and so cannot reach it while stopped. dcrouter states its facts to
|
|
46
|
+
* `controllerOrigin` (an https origin: scheme, host and port), stores the controller and the
|
|
47
|
+
* credential it answers and revokes every API token of the gateway client the controller is bound
|
|
48
|
+
* to, in one transaction; those tokens are refused from then on. The controller session starts at
|
|
49
|
+
* the next start of dcrouter, not here.
|
|
50
|
+
*
|
|
51
|
+
* Only a signed-in administrator may call it: the request carries an identity and no API token,
|
|
52
|
+
* and a token never passes. One adoption runs at a time (`adoption-in-progress`), and only while
|
|
53
|
+
* the gateway's process runs no controller session, which is a gateway that is not adopted or
|
|
54
|
+
* whose session failed for the process (`gateway-session-live` otherwise). dcrouter never retries.
|
|
55
|
+
*
|
|
56
|
+
* A refusal is a `TypedResponseError` whose `errorData` is `IAdoptGatewayWithCodeRefusalData`. A
|
|
57
|
+
* named refusal writes no document; after `internal-error` with `controllerCommitted: 'yes'` the
|
|
58
|
+
* gateway's state is not known (see `TGatewayAdoptionControllerCommitted`). The answer never carries the credential, and dcrouter never logs the code.
|
|
59
|
+
*/
|
|
60
|
+
export interface IReq_AdoptGatewayWithCode extends plugins.typedrequestInterfaces.implementsTR<
|
|
61
|
+
plugins.typedrequestInterfaces.ITypedRequest,
|
|
62
|
+
IReq_AdoptGatewayWithCode
|
|
63
|
+
> {
|
|
64
|
+
method: 'adoptGatewayWithCode';
|
|
65
|
+
request: {
|
|
66
|
+
identity: authInterfaces.IIdentity;
|
|
67
|
+
/** The controller's https origin, such as `https://cloudly.example.com`. */
|
|
68
|
+
controllerOrigin: string;
|
|
69
|
+
/** The adoption code the controller issued for this gateway. */
|
|
70
|
+
code: string;
|
|
71
|
+
};
|
|
72
|
+
response: {
|
|
73
|
+
gatewayId: string;
|
|
74
|
+
controllerId: string;
|
|
75
|
+
epoch: number;
|
|
76
|
+
credentialGeneration: number;
|
|
77
|
+
controllerGatewayClientId: string | null;
|
|
78
|
+
revokedTokens: number;
|
|
79
|
+
};
|
|
80
|
+
}
|
|
@@ -21,6 +21,7 @@ export * from './dns-records.js';
|
|
|
21
21
|
export * from './dns-protected-hostnames.js';
|
|
22
22
|
export * from './dns-mutation-journal.js';
|
|
23
23
|
export * from './gateway-route-dns.js';
|
|
24
|
+
export * from './gateway-adoption.js';
|
|
24
25
|
export * from './acme-config.js';
|
|
25
26
|
export * from './email-domains.js';
|
|
26
27
|
export * from './email-settings.js';
|