@serve.zone/dcrouter-apiclient 34.2.0 → 34.3.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.
@@ -12,14 +12,15 @@ export type TDnsMutationActorKind = 'operator' | 'automation' | 'provider';
12
12
  *
13
13
  * Record mutations: 'create', 'update', 'delete'. Ownership changes that leave the record's
14
14
  * DNS data alone: 'release' (an owned record loses its owner and becomes an operator record),
15
- * 'handoff' (an owned record moves to another owner of the same namespace). Provider
15
+ * 'handoff' (an owned record moves to another owner of the same namespace), 'assign' (an operator
16
+ * gives an operator record to an automation owner, e.g. hands it back to route DNS). Provider
16
17
  * observations: 'mirror-update' and 'mirror-delete' (the local mirror follows a change made at
17
18
  * the provider). Migration to a provider: 'link' (a local record is linked to the provider record
18
19
  * the migration created for it), 'adopt' (a local record is linked to the identical record the
19
20
  * target zone already held) and 'migrate' (the zone switches to the provider). Protected-hostname
20
21
  * list changes: 'protect', 'unprotect'.
21
22
  */
22
- export type TDnsMutationOperation = 'create' | 'update' | 'delete' | 'adopt' | 'release' | 'handoff' | 'mirror-update' | 'mirror-delete' | 'link' | 'migrate' | 'protect' | 'unprotect';
23
+ export type TDnsMutationOperation = 'create' | 'update' | 'delete' | 'adopt' | 'release' | 'handoff' | 'assign' | 'mirror-update' | 'mirror-delete' | 'link' | 'migrate' | 'protect' | 'unprotect';
23
24
  /**
24
25
  * - 'pending' → the intent was written and the mutation has not reported back. A pending entry
25
26
  * that never completes marks a mutation interrupted between its provider call and its local
@@ -25,8 +25,9 @@ export interface IDnsRecord {
25
25
  name: string;
26
26
  type: TDnsRecordType;
27
27
  /**
28
- * Record value as a string. For MX records, formatted as
29
- * `<priority> <exchange>` (e.g. `10 mail.example.com`).
28
+ * Record value as a string, in the shape its type defines (see
29
+ * `TDnsRecordValueField`): an MX value is `<0-65535> <exchange>` (e.g.
30
+ * `10 mail.example.com`, or the RFC 7505 null MX `0 .`).
30
31
  */
31
32
  value: string;
32
33
  /** TTL in seconds. */
@@ -51,3 +52,37 @@ export interface IDnsRecord {
51
52
  */
52
53
  protectedHostname?: true;
53
54
  }
