aws-crt

/** * Module for the configuration of MQTT5 clients to connect to AWS IoT * * @packageDocumentation */ import * as mqtt5 from "./mqtt5"; import * as io from "./io"; import * as auth from "./auth"; import * as iot_shared from "../common/aws_iot_shared"; import * as http from "./http"; export { MqttConnectCustomAuthConfig } from '../common/aws_iot_shared'; /** * Websocket-specific MQTT5 client AWS IoT configuration options * * @category IoT */ export interface WebsocketSigv4Config { /** * Sources the AWS Credentials used to sign the websocket connection handshake. If not provided, the * default credentials provider chain is used. */ credentialsProvider?: auth.AwsCredentialsProvider; /** * AWS region the websocket connection is being established in. Must match the region embedded in the * endpoint. If not provided, pattern-matching logic is used to extract the region from the endpoint. * Use this option if the pattern-matching logic has not yet been updated to handle new endpoint formats. */ region?: string; } /** * Builder pattern class to create an {@link Mqtt5ClientConfig} which can then be used to create * an {@link Mqtt5Client}, configured for use with AWS IoT. * * DEVELOPER PREVIEW DISCLAIMER * * MQTT5 support is currently in **developer preview**. We encourage feedback at all times, but feedback during the * preview window is especially valuable in shaping the final product. During the preview period we may make * backwards-incompatible changes to the public API, but in general, this is something we will try our best to avoid. * * [MQTT5 Client User Guide](https://www.github.com/awslabs/aws-crt-nodejs/blob/main/MQTT5-UserGuide.md) * * @category IoT */ export declare class AwsIotMqtt5ClientConfigBuilder { private tlsContextOptions; private static DEFAULT_WEBSOCKET_MQTT_PORT; private static DEFAULT_DIRECT_MQTT_PORT; private config; private customAuthConfig?; private constructor(); /** * Create a new MQTT5 client builder that will create MQTT5 clients that connect to AWS IoT Core via mutual TLS * using X509 certificate and key at the supplied file paths. * * @param hostName - AWS IoT endpoint to connect to * @param certPath - Path to certificate, in PEM format * @param keyPath - Path to private key, in PEM format */ static newDirectMqttBuilderWithMtlsFromPath(hostName: string, certPath: string, keyPath: string): AwsIotMqtt5ClientConfigBuilder; /** * Create a new MQTT5 client builder that will create MQTT5 clients that connect to AWS IoT Core via mutual TLS * using in-memory X509 certificate and key. * * @param hostName - AWS IoT endpoint to connect to * @param cert - Certificate, in PEM format * @param privateKey - Private key, in PEM format */ static newDirectMqttBuilderWithMtlsFromMemory(hostName: string, cert: string, privateKey: string): AwsIotMqtt5ClientConfigBuilder; /** * Create a new MQTT5 client builder that will create MQTT5 clients that connect to AWS IoT Core via mutual TLS * using a PKCS11 library for certificate and private key operations. * * NOTE: This configuration only works on Unix devices. * * @param hostName - AWS IoT endpoint to connect to * @param pkcs11Options - PKCS#11 options. */ static newDirectMqttBuilderWithMtlsFromPkcs11(hostName: string, pkcs11Options: io.TlsContextOptions.Pkcs11Options): AwsIotMqtt5ClientConfigBuilder; /** * Create a new MQTT5 client builder that will create MQTT5 clients that connect to AWS IoT Core via mutual TLS * using a certificate entry in a Windows certificate store. * * NOTE: This configuration only works on Windows devices. * * @param hostName - AWS IoT endpoint to connect to * @param certificatePath - Path to certificate in a Windows certificate store. * The path must use backslashes and end with the certificate's thumbprint. * Example: `CurrentUser\MY\A11F8A9B5DF5B98BA3508FBCA575D09570E0D2C6` */ static newDirectMqttBuilderWithMtlsFromWindowsCertStorePath(hostName: string, certificatePath: string): AwsIotMqtt5ClientConfigBuilder; /** * Create a new MQTT5 client builder that will create MQTT5 clients that connect to AWS IoT Core via TLS, * authenticating via a custom authenticator. * * @param hostName - AWS IoT endpoint to connect to * @param customAuthConfig - AWS IoT custom auth configuration */ static newDirectMqttBuilderWithCustomAuth(hostName: string, customAuthConfig: iot_shared.MqttConnectCustomAuthConfig): AwsIotMqtt5ClientConfigBuilder; /** * Create a new MQTT5 client builder that will create MQTT5 clients that connect to AWS IoT Core via websockets, * using AWS Sigv4 signing to establish authenticate. * * @param hostName - AWS IoT endpoint to connect to * @param options - additional sigv4-oriented options to use */ static newWebsocketMqttBuilderWithSigv4Auth(hostName: string, options?: WebsocketSigv4Config): AwsIotMqtt5ClientConfigBuilder; /** * Create a new MQTT5 client builder that will create MQTT5 clients that connect to AWS IoT Core via websockets, * authenticating via a custom authenticator. * * @param hostName - AWS IoT endpoint to connect to * @param customAuthConfig - AWS IoT custom auth configuration */ static newWebsocketMqttBuilderWithCustomAuth(hostName: string, customAuthConfig: iot_shared.MqttConnectCustomAuthConfig): AwsIotMqtt5ClientConfigBuilder; /** * Overrides the default system trust store. * * @param caDirpath - Only used on Unix-style systems where all trust anchors are * stored in a directory (e.g. /etc/ssl/certs). * @param caFilepath - Single file containing all trust CAs, in PEM format */ withCertificateAuthorityFromPath(caDirpath?: string, caFilepath?: string): AwsIotMqtt5ClientConfigBuilder; /** * Overrides the default system trust store. * * @param ca - Buffer containing all trust CAs, in PEM format */ withCertificateAuthority(ca: string): AwsIotMqtt5ClientConfigBuilder; /** * Overrides the IoT endpoint port to connect to. * * @param port The IoT endpoint port to connect to. Usually 8883 for MQTT, or 443 for websockets */ withPort(port: number): AwsIotMqtt5ClientConfigBuilder; /** * Overrides all configurable options with respect to the CONNECT packet sent by the client, including the will. * These connect properties will be used for every connection attempt made by the client. Custom authentication * configuration will override the username and password values in this configuration. * * @param connectPacket all configurable options with respect to the CONNECT packet sent by the client */ withConnectProperties(connectPacket: mqtt5.ConnectPacket): AwsIotMqtt5ClientConfigBuilder; /** * Overrides how the MQTT5 client should behave with respect to MQTT sessions. * * @param sessionBehavior how the MQTT5 client should behave with respect to MQTT sessions. */ withSessionBehavior(sessionBehavior: mqtt5.ClientSessionBehavior): AwsIotMqtt5ClientConfigBuilder; /** * Overrides how the reconnect delay is modified in order to smooth out the distribution of reconnection attempt * timepoints for a large set of reconnecting clients. * * @param retryJitterMode controls how the reconnect delay is modified in order to smooth out the distribution of * econnection attempt timepoints for a large set of reconnecting clients. */ withRetryJitterMode(retryJitterMode: mqtt5.RetryJitterType): AwsIotMqtt5ClientConfigBuilder; /** * Overrides the minimum amount of time to wait to reconnect after a disconnect. Exponential backoff is performed * with controllable jitter after each connection failure. * * @param minReconnectDelayMs minimum amount of time to wait to reconnect after a disconnect. */ withMinReconnectDelayMs(minReconnectDelayMs?: number): AwsIotMqtt5ClientConfigBuilder; /** * Overrides the maximum amount of time to wait to reconnect after a disconnect. Exponential backoff is performed * with controllable jitter after each connection failure. * * @param maxReconnectDelayMs maximum amount of time to wait to reconnect after a disconnect. */ withMaxReconnectDelayMs(maxReconnectDelayMs?: number): AwsIotMqtt5ClientConfigBuilder; /** * Overrides the amount of time that must elapse with an established connection before the reconnect delay is * reset to the minimum. This helps alleviate bandwidth-waste in fast reconnect cycles due to permission * failures on operations. * * @param minConnectedTimeToResetReconnectDelayMs the amount of time that must elapse with an established * connection before the reconnect delay is reset to the minimum */ withMinConnectedTimeToResetReconnectDelayMs(minConnectedTimeToResetReconnectDelayMs?: number): AwsIotMqtt5ClientConfigBuilder; /** * Overrides the time interval to wait after sending a CONNECT request for a CONNACK to arrive. If one does not * arrive, the connection will be shut down. * * @param connackTimeoutMs time interval to wait after sending a CONNECT request for a CONNACK to arrive */ withConnackTimeoutMs(connackTimeoutMs?: number): AwsIotMqtt5ClientConfigBuilder; /** * Overrides how disconnects affect the queued and in-progress operations tracked by the client. Also controls * how new operations are handled while the client is not connected. In particular, if the client is not connected, * then any operation that would be failed on disconnect (according to these rules) will also be rejected. * * @param offlineQueueBehavior how disconnects affect the queued and in-progress operations tracked by the client * * @group Node-only */ withOfflineQueueBehavior(offlineQueueBehavior: mqtt5.ClientOperationQueueBehavior): AwsIotMqtt5ClientConfigBuilder; /** * Overrides the time interval to wait after sending a PINGREQ for a PINGRESP to arrive. If one does not arrive, * the client will close the current connection. * * @param pingTimeoutMs time interval to wait after sending a PINGREQ for a PINGRESP to arrive * * @group Node-only */ withPingTimeoutMs(pingTimeoutMs?: number): AwsIotMqtt5ClientConfigBuilder; /** * Overrides the time interval to wait for an ack after sending a QoS 1+ PUBLISH, SUBSCRIBE, or UNSUBSCRIBE before * failing the operation. Defaults to no timeout. * * @param ackTimeoutSeconds the time interval to wait for an ack after sending a QoS 1+ PUBLISH, SUBSCRIBE, * or UNSUBSCRIBE before failing the operation * * @group Node-only */ withAckTimeoutSeconds(ackTimeoutSeconds?: number): AwsIotMqtt5ClientConfigBuilder; /** * Overrides the socket properties of the underlying MQTT connections made by the client. Leave undefined to use * defaults (no TCP keep alive, 10 second socket timeout). * * @param socketOptions socket properties of the underlying MQTT connections made by the client * * @group Node-only */ withSocketOptions(socketOptions: io.SocketOptions): AwsIotMqtt5ClientConfigBuilder; /** * Overrides (tunneling) HTTP proxy usage when establishing MQTT connections. * * @param httpProxyOptions HTTP proxy options to use when establishing MQTT connections * * @group Node-only */ withHttpProxyOptions(httpProxyOptions: http.HttpProxyOptions): AwsIotMqtt5ClientConfigBuilder; /** * Overrides additional controls for client behavior with respect to operation validation and flow control; these * checks go beyond the base MQTT5 spec to respect limits of specific MQTT brokers. * * @param extendedValidationAndFlowControlOptions additional controls for client behavior with respect to operation * validation and flow control * * @group Node-only */ withExtendedValidationAndFlowControlOptions(extendedValidationAndFlowControlOptions: mqtt5.ClientExtendedValidationAndFlowControl): AwsIotMqtt5ClientConfigBuilder; /** * Constructs an MQTT5 Client configuration object for creating mqtt5 clients. */ build(): mqtt5.Mqtt5ClientConfig; }