This is an automated email from the ASF dual-hosted git repository. ocket8888 pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/trafficcontrol-trafficops-types.git
commit b9ef7b40dfdf2267f2caeba051ef2835b236d2ed Author: ocket8888 <[email protected]> AuthorDate: Wed Apr 27 20:31:39 2022 -0600 Actually finish out typings --- src/capability.ts | 31 +++++ src/coordinate.ts | 24 ++++ src/delivery.service.request.ts | 172 +++++++++++++++++++++++ src/dnssec.ts | 40 ++++++ src/federation.ts | 243 ++++++++++++++++++++++++++++++++ src/origin.ts | 144 +++++++++++++++++++ src/router.ts | 19 +++ src/server.capability.ts | 110 +++++++++++++++ src/snap.and.queue.ts | 301 ++++++++++++++++++++++++++++++++++++++++ src/ssl.ts | 90 ++++++++++++ src/steering.ts | 58 ++++++++ src/topology.ts | 51 +++++++ src/uri.signing.ts | 16 +++ 13 files changed, 1299 insertions(+) diff --git a/src/capability.ts b/src/capability.ts new file mode 100644 index 0000000..1db867a --- /dev/null +++ b/src/capability.ts @@ -0,0 +1,31 @@ +/** + * Represents a mapping of a Traffic Ops API route to a Capability it might + * require. These cannot be modified through the API. + * + * @deprecated These supposed restrictions have never been and never will be + * enforced at any level. Capabilities as a concept have been removed/reworked + * in the latest version of the API, and the Traffic Ops API route that used to + * expose this structure has been removed. + */ +export interface APICapability { + readonly capability: string; + readonly httpRoute: string; + readonly id: number; + readonly lastUpdated: Date; + readonly method: "GET" | "PUT" | "POST" | "PATCH" | "DELETE"; +} + +/** + * A Capability represents permission to use an HTTP request method on a Traffic + * Ops API endpoint. As of ATCv6, these are not modifiable through the API. + * + * @deprecated These supposed restrictions have never been and never will be + * enforced at any level. Capabilities as a concept have been removed/reworked + * in the latest version of the API, and the Traffic Ops API route that used to + * expose this structure has been removed. + */ +export interface Capability { + readonly description: string; + readonly lastUpdated: Date; + readonly name: string; +} diff --git a/src/coordinate.ts b/src/coordinate.ts new file mode 100644 index 0000000..b26e12a --- /dev/null +++ b/src/coordinate.ts @@ -0,0 +1,24 @@ +/** + * Represents a Coordinate as Traffic Ops requires it in requests made to the + * `/coordinates` endpoint of its API. + */ +export interface RequestCoordinate { + latitude: number; + longitude: number; + name: string; +} + +/** + * Represents a Coordinate as presented by Traffic Ops in responses from the + * `/coordinates` endpoint of its API. + */ +export interface ResponseCoordinate { + readonly id: number; + readonly lastUpdated: Date; + latitude: number; + longitude: number; + name: string; +} + +/** Represents a Coordinate in an arbitrary context. */ +export type Coordinate = RequestCoordinate | ResponseCoordinate; diff --git a/src/delivery.service.request.ts b/src/delivery.service.request.ts new file mode 100644 index 0000000..64503a4 --- /dev/null +++ b/src/delivery.service.request.ts @@ -0,0 +1,172 @@ +import type { DeliveryService } from "./delivery.service"; + +/** + * Represents a request to create or edit a Delivery Service Request Comment. + */ +export interface RequestDeliveryServiceRequestComment { + deliveryServiceRequestId: number; + value: string; +} + +/** + * Represents a response from Traffic Ops to a request for the creation or + * modification of a Delivery Service Request Comment. + */ +export interface RequestDeliveryServiceRequestCommentResponse { + authorId: number; + /** + * This will be whatever it was in the request - not necessarily the truth. + * (undefined will be coerced into `null`). + */ + author: string | null; + deliveryServiceRequestId: number; + readonly id: number; + readonly lastUpdated: Date; + value: string; + /** + * This will be whatever it was in the request - not necessarily the truth. + * (undefined will be coerced into `null`). + */ + xmlId: string | null; +} + +/** + * Represents a Delivery Service Request Comment as it appears in responses to + * `GET` requests made to the `/deliveryservice_request_comments` endpoint of + * the Traffic Ops API. + */ +export interface ResponseDeliveryServiceRequestComment { + authorId: number; + author: string; + deliveryServiceRequestId: number; + readonly id: number; + readonly lastUpdated: Date; + value: string; + xmlId: string; +} + +/** Represents a Delivery Service Request comment in an arbitrary context. */ +export type DeliveryServiceRequestComment = RequestDeliveryServiceRequestComment | RequestDeliveryServiceRequestCommentResponse | ResponseDeliveryServiceRequestComment; + +/** The various types of changes indicated by a Delivery Service Request (DSR). */ +export const enum DSRChangeType { + /** The `changeType` of a DSR for creating a new Delivery Service. */ + CREATE = "create", + /** The `changeType` of a DSR for deleting an existing Delivery Service. */ + DELETE = "delete", + /** The `changeType` of a DSR for modifying an existing Delivery Service. */ + UPDATE = "update" +} + +/** The various statuses of a Delivery Service Request (DSR). */ +export const enum DSRStatus { + /** This request has been carried out fully and was enacted as stated. */ + COMPLETE = "complete", + /** This request is a draft, and isn't ready to be implemented. */ + DRAFT = "draft", + /** + * This request has been accepted, but is waiting for further actions before + * it can be called complete. + */ + PENDING = "pending", + /** This request will never be implemented as-is. */ + REJECTED = "rejected", + /** This request is ready for review and either approval or rejection. */ + SUBMITTED = "submitted" +} + +/** + * Represents a Delivery Service Request as Traffic Ops requires it in requests. + */ +export interface RequestDeliveryServiceRequest { + assigneeId?: number | null; + changeType: DSRChangeType; + deliveryService: DeliveryService; + status: DSRStatus; +} + +/** A Delivery Service Request with no assignee, as it appears in responses. */ +interface UnassignedResponseDeliveryServiceRequest { + readonly author: string; + readonly authorId: number; + changeType: DSRChangeType; + readonly createdAt: Date; + deliveryService: DeliveryService; + readonly id: number; + readonly lastEditedBy: string; + readonly lastEditedById: number; + readonly lastUpdated: Date; + status: DSRStatus; +} + +/** An assigned DSR, as it appears in responses. */ +interface AssignedResponseDeliveryServiceRequest extends UnassignedResponseDeliveryServiceRequest { + assignee: string; + assigneeId: number; +} + +/** + * Represents a Delivery Service Request as it appears in (some) responses + */ +export type ResponseDeliveryServiceRequest = AssignedResponseDeliveryServiceRequest | UnassignedResponseDeliveryServiceRequest; + +/** Represents a Delivery Service Request in an arbitrary context. */ +export type DeliveryServiceRequest = ResponseDeliveryServiceRequest | RequestDeliveryServiceRequest; + +/** + * Represents a request to change the assignee of a DSR. + * + * Both an undefined value and `null` mean "remove the current assignee". + */ +export interface DeliveryServiceAssignmentChangeRequest { + assigneeId?: number | null; +} + +/** + * Represents a request to change the status of a DSR. + */ +export interface DeliveryServiceStatusChangeRequest { + status: DSRStatus; +} + +/** + * Represents a request to submit a Delivery Service change or creation request + * via email through the `/deliveryservices/request` endpoint of the Traffic Ops + * API. + * + * @deprecated This structure is superseded by {@link DeliveryServiceRequest} + * objects and has been removed from the latest version of the API. + */ +export interface DeliveryServicesRequest { + details: { + customer: string; + deepCachingType: "ALWAYS" | "NEVER"; + deliveryProtocol: "http" | "https" | "http/https"; + hasNegativeCachingCustomization: boolean; + hasOriginACLWhitelist: boolean; + hasOriginDynamicRemap: boolean; + hasSignedURLs: boolean; + headerRewriteEdge?: string | null; + headerRewriteMid?: string | null; + headerRewriteRedirectRouter?: string | null; + maxLibrarySizeEstimate: string; + negativeCachingCustomizationNote: string; + notes?: string | null; + originHeaders?: string | null; + originTestFile: string; + originURL: string; + otherOriginSecurity?: string | null; + overflowService?: string | null; + peakBPSEstimate: string; + peakTPSEstimate: string; + queryStringHandling: string; + rangeRequestHandling: string; + rateLimitingGBPS?: number | null; + rateLimitingTPS?: number | null; + routingName?: string | null; + routingType: "HTTP" | "DNS" | "STEERING" | "ANY_MAP"; + serviceAliases?: Array<string> | null; + serviceDesc: string; + }; + emailTo: string; +} diff --git a/src/dnssec.ts b/src/dnssec.ts new file mode 100644 index 0000000..54d1ab3 --- /dev/null +++ b/src/dnssec.ts @@ -0,0 +1,40 @@ +/** + * Represents a request to generate DNSSEC Keys for a CDN. + */ +export interface CDNDNSSECKeyGenerationRequest { + /** @default Date.now() */ + effectiveDate?: Date | null; + /** + * This is actually the name of the CDN for which keys will be generated. + */ + key: string; + kskExpirationDays: number; + /** In seconds. */ + ttl: number; + zskExpirationDays: number; +} + +/** CDNDNSSECKeys represents the DNSSEC Keys for a single CDN. */ +export interface CDNDNSSECKeys { + ksk: { + expirationDate: Date; + dsRecord?: { + algorithm: string; + digest: string; + digestType: string; + }; + inceptionDate: Date; + name: string; + private: string; + public: string; + ttl: number; + }; + zsk: { + expirationDate: Date; + inceptionDate: Date; + name: string; + private: string; + public: string; + ttl: number; + }; +} diff --git a/src/federation.ts b/src/federation.ts new file mode 100644 index 0000000..c8153f1 --- /dev/null +++ b/src/federation.ts @@ -0,0 +1,243 @@ +/** + * Represents a "CDN Federation" in a response to a GET made to the + * `/cdns/{{name}}/federations` endpoint of the Traffic Ops API + */ +export interface ResponseCDNFederation { + cname: string; + deliveryService: { + id: number; + xmlId: string; + }; + description: string; + readonly lastUpdated: Date; + /** In hours. */ + ttl: number; +} + +/** + * Represents a response to a "POST" request made to the + * `/cdns/{{name}}/federations` endpoint of the Traffic Ops API to create a + * "CDN Federation". + */ +export interface PostResponseCDNFederation { + cname: string; + description: string; + readonly lastUpdated: Date; + /** In hours. */ + ttl: number; +} + +/** + * A Request CDN Federation represents a CDN Federation as Traffic Ops requires + * it to appear in the request to `/cdns/{{name}}/federations` that creates it. + */ +export interface RequestCDNFederation { + cname: string; + description: string; + /** In hours. */ + ttl: number; +} + +/** Represents a CDN Federation in an arbitrary context. */ +export type CDNFederation = ResponseCDNFederation | PostResponseCDNFederation | RequestCDNFederation; + +/** + * Represents a Federation Resolver as Traffic Ops requires it to + * appear in requests. + */ +export interface RequestFederationResolver { + ipAddress: string; + typeId: number; +} + +/** + * Represents a Federation Resolver as Traffic Ops presents it in + * responses. + */ +export interface ResponseFederationResolver { + readonly id: number; + ipAddress: string; + readonly lastUpdated: Date; + type: string; +} + +/** + * Represents a Federation Resolver in an arbitrary context. + */ +export type FederationResolver = RequestFederationResolver | ResponseFederationResolver; + +/** + * A set of Federation Resolver Mapping sets associated with specific address + * families as they appear in requests. + */ +export interface RequestFederationResolverMapping { + resolve4?: Array<string> | null; + resolve6?: Array<string> | null; +} + +/** + * Represents an association between a set of address-family-associated + * Federation Resolver Mappings and a Delivery Service that is itself associated + * with a CDN Federation that is assigned to the currently authenticated user, + * as Traffic Ops requires it to exist in requests. + */ +export interface RequestUserDeliveryServiceFederationResolverMapping { + /** + * The XMLID of the Delivery Service to which the Federation Resolver + * Resolvers in `mappings` are assigned. + */ + deliveryService: string; + mappings: RequestFederationResolverMapping; +} + +/** A CNAME value that can be used in Federation Resolver Mappings. */ +export type FederationResolverMappingCNAME = `${string}.`; + +/** + * Checks if a given string is usable as a Federation Resolver Mapping CNAME + * value. + * + * @param str The string to check. + * @returns `true` if `str` is valid as a value for a CNAME in a Federation + * Resolver Mapping, or `false` otherwise. + */ +export function isValidFederationResolverMappingCNAME(str: string): str is FederationResolverMappingCNAME { + return /^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?)*\.$/.test(str); +} + +/** + * A set of Federation Resolver Mapping sets associated with specific address + * families as they appear in responses. + */ +export interface ResponseFederationResolverMapping extends RequestFederationResolverMapping { + ttl: number; + cname: FederationResolverMappingCNAME; + resolve4?: [string, ...string[]]; + resolve6?: [string, ...string[]]; +}; + +/** + * Represents an association between a set of address-family-associated + * Federation Resolver Mappings and a Delivery Service that is itself associated + * with a CDN Federation that is assigned to the currently authenticated user, + * as Traffic Ops presents it in responses. + */ +export interface ResponseUserDeliveryServiceFederationResolverMapping { + /** + * The XMLID of the Delivery Service to which the Federation Resolver + * Resolvers in `mappings` are assigned. + */ + deliveryService: string; + mappings: Array<ResponseFederationResolverMapping>; +} + +/** + * Represents a single Federation as exposed by the `/federations/all` endpoint + * of the Traffic Ops API. + */ +export type AllFederation = ResponseUserDeliveryServiceFederationResolverMapping; + +/** + * Represents a request to assign a set of zero or more Delivery Services to a + * specific CDN Federation. + */ +export interface AssignDeliveryServicesToCDNFederationRequest { + /** @default [] */ + dsIds?: Array<number> | null; + /** @default false */ + replace?: boolean | null; +} + +/** + * Represents a response to an + * {@link AssignDeliveryServicesToCDNFederationRequest}. + */ +export interface AssignDeliveryServicesToCDNFederationRequestResponse { + dsIds: Array<number> | null; + replace: boolean | null; +} + +/** + * Represents an association between a particular CDN Federation and a single + * Delivery Service which is assigned to it. + */ +export interface DeliveryServiceCDNFederationAssociation { + cdn: string; + /** + * The ID of the Delivery Service identified by `xmlId` - *not* the + * Federation. + */ + readonly id: number; + /** The Name of the Type of the Delivery Service identified by `xmlId`. */ + type: string; + xmlId: string; +} + +/** + * Represents a request to assign a particular CDN Federation to a set of zero + * or more users. + */ +export interface AssignCDNFederationToUsersRequest { + /** @default false */ + replace?: boolean | null; + /** @default [] */ + userIds?: Array<number> | null; +} + +/** Represents a response to an {@link AssignCDNFederationToUsersRequest}. */ +export interface AssignCDNFederationToUsersRequestResponse { + replace: boolean | null; + userIds: Array<number> | null; +} + +/** + * Represents an association between a particular CDN Federation and a single + * user to whom it is assigned. + */ +export interface UserCDNFederationAssociation { + company: string | null; + email: string; + fullName: string; + /** + * The ID of the user identified by `username` - *not* the ID of the + * Federation. + */ + readonly id: number; + role: string; + username: string; +} + +/** + * Represents a request to assign zero or more Federation Resolvers to a + * Federation. + */ +export interface FederationFederationResolverAssociationRequest { + /** @default [] */ + fedResolverIDs?: Array<number> | null; + /** @default false */ + replace?: boolean | null; +} + +/** + * Represents Traffic Ops's response to a + * {@link FederationFederationResolverAssociationRequest}. + */ +export interface FederationFederationResolverAssociationRequestResponse { + /** Refer to {@link https://github.com/apache/trafficcontrol/issues/6795 #6795} */ + alerts: null; + /** Refer to {@link https://github.com/apache/trafficcontrol/issues/6795 #6795} */ + response: { + fedResolverIds: null | Array<number>; + replace: boolean; + }; +} + +/** + * Represents an association between a particular Federation and a Federation + * Resolver. + */ +export interface FederationFederationResolver { + readonly id: number; + ipAddress: string; + type: string; +} diff --git a/src/origin.ts b/src/origin.ts new file mode 100644 index 0000000..e9c237e --- /dev/null +++ b/src/origin.ts @@ -0,0 +1,144 @@ +/** + * Represents an Origin in the context of a request body. + */ +export interface RequestOrigin { + /** @default null */ + cachegroupId?: number | null; + /** @default null */ + coordinateId?: number | null; + deliveryServiceId: number; + fqdn: string; + /** @default null */ + ip6Address?: string | null; + /** @default null */ + ipAddress?: string | null; + /** @default false */ + isPrimary?: boolean | null; + name: string; + /** @default null */ + port?: number | null; + protocol: "http" | "https"; + /** @default null */ + profileId?: number | null; + tenantID: number; +} + +/** + * Represents an Origin as Traffic Ops presets in in responses to requests + * containing {@link RequestOrigin}s. + */ +export interface RequestOriginResponse { + cachegroup: string | null; + cachegroupId: number | null; + coordinate: string | null; + coordinateId: number | null; + deliveryService: string | null; + deliveryServiceId: number; + fqdn: string; + readonly id: number; + ip6Address: string | null; + ipAddress: string | null; + isPrimary: boolean | null; + readonly lastUpdated: Date; + name: string; + port: number | null; + protocol: "http" | "https"; + profile: string | null; + profileId: number | null; + tenant: string | null; + /** + * Refer to + * {@link https://github.com/apache/trafficcontrol/issues/6796 #6796} + */ + tenantId: number; +} + +/** + * The basic set of properties common to all Origins in responses. + */ +interface ResponseOriginBase { + deliveryService: string; + deliveryServiceId: number; + fqdn: string; + readonly id: number; + ip6Address: string | null; + ipAddress: string | null; + isPrimary: boolean; + readonly lastUpdated: Date; + name: string; + port: number | null; + protocol: "http" | "https"; + tenant: string; + /** + * Refer to + * {@link https://github.com/apache/trafficcontrol/issues/6796 #6796} + */ + tenantId: number; +} + +/** + * An Origin with a Cache Group - both related fields are known to be non-null. + */ +interface ResponseOriginWithCacheGroup extends ResponseOriginBase { + cachegroup: string; + cachegroupId: number; +} + +/** + * An Origin without a Cache Group - both related fields are known to be null. + */ +interface ResponseOriginWithoutCacheGroup extends ResponseOriginBase { + cachegroup: null; + cachegroupId: null; +} + +/** + * An Origin with a Profile - both related fields are known to be non-null. + */ +interface ResponseOriginWithProfile extends ResponseOriginBase { + profile: string; + profileId: number; +} + +/** + * An Origin without a Profile - both related fields are known to be null. + */ +interface ResponseOriginWithoutProfile extends ResponseOriginBase { + profile: null; + profileId: null; +} + +/** + * An Origin with a Coordinate - both related fields are known to be non-null. + */ +interface ResponseOriginWithCoordinate extends ResponseOriginBase { + coordinate: string; + coordinateId: number; +} + +/** + * An Origin without a Coordinate - both related fields are known to be null. + */ +interface ResponseOriginWithoutCoordinate extends ResponseOriginBase { + coordinate: null; + coordinateId: null; +} + +/** + * Represents an Origin of content as presented by Traffic Ops in (most) + * responses. + */ +export type ResponseOrigin = (ResponseOriginWithCacheGroup & ResponseOriginWithProfile & ResponseOriginWithCoordinate) | +(ResponseOriginWithCacheGroup & ResponseOriginWithoutProfile & ResponseOriginWithCoordinate) | +(ResponseOriginWithoutCacheGroup & ResponseOriginWithProfile & ResponseOriginWithCoordinate) | +(ResponseOriginWithoutCacheGroup & ResponseOriginWithoutProfile & ResponseOriginWithCoordinate) | +(ResponseOriginWithCacheGroup & ResponseOriginWithProfile & ResponseOriginWithoutCoordinate) | +(ResponseOriginWithCacheGroup & ResponseOriginWithoutProfile & ResponseOriginWithoutCoordinate) | +(ResponseOriginWithoutCacheGroup & ResponseOriginWithProfile & ResponseOriginWithoutCoordinate) | +(ResponseOriginWithoutCacheGroup & ResponseOriginWithoutProfile & ResponseOriginWithoutCoordinate); + +/** + * An Origin is a source of content to be delivered by a CDN to requesting + * clients. + */ +export type Origin = ResponseOrigin | RequestOrigin | RequestOriginResponse; diff --git a/src/router.ts b/src/router.ts new file mode 100644 index 0000000..e618f4a --- /dev/null +++ b/src/router.ts @@ -0,0 +1,19 @@ +/** + * Represents a Consistent Hashing Regular Expression and a sample route + * submitted to the API to test how it would be routed. + */ +export interface ConsistentHashRegexTest { + cdnId: number; + regex: string; + requestPath: string; +} + +/** + * Represents the result of a test routing of a Consistent Hashing Regular + * Expression. + */ +export interface ConsistentHashRegexTestResult { + resultingPathToConsistentHash: string; + consistentHashRegex: string; + requestPath: string; +} diff --git a/src/server.capability.ts b/src/server.capability.ts new file mode 100644 index 0000000..360ec6f --- /dev/null +++ b/src/server.capability.ts @@ -0,0 +1,110 @@ +/** Represents a request to create or modify a Server Capability. */ +export interface RequestServerCapability { + name: string; +} + +/** + * Represents a Server Capability as it is presented by Traffic Ops in responses + * to requests made to its API to create or modify Server Capabilities. + */ +export interface RequestServerCapabilityResponse { + readonly lastUpdated: Date; + name: string; + /** + * @deprecated This field exists erroneously and will probably be removed at + * some point. + */ + // eslint-disable-next-line @typescript-eslint/naming-convention + RequestedName: string; +} + +/** + * Represents a Server Capability as it appears in responses from Traffic Ops to + * GET requests made to its `/server_capabilities` API endpoint. + */ +export interface ResponseServerCapability { + readonly lastUpdated: Date; + name: string; +} + +/** + * Represents in an arbitrary context the ability of a Server to perform some + * function. + */ +export type ServerCapability = RequestServerCapability | RequestServerCapabilityResponse | ResponseServerCapability; + +/** + * Represents a request to associate the requirement of a Server Capability with + * a Delivery Service. + */ +export interface RequestDeliveryServiceRequiredCapability { + deliveryServiceID: number; + requiredCapability: string; +} + +/** + * Represents a response from Traffic Ops to a request to associate the + * requirement of a Server Capability with a Delivery Service. + */ +export interface RequestDeliveryServiceRequiredCapabilityResponse { + deliveryServiceID: number; + readonly lastUpdated: Date; + requiredCapability: string; +} + +/** + * Represents the requirement of a Delivery Service that its assigned servers + * have a given Server Capability as they appear in responses to GET requests + * made to `/deliveryservices_required_capabilities`. + */ +export interface ResponseDeliveryServiceRequiredCapability { + deliveryServiceID: number; + readonly lastUpdated: Date; + requiredCapability: string; + xmlID: string; +} + +/** + * Represents in an arbitrary context the requirement of a Delivery Service that + * cache servers responsible for serving its content have the ability to perform + * some special function defined by a Server Capability. + */ +export type DeliveryServiceRequiredCapability = RequestDeliveryServiceRequiredCapability | RequestDeliveryServiceRequiredCapabilityResponse | ResponseDeliveryServiceRequiredCapability; + +/** + * Represents a request to associate a cache server with some Server Capability + * it ostensibly possesses. + */ +export interface RequestServerServerCapability { + serverCapability: string; + serverID: number; +} + +/** + * Represents a response from Traffic Ops to a request to associate a Server + * Capability with a cache server. + */ +export interface RequestServerServerCapabilityResponse { + readonly lastUpdated: Date; + serverCapability: string; + serverId: number; +} + +/** + * Represents an association between a cache server and a Server Capability + * which it ostensibly possesses as such associations appear in responses to GET + * requests made to the `/server_server_capabilities` endpoint of the Traffic + * Ops API. + */ +export interface ResponseServerServerCapability { + readonly lastUpdated: Date; + serverCapability: string; + serverHostName: string; + serverId: number; +} + +/** + * Represents in an arbitrary context the association between a cache server and + * a Server Capability it ostensibly possesses. + */ +export type ServerServerCapability = RequestServerServerCapability | RequestServerServerCapabilityResponse | ResponseServerServerCapability; diff --git a/src/snap.and.queue.ts b/src/snap.and.queue.ts new file mode 100644 index 0000000..45330dd --- /dev/null +++ b/src/snap.and.queue.ts @@ -0,0 +1,301 @@ +import type { LocalizationMethod } from "./cache.group"; +import type { Interface } from "./server"; + +/** + * The basic set of properties common to all requests to (de)queue updates on a + * Cache Group. + */ +interface CacheGroupQueueRequestBase { + action: "queue" | "dequeue"; +} + +/** + * A request to queue updates on a Cache Group, identifying the CDN to which to + * restrict the operation by its ID. Specifying the Name is not allowed. + */ +interface CacheGroupQueueRequestByCDNID extends CacheGroupQueueRequestBase{ + cdn?: never; + cdnId: number; +} + +/** + * A request to queue updates on a Cache Group, identifying the CDN to which to + * restrict the operation by its Name. Specifying the ID is not allowed. + */ +interface CacheGroupQueueRequestByCDNName extends CacheGroupQueueRequestBase { + cdn: string; + cdnId?: never; +} + +/** Represents a request to queue updates on a Cache Group. */ +export type CacheGroupQueueRequest = CacheGroupQueueRequestByCDNID | CacheGroupQueueRequestByCDNName; + +/** + * Represents a response from the Traffic Ops API to a request to queue updates + * on a Cache Group. + */ +export interface CacheGroupQueueResponse { + action: "queue" | "dequeue"; + cachegroupName: string; + cachegroupID: number; + cdn: string; + serverNames: Array<string>; +} + +/** Represents a request to (de)queue updates on a CDN. */ +export interface CDNQueueRequest { + action: "queue" | "dequeue"; +} + +/** + * Represents a response from Traffic Ops to a request made to its API to + * (de)queue updates on a CDN. + */ +export interface CDNQueueResponse { + action: "queue" | "dequeue"; + cdnId: number; +} + +/** + * Represents a request to (de)queue updates on a Server. + */ +export interface ServerQueueRequest { + action: "queue" | "dequeue"; +} + +/** + * Represents a response from Traffic Ops to a request made to its API to + * (de)queue updates on a server. + */ +export interface ServerQueueResponse { + action: "queue" | "dequeue"; + serverId: number; +} + +/** + * Represents a request to (de)queue updates on a Topology. + */ +export type TopologyQueueRequest = CacheGroupQueueRequestByCDNID; + +/** + * A response to a {@link TopologyQueueRequest}. + */ +export interface TopologyQueueResponse extends TopologyQueueRequest { + topology: string; +} + +/** The basic properties common to all of a Snapshot's "contentServers" */ +interface ContentServerBase { + cacheGroup: string; + capabilities: Array<string>; + fqdn: string; + hashCount: number; + hashId: string; + httpsPort: number | null; + interfaceName: string; + ip: string; + ip6: string; + locationId: string; + port: number; + profile: string; + routingDisabled: 0 | 1; + status: string; +} + +/** An edge-tier Snapshot "contentServer". */ +interface EdgeContentServer extends ContentServerBase { + deliveryServices: { + [xmlID: string]: Array<string>; + }; + type: "EDGE"; +} + +/** A mid-tier Snapshot "contentServer". */ +interface MidContentServer extends ContentServerBase { + type: "MID"; +} + +/** + * Represents a CDN Snapshot. + * + * Note that this structure is highly volatile, and in general isn't bound by + * the normal rules of API versioning. + */ +export interface Snapshot { + config: Record<string, unknown>; + contentRouters: { + [routerHostName: string]: { + "api.port": string; + "secure.api.port": string; + fqdn: string; + httpsPort: number | null; + ip: string; + ip6: string; + location: string; + port: number; + profile: string; + status: string; + }; + }; + contentServers: { + [cacheServerHostName: string]: EdgeContentServer | MidContentServer; + }; + deliveryServices: { + [xmlID: string]: { + anonymousBlockingEnabled: "true" | "false"; + consistentHashQueryParameters: Array<string>; + consistentHashRegex?: string; + coverageZoneOnly: "true" | "false"; + deepCachingType: "ALWAYS" | "NEVER"; + dispersion: { + limit: number; + shuffled: "true" | "false"; + }; + domains: Array<string>; + ecsEnabled: "true" | "false"; + geolocationProvider: string; + ip6RoutingEnabled: "true" | "false"; + matchsets: Array<{ + matchList: Array<{ + "match-type": string; + regex: string; + }>; + protocol: string; + }>; + missLocation: { + lat: number; + long: number; + }; + protocol: { + acceptHttps: "true" | "false"; + redirectToHttps: "true" | "false"; + }; + regionalGeoBlocking: "true" | "false"; + requiredCapabilities: Array<string>; + routingName: string; + soa: { + admin: string; + expire: string; + minimum: string; + refresh: string; + retry: string; + }; + sslEnabled: "true" | "false"; + topology?: string; + ttls: { + /* eslint-disable @typescript-eslint/naming-convention */ + A: string; + AAAA: string; + NS: string; + SOA: string; + /* eslint-enable @typescript-eslint/naming-convention */ + }; + }; + }; + edgeLocations: { + [name: string]: { + backupLocations: { + fallbackToClosest: "true" | "false"; + list?: Array<string>; + }; + latitude: number; + longitude: number; + localizationMethods: Array<LocalizationMethod>; + }; + }; + monitors: { + [monitorHostName: string]: { + fqdn: string; + httpsPort: number | null; + ip: string; + ip6: string; + location: string; + port: number; + profile: string; + status: string; + }; + }; + stats: { + /* eslint-disable @typescript-eslint/naming-convention */ + CDN_name: string; + date: Date; + tm_host: string; + tm_path: string; + tm_user: string; + tm_version: string; + /* eslint-enable @typescript-eslint/naming-convention */ + }; + topologies?: { + [name: string]: { + nodes: Array<string>; + }; + }; + trafficRouterLocations: { + [name: string]: { + backupLocations: { + fallbackToClosest: "true" | "false"; + list?: Array<string>; + }; + latitude: number; + localizationMethods: Array<LocalizationMethod>; + longitude: number; + }; + }; +} + +/** + * Represents a CDN "Monitoring Snapshot". + * + * Note that this structure is highly volatile, and in general isn't bound by + * the normal rules of API versioning. + */ +export interface MonitoringConfig { + cacheGroups: Array<{ + coordinates: { + latitude: number; + longitude: number; + }; + name: string; + }>; + config: Record<string, number | string | boolean>; + deliveryServices: Array<{ + hostRegexes: Array<string>; + status: string; + topology: string | null; + totalKbpsThreshold: number; + totalTpsThreshold: number; + type: string; + xmlId: string; + }>; + profiles: Array<{ + name: string; + parameters: Record<string, string | number | boolean>; + type: string; + }>; + topologies?: { + [name: string]: { + nodes: Array<string>; + }; + }; + trafficMonitors: Array<{ + cachegroup: string; + fqdn: string; + hostname: string; + ip: string; + ip6: string; + port: number; + profile: string; + status: string; + }>; + trafficServers: Array<{ + cachegroup: string; + fqdn: string; + hashid: string; + hostname: string; + interfaces: Array<Interface>; + port: number; + profile: string; + status: string; + type: string; + }>; +} diff --git a/src/ssl.ts b/src/ssl.ts new file mode 100644 index 0000000..bb1c6e6 --- /dev/null +++ b/src/ssl.ts @@ -0,0 +1,90 @@ +/** + * Represents the SSL Keys for a Delivery Service within a CDN as presented by + * Traffic Ops in its responses to requests made to its + * `/cdns/name/{{name}}/sslkeys` API endpoint. + */ +export interface CDNDeliveryServiceSSLKeys { + certificate: { + crt: string; + key: string; + }; + deliveryservice: string; +} + +/** Represents an SSL Key uploaded for a Delivery Service. */ +export interface DeliveryServiceSSLKeyUpload { + authType?: string | null; + cdn: string; + certificate: { + /** Certificate */ + crt: string; + /** Certificate Signing Request */ + csr: string; + /** Private SSL Key */ + key: string; + }; + deliveryservice: string; + hostname: string; + /** + * The XMLID of the Delivery Service that will use/is using this SSL + * certificate/key pair. + */ + key: string; + version: string; +} + +/** + * Represents a request to have Traffic Ops generate an SSL Key/Certificate pair + * for a Delivery Service. + */ +export interface DeliveryServiceSSLKeyGenerationRequest { + businessUnit?: string | null; + cdn: string; + city?: string | null; + country?: string | null; + deliveryservice: string; + hostname: string; + /** + * The XMLID of the Delivery Service for which an SSL Key/Certificate pair + * will be generated. + */ + key: string; + organization?: string | null; + state?: string | null; + version: string; +} + +/** + * Represents a request to have Traffic Ops generate an SSL Key/Certificate pair + * for a Delivery Service using LetsEncrypt (or another configured ACME + * service). + */ +export interface LetsEncryptDeliveryServiceSSLKeyGenerationRequest { + cdn: string; + deliveryservice: string; + hostname: string; + key: string; + version: string; +} + +/** + * Represents a Delivery Service's SSL Key/Certificate pair as presented by + * Traffic Ops in responses. + */ +export interface ResponseDeliveryServiceSSLKey { + certificate: { + crt: string; + key: string; + csr: string; + }; + deliveryservice: string; + cdn: string; + businessUnit?: string; + city?: string; + organization?: string; + hostname?: string; + country?: string; + state?: string; + version: string; + expiration: Date; +} diff --git a/src/steering.ts b/src/steering.ts new file mode 100644 index 0000000..662ae30 --- /dev/null +++ b/src/steering.ts @@ -0,0 +1,58 @@ +/** + * Represents all of the information necessary to route a steered Delivery + * Service. + */ +export interface SteeringConfiguration { + clientSteering: boolean; + /** + * The XMLID of the Delivery Service for which this configuration was made. + */ + deliveryService: string; + filters: Array<{ + /** The XMLID of a target Delivery Service. */ + deliveryService: string; + pattern: string; + }>; + targets: Array<{ + /** The XMLID of a target Delivery Service. */ + deliveryService: string; + order: number; + weight: number; + }>; +} + +/** + * Represents a Steering Target as Traffic Ops requires it in requests used to + * modify existing Steering Targets. + */ +export interface SteeringTargetModificationRequest { + typeId: number; + value: number; +} + +/** + * Represents a Steering Target as Traffic Ops requires it in requests used to + * create new Steering Targets. + */ +export interface SteeringTargetCreationRequest extends SteeringTargetModificationRequest { + targetId: number; +} + +/** Represents a Steering Target as Traffic Ops requires it in requests. */ +export type RequestSteeringTarget = SteeringTargetModificationRequest | SteeringTargetCreationRequest; + +/** + * Represents a Steering Target as Traffic Ops presents it in responses. + */ +export interface ResponseSteeringTarget extends SteeringTargetCreationRequest { + deliveryservice: string; + deliveryserviceId: number; + target: string; + type: string; +} + +/** + * A Steering Target is a configuration for the targeting of a specific + * downstream Delivery Service by a Steering "parent" Delivery Service. + */ +export type SteeringTarget = RequestSteeringTarget | ResponseSteeringTarget; diff --git a/src/topology.ts b/src/topology.ts new file mode 100644 index 0000000..1c99f84 --- /dev/null +++ b/src/topology.ts @@ -0,0 +1,51 @@ +/** + * Represents a Topology as Traffic Ops requires it in requests to its API. + */ +export interface RequestTopology { + description?: string | null; + name: string; + nodes: Array<{ + cachegroup: string; + parents?: Array<number> | null; + }>; +} + +/** + * Represents a Topology as it appears in responses to requests made to the + * Traffic Ops API to create or modify a Topology. + */ +export interface RequestTopologyResponse { + description: string; + readonly lastUpdated: Date; + name: string; + nodes: Array<{ + cachegroup: string; + parents: Array<number> | null; + }>; + /** + * @deprecated This field is included erroneously and will be removed in the + * future. + */ + // eslint-disable-next-line @typescript-eslint/naming-convention + RequestedName: string; +} + +/** + * Represents a Topology as it appears in responses from the Traffic Ops API to + * GET requests made to its `/topologies` endpoint. + */ +export interface ResponseTopology { + description: string; + readonly lastUpdated: Date; + name: string; + nodes: Array<{ + cachegroup: string; + parents: Array<number>; + }>; +} + +/** + * Represents in an arbitrary context a hierarchical system of groups of cache + * servers that can be used to serve Delivery Service content. + */ +export type Topology = RequestTopology | RequestTopologyResponse | ResponseTopology; diff --git a/src/uri.signing.ts b/src/uri.signing.ts new file mode 100644 index 0000000..b88709b --- /dev/null +++ b/src/uri.signing.ts @@ -0,0 +1,16 @@ +/** Represents the URL-signing keys of a Delivery Service. */ +export type DSURLKeys = Record<`key${number}`, string>; + +/** Represents the URI-signature keys of a Delivery Service. */ +export interface DSURISignatureKeys { + [issuer: string]: { + keys: Array<{ + alg: string; + kid: string; + kty: string; + k: string; + }>; + // eslint-disable-next-line @typescript-eslint/naming-convention + renewal_kid: string; + }; +};