55
+ /**
56
+ * The part of a record a value check names when it refuses the record.
57
+ *
58
+ * - `type` → the record type is not one dcrouter serves.
59
+ * - `value` → the value as a whole (wrong number of fields, empty, not a string).
60
+ * - the rest are the RDATA fields of their types: `address` (A, AAAA),
61
+ * `target` (CNAME, NS), `preference` and `exchange` (MX), and `mname`,
62
+ * `rname`, `serial`, `refresh`, `retry`, `expire` and `minimum` (SOA).
63
+ */
64
+ export type TDnsRecordValueField = 'type' | 'value' | 'address' | 'target' | 'preference' | 'exchange' | 'mname' | 'rname' | 'serial' | 'refresh' | 'retry' | 'expire' | 'minimum';
65
+ /**
66
+ * A record whose value dcrouter refused, or cannot serve: which record and
67
+ * which field. `id` is absent for a record that does not exist yet (a create).
68
+ */
69
+ export interface IDnsRecordValueRefusal {
70
+ id?: string;
71
+ name: string;
72
+ /** The type as stored or requested; it may be one dcrouter does not serve. */
73
+ type: string;
74
+ field: TDnsRecordValueField;
75
+ /** Why the field was refused, for people. */
76
+ reason: string;
77
+ }
78
+ /**
79
+ * A stored record whose value dcrouter cannot encode. Such a record is not
80
+ * served from the embedded DNS server (the rest of its RRset still is), a
81
+ * write through dcrouter refuses it, and a domain migration refuses it.
82
+ */
83
+ export interface IDnsInvalidRecord extends IDnsRecordValueRefusal {
84
+ id: string;
85
+ domainId: string;
86
+ /** The stored value, as it is. */
87
+ value: string;
88
+ }
@@ -0,0 +1,39 @@
1
+ /**
2
+ * What route DNS wants at one hostname for one claiming gateway client: the record type and
3
+ * value its reconcile writes there (the same rule route DNS itself uses, read only).
4
+ */
5
+ export interface IGatewayRouteDnsTarget {
6
+ /** The claimed hostname, lowercase without a trailing dot. */
7
+ hostname: string;
8
+ /** The gateway client whose enabled `reconcile` route(s) claim the hostname. */
9
+ gatewayClientId: string;
10
+ /** The claim's owner id, `managedOwnerId` of the records route DNS writes for it. */
11
+ claimOwnerId: string;
12
+ /** External keys of the claim's enabled `reconcile` routes, sorted. */
13
+ routeExternalKeys: string[];
14
+ /** `A` or `AAAA`; absent when route DNS has no usable target for the claim. */
15
+ recordType?: 'A' | 'AAAA';
16
+ /** The address route DNS points the hostname at; absent when it has none (`target-invalid`). */
17
+ targetIp?: string;
18
+ /** The proxy state the claim's route declares; absent when it declares none (the record's own state is kept). */
19
+ proxied?: boolean;
20
+ }
21
+ /**
22
+ * Why route DNS did not take over an operator record (`handBackDnsRecordToRouteDns`). Nothing
23
+ * was written for any of them.
24
+ *
25
+ * - 'record-not-found' → no record has the id.
26
+ * - 'not-operator-record' → the record has an owner (`managedBy`); only an operator record can be handed back.
27
+ * - 'not-address-record' → the record is neither A nor AAAA.
28
+ * - 'protected-hostname' → the hostname is protected; route DNS may not own a record there.
29
+ * - 'hostname-held' → testing DNS reserves the hostname, or a gateway-client hostname ownership holds it.
30
+ * - 'route-inventory-unavailable' → the route inventory is not loaded yet (retryable).
31
+ * - 'no-active-claim' → the gateway client has no enabled `reconcile` route claiming the hostname.
32
+ * - 'target-unavailable' → route DNS has no usable target for the claim right now (retryable).
33
+ * - 'value-mismatch' → the record's type, value or proxy state is not what route DNS wants.
34
+ * - 'zone-mismatch' → the record is not in the zone route DNS writes the hostname in.
35
+ * - 'other-records' → the hostname holds other A, AAAA or CNAME records besides this one.
36
+ * - 'ownership-changed' → the record changed between the checks and the write (retryable).
37
+ * - 'mutation-failed' → the journal or the write failed (retryable).
38
+ */
39
+ export type TGatewayRouteDnsHandBackRefusal = 'record-not-found' | 'not-operator-record' | 'not-address-record' | 'protected-hostname' | 'hostname-held' | 'route-inventory-unavailable' | 'no-active-claim' | 'target-unavailable' | 'value-mismatch' | 'zone-mismatch' | 'other-records' | 'ownership-changed' | 'mutation-failed';
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZ2F0ZXdheS1yb3V0ZS1kbnMuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90c19pbnRlcmZhY2VzL2RhdGEvZ2F0ZXdheS1yb3V0ZS1kbnMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IiJ9
@@ -11,6 +11,7 @@ export * from './workhoster.js';
11
11
  export * from './dns-record.js';
12
12
  export * from './dns-mutation-journal.js';
13
13
  export * from './dns-protected-hostname.js';
14
+ export * from './gateway-route-dns.js';
14
15
  export * from './acme-config.js';
15
16
  export * from './email-domain.js';
16
17
  export * from './email-settings.js';
@@ -11,6 +11,7 @@ export * from './workhoster.js';
11
11
  export * from './dns-record.js';
12
12
  export * from './dns-mutation-journal.js';
13
13
  export * from './dns-protected-hostname.js';
14
+ export * from './gateway-route-dns.js';
14
15
  export * from './acme-config.js';
15
16
  export * from './email-domain.js';
16
17
  export * from './email-settings.js';
@@ -18,4 +19,4 @@ export * from './smtp-account.js';
18
19
  export * from './security-policy.js';
19
20
  export * from './config-events.js';
20
21
  export * from './testing.js';
