@azure/web-pubsub-express 1.0.6-alpha.20240927.1 → 1.0.6-alpha.20241001.2

package/dist/web-pubsub-express.d.ts

@@ -20,10 +20,28 @@ export declare interface ConnectedRequest {
     context: ConnectionContext;
 }
 
+/**
+ * Response of a failed connect event.
+ */
+export declare interface ConnectErrorResponse {
+    /**
+     * The error code.
+     */
+    code: 400 | 401 | 500;
+    /**
+     * The error detail.
+     */
+    detail?: string;
+}
+
 /**
  * The connection context representing the client WebSocket connection.
  */
 export declare interface ConnectionContext {
+    /**
+     * The unique identifier generated by the service of the network connection.
+     */
+    signature: string;
     /**
      * The hub the connection belongs to.
      */
@@ -52,6 +70,14 @@ export declare interface ConnectionContext {
      * Get the additional states for the connection, such states are perserved throughout the lifetime of the connection.
      */
     states: Record<string, any>;
+    /**
+     * The type of client protocol.
+     */
+    clientProtocol: WebPubSubClientProtocol;
+    /**
+     * The MQTT properties that the client WebSocket connection has when it connects (For MQTT connection only).
+     */
+    mqtt?: MqttConnectionContextProperties;
 }
 
 /**
@@ -125,13 +151,18 @@ export declare interface ConnectResponseHandler {
      * Return success response to the service.
      * @param response - The response for the connect event.
      */
-    success(response?: ConnectResponse): void;
+    success(response?: ConnectResponse | MqttConnectResponse): void;
     /**
      * Return failed response and the service will reject the client WebSocket connection.
      * @param code - Code can be 400 user error, 401 unauthorized and 500 server error.
      * @param detail - The detail of the error.
      */
     fail(code: 400 | 401 | 500, detail?: string): void;
+    /**
+     * Return failed response with MQTT response properties and the service will reject the client WebSocket connection.
+     * @param response - The response for the connect event which contains either default WebPubSub or MQTT response properties.
+     */
+    failWith(response: ConnectErrorResponse | MqttConnectErrorResponse): void;
 }
 
 /**
@@ -148,6 +179,476 @@ export declare interface DisconnectedRequest {
     reason?: string;
 }
 
+/**
+ * Response of an MQTT connection failure.
+ */
+export declare interface MqttConnectErrorResponse {
+    /**
+     * The properties of the MQTT connection failure response.
+     */
+    mqtt: MqttConnectErrorResponseProperties;
+}
+
+/**
+ * The properties of an MQTT connection failure response.
+ */
+export declare interface MqttConnectErrorResponseProperties {
+    /**
+     * The MQTT connect return code.
+     */
+    code: MqttV311ConnectReturnCode | MqttV500ConnectReasonCode;
+    /**
+     * The reason string for the connection failure.
+     */
+    reason?: string;
+    /**
+     * The user properties in the response.
+     */
+    userProperties?: MqttUserProperty[];
+}
+
+/**
+ * The connection context properties representing the MQTT client WebSocket connection.
+ */
+export declare interface MqttConnectionContextProperties {
+    /**
+     * The unique identifier generated by the service of the network connection.
+     */
+    physicalConnectionId: string;
+    /**
+     * The unique identifier generated by the service of the MQTT session.
+     */
+    sessionId?: string;
+}
+
+/**
+ * The properties of the MQTT CONNECT packet.
+ */
+export declare interface MqttConnectProperties {
+    /**
+     * MQTT protocol version.
+     */
+    protocolVersion: number;
+    /**
+     * The username field in the MQTT CONNECT packet.
+     */
+    username?: string;
+    /**
+     * The password field in the MQTT CONNECT packet.
+     */
+    password?: string;
+    /**
+     * The user properties in the MQTT CONNECT packet.
+     */
+    userProperties?: MqttUserProperty[];
+}
+
+/**
+ * Request for the MQTT connect event.
+ */
+export declare interface MqttConnectRequest extends ConnectRequest {
+    /**
+     * The MQTT specific properties in the MQTT connect event request.
+     */
+    mqtt: MqttConnectProperties;
+}
+
+/**
+ * Success respones of the connect event.
+ */
+export declare interface MqttConnectResponse extends ConnectResponse {
+    /**
+     * The MQTT specific properties in a successful MQTT connection event response.
+     */
+    mqtt?: MqttConnectResponseProperties;
+}
+
+/**
+ * The properties of a successful MQTT connection event response
+ */
+export declare interface MqttConnectResponseProperties {
+    /**
+     * Additional diagnostic or other information provided by upstream server
+     * Now only MQTT 5.0 supports user properties
+     */
+    userProperties?: MqttUserProperty[];
+}
+
+/**
+ * The properties of an MQTT disconnected event.
+ */
+export declare interface MqttDisconnectedProperties {
+    /**
+     * The MQTT disconnect packet.
+     */
+    disconnectPacket: MqttDisconnectPacket;
+    /**
+     * Whether the disconnection is initiated by the client.
+     */
+    initiatedByClient: boolean;
+}
+
+/**
+ * Request for the disconnected event.
+ */
+export declare interface MqttDisconnectedRequest extends DisconnectedRequest {
+    /**
+     * The MQTT specific properties in the MQTT disconnected event request.
+     */
+    mqtt: MqttDisconnectedProperties;
+}
+
+/**
+ * The properties of the MQTT DISCONNECT packet.
+ */
+export declare interface MqttDisconnectPacket {
+    /**
+     * The MQTT disconnect return code.
+     */
+    code: MqttDisconnectReasonCode;
+    /**
+     * The user properties in the MQTT disconnect packet.
+     */
+    userProperties?: MqttUserProperty[];
+}
+
+/**
+ * MQTT 5.0 Disconnect Reason Codes.
+ */
+export declare enum MqttDisconnectReasonCode {
+    /**
+     * 0x00 - Normal disconnection
+     * Sent by: Client or Server
+     * Description: Close the connection normally. Do not send the Will Message.
+     */
+    NormalDisconnection = 0,
+    /**
+     * 0x04 - Disconnect with Will Message
+     * Sent by: Client
+     * Description: The Client wishes to disconnect but requires that the Server also publishes its Will Message.
+     */
+    DisconnectWithWillMessage = 4,
+    /**
+     * 0x80 - Unspecified error
+     * Sent by: Client or Server
+     * Description: The Connection is closed but the sender either does not wish to reveal the reason, or none of the other Reason Codes apply.
+     */
+    UnspecifiedError = 128,
+    /**
+     * 0x81 - Malformed Packet
+     * Sent by: Client or Server
+     * Description: The received packet does not conform to this specification.
+     */
+    MalformedPacket = 129,
+    /**
+     * 0x82 - Protocol Error
+     * Sent by: Client or Server
+     * Description: An unexpected or out of order packet was received.
+     */
+    ProtocolError = 130,
+    /**
+     * 0x83 - Implementation specific error
+     * Sent by: Client or Server
+     * Description: The packet received is valid but cannot be processed by this implementation.
+     */
+    ImplementationSpecificError = 131,
+    /**
+     * 0x87 - Not authorized
+     * Sent by: Server
+     * Description: The request is not authorized.
+     */
+    NotAuthorized = 135,
+    /**
+     * 0x89 - Server busy
+     * Sent by: Server
+     * Description: The Server is busy and cannot continue processing requests from this Client.
+     */
+    ServerBusy = 137,
+    /**
+     * 0x8B - Server shutting down
+     * Sent by: Server
+     * Description: The Server is shutting down.
+     */
+    ServerShuttingDown = 139,
+    /**
+     * 0x8D - Keep Alive timeout
+     * Sent by: Server
+     * Description: The Connection is closed because no packet has been received for 1.5 times the Keepalive time.
+     */
+    KeepAliveTimeout = 141,
+    /**
+     * 0x8E - Session taken over
+     * Sent by: Server
+     * Description: Another Connection using the same ClientID has connected causing this Connection to be closed.
+     */
+    SessionTakenOver = 142,
+    /**
+     * 0x8F - Topic Filter invalid
+     * Sent by: Server
+     * Description: The Topic Filter is correctly formed, but is not accepted by this Server.
+     */
+    TopicFilterInvalid = 143,
+    /**
+     * 0x90 - Topic Name invalid
+     * Sent by: Client or Server
+     * Description: The Topic Name is correctly formed, but is not accepted by this Client or Server.
+     */
+    TopicNameInvalid = 144,
+    /**
+     * 0x93 - Receive Maximum exceeded
+     * Sent by: Client or Server
+     * Description: The Client or Server has received more than Receive Maximum publication for which it has not sent PUBACK or PUBCOMP.
+     */
+    ReceiveMaximumExceeded = 147,
+    /**
+     * 0x94 - Topic Alias invalid
+     * Sent by: Client or Server
+     * Description: The Client or Server has received a PUBLISH packet containing a Topic Alias which is greater than the Maximum Topic Alias it sent in the CONNECT or CONNACK packet.
+     */
+    TopicAliasInvalid = 148,
+    /**
+     * 0x95 - Packet too large
+     * Sent by: Client or Server
+     * Description: The packet size is greater than Maximum Packet Size for this Client or Server.
+     */
+    PacketTooLarge = 149,
+    /**
+     * 0x96 - Message rate too high
+     * Sent by: Client or Server
+     * Description: The received data rate is too high.
+     */
+    MessageRateTooHigh = 150,
+    /**
+     * 0x97 - Quota exceeded
+     * Sent by: Client or Server
+     * Description: An implementation or administrative imposed limit has been exceeded.
+     */
+    QuotaExceeded = 151,
+    /**
+     * 0x98 - Administrative action
+     * Sent by: Client or Server
+     * Description: The Connection is closed due to an administrative action.
+     */
+    AdministrativeAction = 152,
+    /**
+     * 0x99 - Payload format invalid
+     * Sent by: Client or Server
+     * Description: The payload format does not match the one specified by the Payload Format Indicator.
+     */
+    PayloadFormatInvalid = 153,
+    /**
+     * 0x9A - Retain not supported
+     * Sent by: Server
+     * Description: The Server does not support retained messages.
+     */
+    RetainNotSupported = 154,
+    /**
+     * 0x9B - QoS not supported
+     * Sent by: Server
+     * Description: The Client specified a QoS greater than the QoS specified in a Maximum QoS in the CONNACK.
+     */
+    QosNotSupported = 155,
+    /**
+     * 0x9C - Use another server
+     * Sent by: Server
+     * Description: The Client should temporarily change its Server.
+     */
+    UseAnotherServer = 156,
+    /**
+     * 0x9D - Server moved
+     * Sent by: Server
+     * Description: The Server is moved and the Client should permanently change its server location.
+     */
+    ServerMoved = 157,
+    /**
+     * 0x9E - Shared Subscriptions not supported
+     * Sent by: Server
+     * Description: The Server does not support Shared Subscriptions.
+     */
+    SharedSubscriptionsNotSupported = 158,
+    /**
+     * 0x9F - Connection rate exceeded
+     * Sent by: Server
+     * Description: This connection is closed because the connection rate is too high.
+     */
+    ConnectionRateExceeded = 159,
+    /**
+     * 0xA0 - Maximum connect time
+     * Sent by: Server
+     * Description: The maximum connection time authorized for this connection has been exceeded.
+     */
+    MaximumConnectTime = 160,
+    /**
+     * 0xA1 - Subscription Identifiers not supported
+     * Sent by: Server
+     * Description: The Server does not support Subscription Identifiers; the subscription is not accepted.
+     */
+    SubscriptionIdentifiersNotSupported = 161,
+    /**
+     * 0xA2 - Wildcard Subscriptions not supported
+     * Sent by: Server
+     * Description: The Server does not support Wildcard Subscriptions; the subscription is not accepted.
+     */
+    WildcardSubscriptionsNotSupported = 162
+}
+
+/**
+ * The properties of a user in MQTT.
+ */
+export declare interface MqttUserProperty {
+    /**
+     * The name of the property.
+     */
+    name: string;
+    /**
+     * The value of the property.
+     */
+    value: string;
+}
+
+/**
+ * MQTT 3.1.1 Connect Return Codes.
+ */
+export declare enum MqttV311ConnectReturnCode {
+    /**
+     * 0x01: Connection refused, unacceptable protocol version
+     * The Server does not support the level of the MQTT protocol requested by the Client.
+     */
+    UnacceptableProtocolVersion = 1,
+    /**
+     * 0x02: Connection refused, identifier rejected
+     * The Client identifier is correct UTF-8 but not allowed by the Server.
+     */
+    IdentifierRejected = 2,
+    /**
+     * 0x03: Connection refused, server unavailable
+     * The Network Connection has been made but the MQTT service is unavailable.
+     */
+    ServerUnavailable = 3,
+    /**
+     * 0x04: Connection refused, bad user name or password
+     * The data in the user name or password is malformed.
+     */
+    BadUsernameOrPassword = 4,
+    /**
+     * 0x05: Connection refused, not authorized
+     * The Client is not authorized to connect.
+     */
+    NotAuthorized = 5
+}
+
+/**
+ * MQTT Connect Reason Codes
+ * These codes represent the reasons for the outcome of an MQTT CONNECT packet as per MQTT 5.0 specification.
+ */
+export declare enum MqttV500ConnectReasonCode {
+    /**
+     * 0x80 - Unspecified error
+     * Description: The Server does not wish to reveal the reason for the failure, or none of the other Reason Codes apply.
+     */
+    UnspecifiedError = 128,
+    /**
+     * 0x81 - Malformed Packet
+     * Description: Data within the CONNECT packet could not be correctly parsed.
+     */
+    MalformedPacket = 129,
+    /**
+     * 0x82 - Protocol Error
+     * Description: Data in the CONNECT packet does not conform to this specification.
+     */
+    ProtocolError = 130,
+    /**
+     * 0x83 - Implementation specific error
+     * Description: The CONNECT is valid but is not accepted by this Server.
+     */
+    ImplementationSpecificError = 131,
+    /**
+     * 0x84 - Unsupported Protocol Version
+     * Description: The Server does not support the version of the MQTT protocol requested by the Client.
+     */
+    UnsupportedProtocolVersion = 132,
+    /**
+     * 0x85 - Client Identifier not valid
+     * Description: The Client Identifier is a valid string but is not allowed by the Server.
+     */
+    ClientIdentifierNotValid = 133,
+    /**
+     * 0x86 - Bad User Name or Password
+     * Description: The Server does not accept the User Name or Password specified by the Client.
+     */
+    BadUserNameOrPassword = 134,
+    /**
+     * 0x87 - Not authorized
+     * Description: The Client is not authorized to connect.
+     */
+    NotAuthorized = 135,
+    /**
+     * 0x88 - Server unavailable
+     * Description: The MQTT Server is not available.
+     */
+    ServerUnavailable = 136,
+    /**
+     * 0x89 - Server busy
+     * Description: The Server is busy. Try again later.
+     */
+    ServerBusy = 137,
+    /**
+     * 0x8A - Banned
+     * Description: This Client has been banned by administrative action. Contact the server administrator.
+     */
+    Banned = 138,
+    /**
+     * 0x8C - Bad authentication method
+     * Description: The authentication method is not supported or does not match the authentication method currently in use.
+     */
+    BadAuthenticationMethod = 140,
+    /**
+     * 0x90 - Topic Name invalid
+     * Description: The Will Topic Name is not malformed, but is not accepted by this Server.
+     */
+    TopicNameInvalid = 144,
+    /**
+     * 0x95 - Packet too large
+     * Description: The CONNECT packet exceeded the maximum permissible size.
+     */
+    PacketTooLarge = 149,
+    /**
+     * 0x97 - Quota exceeded
+     * Description: An implementation or administrative imposed limit has been exceeded.
+     */
+    QuotaExceeded = 151,
+    /**
+     * 0x99 - Payload format invalid
+     * Description: The Will Payload does not match the specified Payload Format Indicator.
+     */
+    PayloadFormatInvalid = 153,
+    /**
+     * 0x9A - Retain not supported
+     * Description: The Server does not support retained messages, and Will Retain was set to 1.
+     */
+    RetainNotSupported = 154,
+    /**
+     * 0x9B - QoS not supported
+     * Description: The Server does not support the QoS set in Will QoS.
+     */
+    QosNotSupported = 155,
+    /**
+     * 0x9C - Use another server
+     * Description: The Client should temporarily use another server.
+     */
+    UseAnotherServer = 156,
+    /**
+     * 0x9D - Server moved
+     * Description: The Client should permanently use another server.
+     */
+    ServerMoved = 157,
+    /**
+     * 0x9F - Connection rate exceeded
+     * Description: The connection rate limit has been exceeded.
+     */
+    ConnectionRateExceeded = 159
+}
+
 /**
  * Request for the user event.
  */
@@ -216,6 +717,11 @@ export declare interface UserEventResponseHandler {
     fail(code: 400 | 401 | 500, detail?: string): void;
 }
 
+/**
+ * The protocol of Web PubSub Client.
+ */
+export declare type WebPubSubClientProtocol = "default" | "mqtt";
+
 /**
  * The handler to handle incoming CloudEvents messages
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@azure/web-pubsub-express",
-  "version": "1.0.6-alpha.20240927.1",
+  "version": "1.0.6-alpha.20241001.2",
   "description": "Azure Web PubSub CloudEvents handlers",
   "sdk-type": "client",
   "scripts": {