21
- //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90c19pbnRlcmZhY2VzL2RhdGEvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsY0FBYyxXQUFXLENBQUM7QUFDMUIsY0FBYyxZQUFZLENBQUM7QUFDM0IsY0FBYyxvQkFBb0IsQ0FBQztBQUNuQyxjQUFjLHVCQUF1QixDQUFDO0FBQ3RDLGNBQWMscUJBQXFCLENBQUM7QUFDcEMsY0FBYyxVQUFVLENBQUM7QUFDekIsY0FBYyxtQkFBbUIsQ0FBQztBQUNsQyxjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLG9CQUFvQixDQUFDO0FBQ25DLGNBQWMsaUJBQWlCLENBQUM7QUFDaEMsY0FBYyxpQkFBaUIsQ0FBQztBQUNoQyxjQUFjLDJCQUEyQixDQUFDO0FBQzFDLGNBQWMsNkJBQTZCLENBQUM7QUFDNUMsY0FBYyxrQkFBa0IsQ0FBQztBQUNqQyxjQUFjLG1CQUFtQixDQUFDO0FBQ2xDLGNBQWMscUJBQXFCLENBQUM7QUFDcEMsY0FBYyxtQkFBbUIsQ0FBQztBQUNsQyxjQUFjLHNCQUFzQixDQUFDO0FBQ3JDLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxjQUFjLENBQUMifQ==
22
+ //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90c19pbnRlcmZhY2VzL2RhdGEvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsY0FBYyxXQUFXLENBQUM7QUFDMUIsY0FBYyxZQUFZLENBQUM7QUFDM0IsY0FBYyxvQkFBb0IsQ0FBQztBQUNuQyxjQUFjLHVCQUF1QixDQUFDO0FBQ3RDLGNBQWMscUJBQXFCLENBQUM7QUFDcEMsY0FBYyxVQUFVLENBQUM7QUFDekIsY0FBYyxtQkFBbUIsQ0FBQztBQUNsQyxjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLG9CQUFvQixDQUFDO0FBQ25DLGNBQWMsaUJBQWlCLENBQUM7QUFDaEMsY0FBYyxpQkFBaUIsQ0FBQztBQUNoQyxjQUFjLDJCQUEyQixDQUFDO0FBQzFDLGNBQWMsNkJBQTZCLENBQUM7QUFDNUMsY0FBYyx3QkFBd0IsQ0FBQztBQUN2QyxjQUFjLGtCQUFrQixDQUFDO0FBQ2pDLGNBQWMsbUJBQW1CLENBQUM7QUFDbEMsY0FBYyxxQkFBcUIsQ0FBQztBQUNwQyxjQUFjLG1CQUFtQixDQUFDO0FBQ2xDLGNBQWMsc0JBQXNCLENBQUM7QUFDckMsY0FBYyxvQkFBb0IsQ0FBQztBQUNuQyxjQUFjLGNBQWMsQ0FBQyJ9
@@ -1,6 +1,6 @@
1
1
  import * as plugins from '../plugins.js';
2
2
  import type * as authInterfaces from '../data/auth.js';
3
- import type { IDnsRecord, TDnsRecordType } from '../data/dns-record.js';
3
+ import type { IDnsInvalidRecord, IDnsRecord, IDnsRecordValueRefusal, TDnsRecordType } from '../data/dns-record.js';
4
4
  /**
5
5
  * Get all DNS records for a domain.
6
6
  */
@@ -51,6 +51,8 @@ export interface IReq_CreateDnsRecord extends plugins.typedrequestInterfaces.imp
51
51
  success: boolean;
52
52
  id?: string;
53
53
  message?: string;
54
+ /** Present when the value was refused (nothing was written). */
55
+ invalidValue?: IDnsRecordValueRefusal;
54
56
  };
55
57
  }
56
58
  /**
@@ -70,6 +72,12 @@ export interface IReq_UpdateDnsRecord extends plugins.typedrequestInterfaces.imp
70
72
  response: {
71
73
  success: boolean;
72
74
  message?: string;
75
+ /**
76
+ * Present when the record as it would be after the update was refused
77
+ * (nothing was written). The whole merged record is checked, not only the
78
+ * fields the request changes.
79
+ */
80
+ invalidValue?: IDnsRecordValueRefusal;
73
81
  };
74
82
  }
75
83
  /**
@@ -87,3 +95,20 @@ export interface IReq_DeleteDnsRecord extends plugins.typedrequestInterfaces.imp
87
95
  message?: string;
88
96
  };
89
97
  }
98
+ /**
99
+ * Every stored record, in every domain, whose value dcrouter cannot encode.
100
+ *
101
+ * A record of a dcrouter-hosted zone in this list is not served (the rest of
102
+ * its RRset is); a provider zone record in it is a local mirror that a write
103
+ * or a migration refuses. Fix or delete each one; dcrouter never rewrites them.
104
+ */
105
+ export interface IReq_GetInvalidDnsRecords extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_GetInvalidDnsRecords> {
106
+ method: 'getInvalidDnsRecords';
107
+ request: {
108
+ identity?: authInterfaces.IIdentity;
109
+ apiToken?: string;
110
+ };
111
+ response: {
112
+ records: IDnsInvalidRecord[];
113
+ };
114
+ }
@@ -147,5 +147,7 @@ export interface IReq_MigrateDomain extends plugins.typedrequestInterfaces.imple
147
147
  /** Number of records migrated. */
148
148
  recordsMigrated?: number;
149
149
  message?: string;
150
+ /** Present when records of the domain have values dcrouter cannot encode; nothing was written. */
151
+ invalidRecords?: import('../data/dns-record.js').IDnsRecordValueRefusal[];
150
152
  };
151
153
  }
@@ -0,0 +1,58 @@
1
+ import * as plugins from '../plugins.js';
2
+ import type * as authInterfaces from '../data/auth.js';
3
+ import type { IDnsRecord } from '../data/dns-record.js';
4
+ import type { IGatewayRouteDnsTarget, TGatewayRouteDnsHandBackRefusal } from '../data/gateway-route-dns.js';
5
+ /**
6
+ * What route DNS wants at every hostname a gateway client claims with an enabled `reconcile`
7
+ * route, one entry per claiming client, sorted by hostname and client: the same target rule the
8
+ * reconciler writes with. Read only. Answers a retryable `TypedResponseError`
9
+ * (`errorData: { code: 'route-inventory-unavailable', retryable: true }`) until the route
10
+ * inventory is loaded. Requires `dns-records:read`.
11
+ */
12
+ export interface IReq_GetGatewayRouteDnsTargets extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_GetGatewayRouteDnsTargets> {
13
+ method: 'getGatewayRouteDnsTargets';
14
+ request: {
15
+ identity?: authInterfaces.IIdentity;
16
+ apiToken?: string;
17
+ /** Only this hostname (any case, trailing dot allowed). */
18
+ hostname?: string;
19
+ };
20
+ response: {
21
+ targets: IGatewayRouteDnsTarget[];
22
+ };
23
+ }
24
+ /**
25
+ * Hand one operator record (no owner) back to route DNS for the claim of `gatewayClientId` at
26
+ * the record's hostname. Refused, with nothing written, unless the record is the hostname's only
27
+ * A, AAAA or CNAME record and its type, value and proxy state are exactly what route DNS wants
28
+ * for that claim (`getGatewayRouteDnsTargets`). On success the record keeps its DNS data and
29
+ * becomes route-owned (`managedBy: 'gateway-route-dns'`), and the DNS mutation journal holds an
30
+ * `assign` entry by the operator. Route DNS never takes over an operator record on its own.
31
+ * Requires an admin identity or an admin API token (`dns-records:write`).
32
+ */
33
+ export interface IReq_HandBackDnsRecordToRouteDns extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_HandBackDnsRecordToRouteDns> {
34
+ method: 'handBackDnsRecordToRouteDns';
35
+ request: {
36
+ identity?: authInterfaces.IIdentity;
37
+ apiToken?: string;
38
+ /** The operator record. */
39
+ recordId: string;
40
+ /** The gateway client whose claim takes the record. */
41
+ gatewayClientId: string;
42
+ /** Why, for the journal. */
43
+ reason: string;
44
+ };
45
+ response: {
46
+ success: true;
47
+ /** The record as stored after the hand-back. */
48
+ record: IDnsRecord;
49
+ target: IGatewayRouteDnsTarget;
50
+ } | {
51
+ success: false;
52
+ refusal: TGatewayRouteDnsHandBackRefusal;
53
+ retryable: boolean;
54
+ message: string;
55
+ /** What route DNS wants, when the claim was found. */
56
+ target?: IGatewayRouteDnsTarget;
57
+ };
58
+ }
@@ -0,0 +1,2 @@
1
+ import * as plugins from '../plugins.js';
2
+ //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZ2F0ZXdheS1yb3V0ZS1kbnMuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90c19pbnRlcmZhY2VzL3JlcXVlc3RzL2dhdGV3YXktcm91dGUtZG5zLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBSyxPQUFPLE1BQU0sZUFBZSxDQUFDIn0=
@@ -20,6 +20,7 @@ export * from './dns-authority.js';
20
20
  export * from './dns-records.js';
21
21
  export * from './dns-protected-hostnames.js';
22
22
  export * from './dns-mutation-journal.js';
23
+ export * from './gateway-route-dns.js';
23
24
  export * from './acme-config.js';
24
25
  export * from './email-domains.js';
25
26
  export * from './email-settings.js';
@@ -20,6 +20,7 @@ export * from './dns-authority.js';
20
20
  export * from './dns-records.js';
21
21
  export * from './dns-protected-hostnames.js';
22
22
  export * from './dns-mutation-journal.js';
23
+ export * from './gateway-route-dns.js';
23
24
  export * from './acme-config.js';
24
25
  export * from './email-domains.js';
25
26
  export * from './email-settings.js';
@@ -29,4 +30,4 @@ export * from './workhoster.js';
29
30
  export * from './security-policy.js';
30
31
  export * from './config-events.js';
31
32
  export * from './testing.js';
32
- //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90c19pbnRlcmZhY2VzL3JlcXVlc3RzL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsWUFBWSxDQUFDO0FBQzNCLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsV0FBVyxDQUFDO0FBQzFCLGNBQWMsWUFBWSxDQUFDO0FBQzNCLGNBQWMscUJBQXFCLENBQUM7QUFDcEMsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxnQkFBZ0IsQ0FBQztBQUMvQixjQUFjLGtCQUFrQixDQUFDO0FBQ2pDLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyx1QkFBdUIsQ0FBQztBQUN0QyxjQUFjLGlCQUFpQixDQUFDO0FBQ2hDLGNBQWMsVUFBVSxDQUFDO0FBQ3pCLGNBQWMsc0JBQXNCLENBQUM7QUFDckMsY0FBYyxzQkFBc0IsQ0FBQztBQUNyQyxjQUFjLHNCQUFzQixDQUFDO0FBQ3JDLGNBQWMsWUFBWSxDQUFDO0FBQzNCLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxvQkFBb0IsQ0FBQztBQUNuQyxjQUFjLGtCQUFrQixDQUFDO0FBQ2pDLGNBQWMsOEJBQThCLENBQUM7QUFDN0MsY0FBYywyQkFBMkIsQ0FBQztBQUMxQyxjQUFjLGtCQUFrQixDQUFDO0FBQ2pDLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxxQkFBcUIsQ0FBQztBQUNwQyxjQUFjLG9CQUFvQixDQUFDO0FBQ25DLGNBQWMsZUFBZSxDQUFDO0FBQzlCLGNBQWMsaUJBQWlCLENBQUM7QUFDaEMsY0FBYyxzQkFBc0IsQ0FBQztBQUNyQyxjQUFjLG9CQUFvQixDQUFDO0FBQ25DLGNBQWMsY0FBYyxDQUFDIn0=
33
+ //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90c19pbnRlcmZhY2VzL3JlcXVlc3RzL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsWUFBWSxDQUFDO0FBQzNCLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsV0FBVyxDQUFDO0FBQzFCLGNBQWMsWUFBWSxDQUFDO0FBQzNCLGNBQWMscUJBQXFCLENBQUM7QUFDcEMsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxnQkFBZ0IsQ0FBQztBQUMvQixjQUFjLGtCQUFrQixDQUFDO0FBQ2pDLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyx1QkFBdUIsQ0FBQztBQUN0QyxjQUFjLGlCQUFpQixDQUFDO0FBQ2hDLGNBQWMsVUFBVSxDQUFDO0FBQ3pCLGNBQWMsc0JBQXNCLENBQUM7QUFDckMsY0FBYyxzQkFBc0IsQ0FBQztBQUNyQyxjQUFjLHNCQUFzQixDQUFDO0FBQ3JDLGNBQWMsWUFBWSxDQUFDO0FBQzNCLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxvQkFBb0IsQ0FBQztBQUNuQyxjQUFjLGtCQUFrQixDQUFDO0FBQ2pDLGNBQWMsOEJBQThCLENBQUM7QUFDN0MsY0FBYywyQkFBMkIsQ0FBQztBQUMxQyxjQUFjLHdCQUF3QixDQUFDO0FBQ3ZDLGNBQWMsa0JBQWtCLENBQUM7QUFDakMsY0FBYyxvQkFBb0IsQ0FBQztBQUNuQyxjQUFjLHFCQUFxQixDQUFDO0FBQ3BDLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxlQUFlLENBQUM7QUFDOUIsY0FBYyxpQkFBaUIsQ0FBQztBQUNoQyxjQUFjLHNCQUFzQixDQUFDO0FBQ3JDLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxjQUFjLENBQUMifQ==
package/package.json CHANGED
@@ -28,7 +28,7 @@
28
28
  "MAC authentication"
29
29
  ],
30
30
  "name": "@serve.zone/dcrouter-apiclient",
31
- "version": "34.2.0",
31
+ "version": "34.3.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",
@@ -14,7 +14,8 @@ export type TDnsMutationActorKind = 'operator' | 'automation' | 'provider';
14
14
  *
15
15
  * Record mutations: 'create', 'update', 'delete'. Ownership changes that leave the record's
16
16
  * DNS data alone: 'release' (an owned record loses its owner and becomes an operator record),
17
- * 'handoff' (an owned record moves to another owner of the same namespace). Provider
17
+ * 'handoff' (an owned record moves to another owner of the same namespace), 'assign' (an operator
18
+ * gives an operator record to an automation owner, e.g. hands it back to route DNS). Provider
18
19
  * observations: 'mirror-update' and 'mirror-delete' (the local mirror follows a change made at
19
20
  * the provider). Migration to a provider: 'link' (a local record is linked to the provider record
20
21
  * the migration created for it), 'adopt' (a local record is linked to the identical record the
@@ -28,6 +29,7 @@ export type TDnsMutationOperation =
28
29
  | 'adopt'
29
30
  | 'release'
30
31
  | 'handoff'
32
+ | 'assign'
31
33
  | 'mirror-update'
32
34
  | 'mirror-delete'
33
35
  | 'link'
@@ -27,8 +27,9 @@ export interface IDnsRecord {
27
27
  name: string;
28
28
  type: TDnsRecordType;
29
29
  /**
30
- * Record value as a string. For MX records, formatted as
31
- * `<priority> <exchange>` (e.g. `10 mail.example.com`).
30
+ * Record value as a string, in the shape its type defines (see
31
+ * `TDnsRecordValueField`): an MX value is `<0-65535> <exchange>` (e.g.
32
+ * `10 mail.example.com`, or the RFC 7505 null MX `0 .`).
32
33
  */
33
34
  value: string;
34
35
  /** TTL in seconds. */
@@ -53,3 +54,53 @@ export interface IDnsRecord {
53
54
  */
54
55
  protectedHostname?: true;
55
56
  }
57
+
58
+ /**
59
+ * The part of a record a value check names when it refuses the record.
60
+ *
61
+ * - `type` → the record type is not one dcrouter serves.
62
+ * - `value` → the value as a whole (wrong number of fields, empty, not a string).
63
+ * - the rest are the RDATA fields of their types: `address` (A, AAAA),
64
+ * `target` (CNAME, NS), `preference` and `exchange` (MX), and `mname`,
65
+ * `rname`, `serial`, `refresh`, `retry`, `expire` and `minimum` (SOA).
66
+ */
67
+ export type TDnsRecordValueField =
68
+ | 'type'
69
+ | 'value'
70
+ | 'address'
71
+ | 'target'
72
+ | 'preference'
73
+ | 'exchange'
74
+ | 'mname'
75
+ | 'rname'
76
+ | 'serial'
77
+ | 'refresh'
78
+ | 'retry'
79
+ | 'expire'
80
+ | 'minimum';
81
+
82
+ /**
83
+ * A record whose value dcrouter refused, or cannot serve: which record and
84
+ * which field. `id` is absent for a record that does not exist yet (a create).
85
+ */
86
+ export interface IDnsRecordValueRefusal {
87
+ id?: string;
88
+ name: string;
89
+ /** The type as stored or requested; it may be one dcrouter does not serve. */
90
+ type: string;
91
+ field: TDnsRecordValueField;
92
+ /** Why the field was refused, for people. */
93
+ reason: string;
94
+ }
95
+
96
+ /**
97
+ * A stored record whose value dcrouter cannot encode. Such a record is not
98
+ * served from the embedded DNS server (the rest of its RRset still is), a
99
+ * write through dcrouter refuses it, and a domain migration refuses it.
100
+ */
101
+ export interface IDnsInvalidRecord extends IDnsRecordValueRefusal {
102
+ id: string;
103
+ domainId: string;
104
+ /** The stored value, as it is. */
105
+ value: string;
106
+ }
@@ -0,0 +1,53 @@
1
+ /**
2
+ * What route DNS wants at one hostname for one claiming gateway client: the record type and
3
+ * value its reconcile writes there (the same rule route DNS itself uses, read only).
4
+ */
5
+ export interface IGatewayRouteDnsTarget {
6
+ /** The claimed hostname, lowercase without a trailing dot. */
7
+ hostname: string;
8
+ /** The gateway client whose enabled `reconcile` route(s) claim the hostname. */
9
+ gatewayClientId: string;
10
+ /** The claim's owner id, `managedOwnerId` of the records route DNS writes for it. */
11
+ claimOwnerId: string;
12
+ /** External keys of the claim's enabled `reconcile` routes, sorted. */
13
+ routeExternalKeys: string[];
14
+ /** `A` or `AAAA`; absent when route DNS has no usable target for the claim. */
15
+ recordType?: 'A' | 'AAAA';
16
+ /** The address route DNS points the hostname at; absent when it has none (`target-invalid`). */
17
+ targetIp?: string;
18
+ /** The proxy state the claim's route declares; absent when it declares none (the record's own state is kept). */
19
+ proxied?: boolean;
20
+ }
21
+
22
+ /**
23
+ * Why route DNS did not take over an operator record (`handBackDnsRecordToRouteDns`). Nothing
24
+ * was written for any of them.
25
+ *
26
+ * - 'record-not-found' → no record has the id.
27
+ * - 'not-operator-record' → the record has an owner (`managedBy`); only an operator record can be handed back.
28
+ * - 'not-address-record' → the record is neither A nor AAAA.
29
+ * - 'protected-hostname' → the hostname is protected; route DNS may not own a record there.
30
+ * - 'hostname-held' → testing DNS reserves the hostname, or a gateway-client hostname ownership holds it.
31
+ * - 'route-inventory-unavailable' → the route inventory is not loaded yet (retryable).
32
+ * - 'no-active-claim' → the gateway client has no enabled `reconcile` route claiming the hostname.
33
+ * - 'target-unavailable' → route DNS has no usable target for the claim right now (retryable).
34
+ * - 'value-mismatch' → the record's type, value or proxy state is not what route DNS wants.
35
+ * - 'zone-mismatch' → the record is not in the zone route DNS writes the hostname in.
36
+ * - 'other-records' → the hostname holds other A, AAAA or CNAME records besides this one.
37
+ * - 'ownership-changed' → the record changed between the checks and the write (retryable).
38
+ * - 'mutation-failed' → the journal or the write failed (retryable).
39
+ */
40
+ export type TGatewayRouteDnsHandBackRefusal =
41
+ | 'record-not-found'
42
+ | 'not-operator-record'
43
+ | 'not-address-record'
44
+ | 'protected-hostname'
45
+ | 'hostname-held'
46
+ | 'route-inventory-unavailable'
47
+ | 'no-active-claim'
48
+ | 'target-unavailable'
49
+ | 'value-mismatch'
50
+ | 'zone-mismatch'
51
+ | 'other-records'
52
+ | 'ownership-changed'
53
+ | 'mutation-failed';
@@ -11,6 +11,7 @@ export * from './workhoster.js';
11
11
  export * from './dns-record.js';
12
12
  export * from './dns-mutation-journal.js';
13
13
  export * from './dns-protected-hostname.js';
14
+ export * from './gateway-route-dns.js';
14
15
  export * from './acme-config.js';
15
16
  export * from './email-domain.js';
16
17
  export * from './email-settings.js';
@@ -1,6 +1,11 @@
1
1
  import * as plugins from '../plugins.js';
2
2
  import type * as authInterfaces from '../data/auth.js';
3
- import type { IDnsRecord, TDnsRecordType } from '../data/dns-record.js';
3
+ import type {
4
+ IDnsInvalidRecord,
5
+ IDnsRecord,
6
+ IDnsRecordValueRefusal,
7
+ TDnsRecordType,
8
+ } from '../data/dns-record.js';
4
9
 
5
10
  // ============================================================================
6
11
  // DNS Record Endpoints
@@ -67,6 +72,8 @@ export interface IReq_CreateDnsRecord extends plugins.typedrequestInterfaces.imp
67
72
  success: boolean;
68
73
  id?: string;
69
74
  message?: string;
75
+ /** Present when the value was refused (nothing was written). */
76
+ invalidValue?: IDnsRecordValueRefusal;
70
77
  };
71
78
  }
72
79
 
@@ -90,6 +97,12 @@ export interface IReq_UpdateDnsRecord extends plugins.typedrequestInterfaces.imp
90
97
  response: {
91
98
  success: boolean;
92
99
  message?: string;
100
+ /**
101
+ * Present when the record as it would be after the update was refused
102
+ * (nothing was written). The whole merged record is checked, not only the
103
+ * fields the request changes.
104
+ */
105
+ invalidValue?: IDnsRecordValueRefusal;
93
106
  };
94
107
  }
95
108
 
@@ -111,3 +124,24 @@ export interface IReq_DeleteDnsRecord extends plugins.typedrequestInterfaces.imp
111
124
  message?: string;
112
125
  };
113
126
  }
127
+
128
+ /**
129
+ * Every stored record, in every domain, whose value dcrouter cannot encode.
130
+ *
131
+ * A record of a dcrouter-hosted zone in this list is not served (the rest of
132
+ * its RRset is); a provider zone record in it is a local mirror that a write
133
+ * or a migration refuses. Fix or delete each one; dcrouter never rewrites them.
134
+ */
135
+ export interface IReq_GetInvalidDnsRecords extends plugins.typedrequestInterfaces.implementsTR<
136
+ plugins.typedrequestInterfaces.ITypedRequest,
137
+ IReq_GetInvalidDnsRecords
138
+ > {
139
+ method: 'getInvalidDnsRecords';
140
+ request: {
141
+ identity?: authInterfaces.IIdentity;
142
+ apiToken?: string;
143
+ };
144
+ response: {
145
+ records: IDnsInvalidRecord[];
146
+ };
147
+ }
@@ -183,5 +183,7 @@ export interface IReq_MigrateDomain extends plugins.typedrequestInterfaces.imple
183
183
  /** Number of records migrated. */
184
184
  recordsMigrated?: number;
185
185
  message?: string;
186
+ /** Present when records of the domain have values dcrouter cannot encode; nothing was written. */
187
+ invalidRecords?: import('../data/dns-record.js').IDnsRecordValueRefusal[];
186
188
  };
187
189
  }
@@ -0,0 +1,72 @@
1
+ import * as plugins from '../plugins.js';
2
+ import type * as authInterfaces from '../data/auth.js';
3
+ import type { IDnsRecord } from '../data/dns-record.js';
4
+ import type { IGatewayRouteDnsTarget, TGatewayRouteDnsHandBackRefusal } from '../data/gateway-route-dns.js';
5
+
6
+ // ============================================================================
7
+ // Gateway route DNS (operator reads and the hand-back)
8
+ // ============================================================================
9
+
10
+ /**
11
+ * What route DNS wants at every hostname a gateway client claims with an enabled `reconcile`
12
+ * route, one entry per claiming client, sorted by hostname and client: the same target rule the
13
+ * reconciler writes with. Read only. Answers a retryable `TypedResponseError`
14
+ * (`errorData: { code: 'route-inventory-unavailable', retryable: true }`) until the route
15
+ * inventory is loaded. Requires `dns-records:read`.
16
+ */
17
+ export interface IReq_GetGatewayRouteDnsTargets extends plugins.typedrequestInterfaces.implementsTR<
18
+ plugins.typedrequestInterfaces.ITypedRequest,
19
+ IReq_GetGatewayRouteDnsTargets
20
+ > {
21
+ method: 'getGatewayRouteDnsTargets';
22
+ request: {
23
+ identity?: authInterfaces.IIdentity;
24
+ apiToken?: string;
25
+ /** Only this hostname (any case, trailing dot allowed). */
26
+ hostname?: string;
27
+ };
28
+ response: {
29
+ targets: IGatewayRouteDnsTarget[];
30
+ };
31
+ }
32
+
33
+ /**
34
+ * Hand one operator record (no owner) back to route DNS for the claim of `gatewayClientId` at
35
+ * the record's hostname. Refused, with nothing written, unless the record is the hostname's only
36
+ * A, AAAA or CNAME record and its type, value and proxy state are exactly what route DNS wants
37
+ * for that claim (`getGatewayRouteDnsTargets`). On success the record keeps its DNS data and
38
+ * becomes route-owned (`managedBy: 'gateway-route-dns'`), and the DNS mutation journal holds an
39
+ * `assign` entry by the operator. Route DNS never takes over an operator record on its own.
40
+ * Requires an admin identity or an admin API token (`dns-records:write`).
41
+ */
42
+ export interface IReq_HandBackDnsRecordToRouteDns extends plugins.typedrequestInterfaces.implementsTR<
43
+ plugins.typedrequestInterfaces.ITypedRequest,
44
+ IReq_HandBackDnsRecordToRouteDns
45
+ > {
46
+ method: 'handBackDnsRecordToRouteDns';
47
+ request: {
48
+ identity?: authInterfaces.IIdentity;
49
+ apiToken?: string;
50
+ /** The operator record. */
51
+ recordId: string;
52
+ /** The gateway client whose claim takes the record. */
53
+ gatewayClientId: string;
54
+ /** Why, for the journal. */
55
+ reason: string;
56
+ };
57
+ response:
58
+ | {
59
+ success: true;
60
+ /** The record as stored after the hand-back. */
61
+ record: IDnsRecord;
62
+ target: IGatewayRouteDnsTarget;
63
+ }
64
+ | {
65
+ success: false;
66
+ refusal: TGatewayRouteDnsHandBackRefusal;
67
+ retryable: boolean;
68
+ message: string;
69
+ /** What route DNS wants, when the claim was found. */
70
+ target?: IGatewayRouteDnsTarget;
71
+ };
72
+ }
@@ -20,6 +20,7 @@ export * from './dns-authority.js';
20
20
  export * from './dns-records.js';
21
21
  export * from './dns-protected-hostnames.js';
22
22
  export * from './dns-mutation-journal.js';
23
+ export * from './gateway-route-dns.js';
23
24
  export * from './acme-config.js';
24
25
  export * from './email-domains.js';
25
26
  export * from './email-settings.js';