Class Context
Index
Constructors
constructor
- new Context(
options?: {
blocky?: boolean;
ioThreads?: number;
ipv6?: boolean;
maxMessageSize?: number;
maxSockets?: number;
threadPriority?: number;
threadSchedulingPolicy?: number;
},
): Context Creates a new ØMQ context and sets any provided context options. Sockets need to be explicitly associated with a new context during construction.
Parameters
Optionaloptions: {
blocky?: boolean;
ioThreads?: number;
ipv6?: boolean;
maxMessageSize?: number;
maxSockets?: number;
threadPriority?: number;
threadSchedulingPolicy?: number;
}An optional object with options that will be set on the context during creation.
Optionalblocky?: booleanZMQ_BLOCKY
By default the context will block forever when closed at process exit. The assumption behind this behavior is that abrupt termination will cause message loss. Most real applications use some form of handshaking to ensure applications receive termination messages, and then terminate the context with Socket.linger set to zero on all sockets. This setting is an easier way to get the same result. When blocky is set to
false, all new sockets are given a linger timeout of zero. You must still close all sockets before exiting.OptionalioThreads?: numberZMQ_IO_THREADS
Size of the ØMQ thread pool to handle I/O operations. If your application is using only the
inproctransport for messaging you may set this to zero, otherwise set it to at least one (default).Optionalipv6?: booleanZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, a socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
OptionalmaxMessageSize?: numberZMQ_MAX_MSGSZ
Maximum allowed size of a message sent in the context.
OptionalmaxSockets?: numberZMQ_MAX_SOCKETS
Maximum number of sockets allowed on the context.
OptionalthreadPriority?: numberZMQ_THREAD_PRIORITY
Scheduling priority for internal context's thread pool. This option is not available on Windows. Supported values for this option depend on chosen scheduling policy. Details can be found at http://man7.org/linux/man-pages/man2/sched_setscheduler.2.html. This option only applies before creating any sockets on the context.
OptionalthreadSchedulingPolicy?: numberZMQ_THREAD_SCHED_POLICY
Scheduling policy for internal context's thread pool. This option is not available on Windows. Supported values for this option can be found at http://man7.org/linux/man-pages/man2/sched_setscheduler.2.html. This option only applies before creating any sockets on the context.
Returns Context
Properties
blocky
ZMQ_BLOCKY
By default the context will block forever when closed at process exit. The assumption behind this behavior is that abrupt termination will cause message loss. Most real applications use some form of handshaking to ensure applications receive termination messages, and then terminate the context with Socket.linger set to zero on all sockets. This setting is an easier way to get the same result. When blocky is set to false, all new sockets are given a linger timeout of zero. You must still close all sockets before exiting.
ioThreads
ZMQ_IO_THREADS
Size of the ØMQ thread pool to handle I/O operations. If your application is using only the inproc transport for messaging you may set this to zero, otherwise set it to at least one (default).
ipv6
ZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, a socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
maxMessageSize
ZMQ_MAX_MSGSZ
Maximum allowed size of a message sent in the context.
maxSockets
ZMQ_MAX_SOCKETS
Maximum number of sockets allowed on the context.
ReadonlymaxSocketsLimit
ZMQ_SOCKET_LIMIT
Largest number of sockets that can be set with maxSockets.
threadPriority
ZMQ_THREAD_PRIORITY
Scheduling priority for internal context's thread pool. This option is not available on Windows. Supported values for this option depend on chosen scheduling policy. Details can be found at http://man7.org/linux/man-pages/man2/sched_setscheduler.2.html. This option only applies before creating any sockets on the context.
threadSchedulingPolicy
ZMQ_THREAD_SCHED_POLICY
Scheduling policy for internal context's thread pool. This option is not available on Windows. Supported values for this option can be found at http://man7.org/linux/man-pages/man2/sched_setscheduler.2.html. This option only applies before creating any sockets on the context.
Class Dealer
A Dealer socket can be used to extend request/reply sockets. Each message sent is round-robined among all connected peers, and each message received is fair-queued from all connected peers.
When a Dealer socket enters the mute state due to having reached the high water mark for all peers, or if there are no peers at all, then any Writable.send() operations on the socket shall block until the mute state ends or at least one peer becomes available for sending; messages are not discarded.
When a Dealer is connected to a Reply socket, each message sent must consist of an empty message part, the delimiter, followed by one or more body parts.
Hierarchy (view full)
Index
Constructors
Properties
Methods
Constructors
constructor
- new
Dealer (options?): Dealer Parameters
Optionaloptions: {
affinity?: number;
backlog?: number;
conflate?: boolean;
connectTimeout?: number;
context?: Context;
curvePublicKey?: null | string;
curveSecretKey?: null | string;
curveServer?: boolean;
curveServerKey?: null | string;
gssapiPlainText?: boolean;
gssapiPrincipal?: null | string;
gssapiPrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
gssapiServer?: boolean;
gssapiServicePrincipal?: null | string;
gssapiServicePrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
handshakeInterval?: number;
heartbeatInterval?: number;
heartbeatTimeout?: number;
heartbeatTimeToLive?: number;
immediate?: boolean;
interface?: null | string;
ipv6?: boolean;
linger?: number;
loopbackFastPath?: boolean;
maxMessageSize?: number;
multicastHops?: number;
multicastMaxTransportDataUnit?: number;
plainPassword?: null | string;
plainServer?: boolean;
plainUsername?: null | string;
probeRouter?: boolean;
rate?: number;
receiveBufferSize?: number;
receiveHighWaterMark?: number;
receiveTimeout?: number;
reconnectInterval?: number;
reconnectMaxInterval?: number;
recoveryInterval?: number;
routingId?: null | string;
sendBufferSize?: number;
sendHighWaterMark?: number;
sendTimeout?: number;
socksProxy?: null | string;
tcpAcceptFilter?: null | string;
tcpKeepalive?: number;
tcpKeepaliveCount?: number;
tcpKeepaliveIdle?: number;
tcpKeepaliveInterval?: number;
tcpMaxRetransmitTimeout?: number;
typeOfService?: number;
vmciBufferMaxSize?: number;
vmciBufferMinSize?: number;
vmciBufferSize?: number;
vmciConnectTimeout?: number;
zapDomain?: null | string;
zapEnforceDomain?: boolean;
}Optionalaffinity?: numberZMQ_AFFINITY
I/O thread affinity, which determines which threads from the ØMQ I/O thread pool associated with the socket's context shall handle newly created connections.
Note: This value is a bit mask, but values higher than
Number.MAX_SAFE_INTEGERmay not be represented accurately! This currently means that configurations beyond 52 threads are unreliable.Optionalbacklog?: numberZMQ_BACKLOG
Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.
Optionalconflate?: booleanZMQ_CONFLATE
If set to
true, a socket shall keep only one message in its inbound/outbound queue: the last message to be received/sent. Ignores any high water mark options. Does not support multi-part messages - in particular, only one part of it is kept in the socket internal queue.OptionalconnectTimeout ?: numberZMQ_CONNECT_TIMEOUT
Sets how long to wait before timing-out a connect() system call. The connect() system call normally takes a long time before it returns a time out error. Setting this option allows the library to time out the call at an earlier interval.
Optionalcontext?: ContextOptionalcurvePublic ?: null | stringKey ZMQ_CURVE_PUBLICKEY
Sets the socket's long term public key. You must set this on CURVE client sockets. A server socket does not need to know its own public key. You can create a new keypair with curveKeyPair().
OptionalcurveSecret ?: null | stringKey ZMQ_CURVE_SECRETKEY
Sets the socket's long term secret key. You must set this on both CURVE client and server sockets. You can create a new keypair with curveKeyPair().
OptionalcurveServer ?: booleanZMQ_CURVE_SERVER
Defines whether the socket will act as server for CURVE security. A value of
truemeans the socket will act as CURVE server. A value offalsemeans the socket will not act as CURVE server, and its security role then depends on other option settings.OptionalcurveServer ?: null | stringKey ZMQ_CURVE_SERVERKEY
Sets the socket's long term server key. This is the public key of the CURVE server socket. You must set this on CURVE client sockets. This key must have been generated together with the server's secret key. You can create a new keypair with curveKeyPair().
OptionalgssapiPlain ?: booleanText OptionalgssapiPrincipal ?: null | stringOptionalgssapiPrincipal ?: "hostBased" | "userName" | "krb5Principal"Name Type OptionalgssapiServer ?: booleanOptionalgssapiService ?: null | stringPrincipal OptionalgssapiService ?: "hostBased" | "userName" | "krb5Principal"Principal Name Type OptionalhandshakeInterval ?: numberZMQ_HANDSHAKE_IVL
Handshaking is the exchange of socket configuration information (socket type, identity, security) that occurs when a connection is first opened (only for connection-oriented transports). If handshaking does not complete within the configured time, the connection shall be closed. The value 0 means no handshake time limit.
OptionalheartbeatInterval ?: numberZMQ_HEARTBEAT_IVL
Interval in milliseconds between sending ZMTP heartbeats for the specified socket. If this option is greater than 0, then a PING ZMTP command will be sent after every interval.
OptionalheartbeatTimeout ?: numberZMQ_HEARTBEAT_TIMEOUT
How long (in milliseconds) to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic. This option is only valid if heartbeatInterval is greater than 0. The connection will time out if there is no traffic received after sending the PING command. The received traffic does not have to be a PONG command - any received traffic will cancel the timeout.
OptionalheartbeatTime ?: numberTo Live ZMQ_HEARTBEAT_TTL
The timeout in milliseconds on the remote peer for ZMTP heartbeats. If this option is greater than 0, the remote side shall time out the connection if it does not receive any more traffic within the TTL period. This option does not have any effect if heartbeatInterval is 0. Internally, this value is rounded down to the nearest decisecond, any value less than 100 will have no effect.
Optionalimmediate?: booleanZMQ_IMMEDIATE
By default queues will fill on outgoing connections even if the connection has not completed. This can lead to "lost" messages on sockets with round-robin routing (Request, Push, Dealer). If this option is set to
true, messages shall be queued only to completed connections. This will cause the socket to block if there are no other connections, but will prevent queues from filling on pipes awaiting connection.Optionalinterface?: null | stringZMQ_BINDTODEVICE
Binds the socket to the given network interface (Linux only). Allows to use Linux VRF, see: https://www.kernel.org/doc/Documentation/networking/vrf.txt. Requires the program to be ran as root or with
CAP_NET_RAW.Optionalipv6?: booleanZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
Optionallinger?: numberZMQ_LINGER
Determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with close().
OptionalloopbackFast ?: booleanPath ZMQ_LOOPBACK_FASTPATH
Enable faster TCP connections on loopback devices. An application can enable this option to reduce the latency and improve the performance of loopback operations on a TCP socket on Windows.
OptionalmaxMessage ?: numberSize ZMQ_MAXMSGSIZE
Limits the size of the inbound message. If a peer sends a message larger than the limit it is disconnected. Value of -1 means no limit.
OptionalmulticastHops ?: numberZMQ_MULTICAST_HOPS
Sets the time-to-live field in every multicast packet sent from this socket. The default is 1 which means that the multicast packets don't leave the local network.
OptionalmulticastMax ?: numberTransport Data Unit ZMQ_MULTICAST_MAXTPDU
Sets the maximum transport data unit size used for outbound multicast packets. This must be set at or below the minimum Maximum Transmission Unit (MTU) for all network paths over which multicast reception is required.
OptionalplainPassword ?: null | stringZMQ_PLAIN_PASSWORD
Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
OptionalplainServer ?: booleanZMQ_PLAIN_SERVER
Defines whether the socket will act as server for PLAIN security. A value of
truemeans the socket will act as PLAIN server. A value offalsemeans the socket will not act as PLAIN server, and its security role then depends on other option settings.OptionalplainUsername ?: null | stringZMQ_PLAIN_USERNAME
Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
OptionalprobeRouter ?: booleanZMQ_PROBE_ROUTER
When set to
true, the socket will automatically send an empty message when a new connection is made or accepted. You may set this on sockets connected to a Router socket. The application must filter such empty messages. This option provides the Router with an event signaling the arrival of a new peer.Warning:* Do not set this option on a socket that talks to any other socket type except Router: the results are undefined.
Optionalrate?: numberZMQ_RATE
Maximum send or receive data rate for multicast transports such as
pgm.OptionalreceiveBuffer ?: numberSize ZMQ_RCVBUF
Underlying kernel receive buffer size in bytes. A value of -1 means leave the OS default unchanged.
OptionalreceiveHigh ?: numberWater Mark ZMQ_RCVHWM
The high water mark is a hard limit on the maximum number of incoming messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
OptionalreceiveTimeout ?: numberZMQ_RCVTIMEO
Sets the timeout receiving messages on the socket. If the value is 0, receive() will return a rejected promise immediately if there is no message to receive. If the value is -1, it will wait asynchronously until a message is available. For all other values, it will wait for a message for that amount of time before rejecting.
OptionalreconnectInterval ?: numberZMQ_RECONNECT_IVL
Period ØMQ shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. The value -1 means no reconnection.
OptionalreconnectMax ?: numberInterval ZMQ_RECONNECT_IVL_MAX
Maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled until reconnectMaxInterval is reached. This allows for exponential backoff strategy. Zero (the default) means no exponential backoff is performed and reconnect interval calculations are only based on reconnectInterval.
OptionalrecoveryInterval ?: numberZMQ_RECOVERY_IVL
Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
OptionalroutingId ?: null | stringZMQ_ROUTING_ID
The identity of the specified socket when connecting to a
Routersocket.OptionalsendBuffer ?: numberSize ZMQ_SNDBUF
Underlying kernel transmit buffer size in bytes. A value of -1 means leave the OS default unchanged.
OptionalsendHigh ?: numberWater Mark ZMQ_SNDHWM
The high water mark is a hard limit on the maximum number of outgoing messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
OptionalsendTimeout ?: numberZMQ_SNDTIMEO
Sets the timeout for sending messages on the socket. If the value is 0, send() will return a rejected promise immediately if the message cannot be sent. If the value is -1, it will wait asynchronously until the message is sent. For all other values, it will try to send the message for that amount of time before rejecting.
OptionalsocksProxy ?: null | stringZMQ_SOCKS_PROXY
The SOCKS5 proxy address that shall be used by the socket for the TCP connection(s). Does not support SOCKS5 authentication. If the endpoints are domain names instead of addresses they shall not be resolved and they shall be forwarded unchanged to the SOCKS proxy service in the client connection request message (address type 0x03 domain name).
OptionaltcpAccept ?: null | stringFilter ZMQ_TCP_ACCEPT_FILTER
Assign a filter that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one filter is applied then new connection source IP should be matched. To clear all filters set to
null. Filter is a string with IPv6 or IPv4 CIDR.OptionaltcpKeepalive ?: numberZMQ_TCP_KEEPALIVE
Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepalive ?: numberCount ZMQ_TCP_KEEPALIVE_CNT
Overrides TCP_KEEPCNT socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepalive ?: numberIdle ZMQ_TCP_KEEPALIVE_IDLE
Overrides TCP_KEEPIDLE / TCP_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepalive ?: numberInterval ZMQ_TCP_KEEPALIVE_INTVL
Overrides TCP_KEEPINTVL socket option (if supported by the OS). The default value of -1 leaves it to the OS default.
OptionaltcpMax ?: numberRetransmit Timeout ZMQ_TCP_MAXRT
Sets how long before an unacknowledged TCP retransmit times out (if supported by the OS). The system normally attempts many TCP retransmits following an exponential backoff strategy. This means that after a network outage, it may take a long time before the session can be re-established. Setting this option allows the timeout to happen at a shorter interval.
OptionaltypeOf ?: numberService ZMQ_TOS
Sets the ToS fields (the Differentiated Services (DS) and Explicit Congestion Notification (ECN) field) of the IP header. The ToS field is typically used to specify a packet's priority. The availability of this option is dependent on intermediate network equipment that inspect the ToS field and provide a path for low-delay, high-throughput, highly-reliable service, etc.
OptionalvmciBuffer ?: numberMax Size ZMQ_VMCI_BUFFER_MAX_SIZE
Maximum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciBuffer ?: numberMin Size ZMQ_VMCI_BUFFER_MIN_SIZE
Minimum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciBuffer ?: numberSize ZMQ_VMCI_BUFFER_SIZE
The size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciConnect ?: numberTimeout ZMQ_VMCI_CONNECT_TIMEOUT
Connection timeout for the socket. For
vmci://transports only.OptionalzapDomain ?: null | stringZMQ_ZAP_DOMAIN
Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the default on all
tcp://connections), ZAP authentication only happens if you set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 for more details.OptionalzapEnforce ?: booleanDomain ZMQ_ZAP_ENFORCE_DOMAIN
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.
Returns Dealer
Properties
affinity
ZMQ_AFFINITY
I/O thread affinity, which determines which threads from the ØMQ I/O thread pool associated with the socket's context shall handle newly created connections.
Note: This value is a bit mask, but values higher than Number.MAX_SAFE_INTEGER may not be represented accurately! This currently means that configurations beyond 52 threads are unreliable.
backlog
ZMQ_BACKLOG
Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.
Readonlyclosed
Whether this socket was previously closed with close().
conflate
ZMQ_CONFLATE
If set to true, a socket shall keep only one message in its inbound/outbound queue: the last message to be received/sent. Ignores any high water mark options. Does not support multi-part messages - in particular, only one part of it is kept in the socket internal queue.
connectTimeout
ZMQ_CONNECT_TIMEOUT
Sets how long to wait before timing-out a connect() system call. The connect() system call normally takes a long time before it returns a time out error. Setting this option allows the library to time out the call at an earlier interval.
Readonlycontext
Context that this socket belongs to.
curvePublicKey
ZMQ_CURVE_PUBLICKEY
Sets the socket's long term public key. You must set this on CURVE client sockets. A server socket does not need to know its own public key. You can create a new keypair with curveKeyPair().
curveSecretKey
ZMQ_CURVE_SECRETKEY
Sets the socket's long term secret key. You must set this on both CURVE client and server sockets. You can create a new keypair with curveKeyPair().
curveServer
ZMQ_CURVE_SERVER
Defines whether the socket will act as server for CURVE security. A value of true means the socket will act as CURVE server. A value of false means the socket will not act as CURVE server, and its security role then depends on other option settings.
curveServerKey
ZMQ_CURVE_SERVERKEY
Sets the socket's long term server key. This is the public key of the CURVE server socket. You must set this on CURVE client sockets. This key must have been generated together with the server's secret key. You can create a new keypair with curveKeyPair().
Readonlyevents
Event Observer for this socket. This starts up a ØMQ monitoring socket internally that receives all socket events.
gssapiPlainText
gssapiPrincipal
gssapiPrincipalNameType
gssapiServer
gssapiServicePrincipal
gssapiServicePrincipalNameType
handshakeInterval
ZMQ_HANDSHAKE_IVL
Handshaking is the exchange of socket configuration information (socket type, identity, security) that occurs when a connection is first opened (only for connection-oriented transports). If handshaking does not complete within the configured time, the connection shall be closed. The value 0 means no handshake time limit.
heartbeatInterval
ZMQ_HEARTBEAT_IVL
Interval in milliseconds between sending ZMTP heartbeats for the specified socket. If this option is greater than 0, then a PING ZMTP command will be sent after every interval.
heartbeatTimeout
ZMQ_HEARTBEAT_TIMEOUT
How long (in milliseconds) to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic. This option is only valid if heartbeatInterval is greater than 0. The connection will time out if there is no traffic received after sending the PING command. The received traffic does not have to be a PONG command - any received traffic will cancel the timeout.
heartbeatTimeToLive
ZMQ_HEARTBEAT_TTL
The timeout in milliseconds on the remote peer for ZMTP heartbeats. If this option is greater than 0, the remote side shall time out the connection if it does not receive any more traffic within the TTL period. This option does not have any effect if heartbeatInterval is 0. Internally, this value is rounded down to the nearest decisecond, any value less than 100 will have no effect.
immediate
ZMQ_IMMEDIATE
By default queues will fill on outgoing connections even if the connection has not completed. This can lead to "lost" messages on sockets with round-robin routing (Request, Push, Dealer). If this option is set to true, messages shall be queued only to completed connections. This will cause the socket to block if there are no other connections, but will prevent queues from filling on pipes awaiting connection.
interface
ZMQ_BINDTODEVICE
Binds the socket to the given network interface (Linux only). Allows to use Linux VRF, see: https://www.kernel.org/doc/Documentation/networking/vrf.txt. Requires the program to be ran as root or with CAP_NET_RAW.
ipv6
ZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
ReadonlylastEndpoint
ZMQ_LAST_ENDPOINT
The last endpoint bound for TCP and IPC transports.
linger
ZMQ_LINGER
Determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with close().
loopbackFastPath
ZMQ_LOOPBACK_FASTPATH
Enable faster TCP connections on loopback devices. An application can enable this option to reduce the latency and improve the performance of loopback operations on a TCP socket on Windows.
maxMessageSize
ZMQ_MAXMSGSIZE
Limits the size of the inbound message. If a peer sends a message larger than the limit it is disconnected. Value of -1 means no limit.
multicastHops
ZMQ_MULTICAST_HOPS
Sets the time-to-live field in every multicast packet sent from this socket. The default is 1 which means that the multicast packets don't leave the local network.
multicastMaxTransportDataUnit
ZMQ_MULTICAST_MAXTPDU
Sets the maximum transport data unit size used for outbound multicast packets. This must be set at or below the minimum Maximum Transmission Unit (MTU) for all network paths over which multicast reception is required.
plainPassword
ZMQ_PLAIN_PASSWORD
Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
plainServer
ZMQ_PLAIN_SERVER
Defines whether the socket will act as server for PLAIN security. A value of true means the socket will act as PLAIN server. A value of false means the socket will not act as PLAIN server, and its security role then depends on other option settings.
plainUsername
ZMQ_PLAIN_USERNAME
Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
probeRouter
ZMQ_PROBE_ROUTER
When set to true, the socket will automatically send an empty message when a new connection is made or accepted. You may set this on sockets connected to a Router socket. The application must filter such empty messages. This option provides the Router with an event signaling the arrival of a new peer.
Warning:* Do not set this option on a socket that talks to any other socket type except Router: the results are undefined.
rate
ZMQ_RATE
Maximum send or receive data rate for multicast transports such as pgm.
Readonlyreadable
Whether any messages are currently available. If true, the next call to Readable.receive() will immediately read a message from the socket. For sockets that cannot receive messsages this is always false.
receiveBufferSize
ZMQ_RCVBUF
Underlying kernel receive buffer size in bytes. A value of -1 means leave the OS default unchanged.
receiveHighWaterMark
ZMQ_RCVHWM
The high water mark is a hard limit on the maximum number of incoming messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
receiveTimeout
ZMQ_RCVTIMEO
Sets the timeout receiving messages on the socket. If the value is 0, receive() will return a rejected promise immediately if there is no message to receive. If the value is -1, it will wait asynchronously until a message is available. For all other values, it will wait for a message for that amount of time before rejecting.
reconnectInterval
ZMQ_RECONNECT_IVL
Period ØMQ shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. The value -1 means no reconnection.
reconnectMaxInterval
ZMQ_RECONNECT_IVL_MAX
Maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled until reconnectMaxInterval is reached. This allows for exponential backoff strategy. Zero (the default) means no exponential backoff is performed and reconnect interval calculations are only based on reconnectInterval.
recoveryInterval
ZMQ_RECOVERY_IVL
Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
routingId
ZMQ_ROUTING_ID
The identity of the specified socket when connecting to a Router socket.
ReadonlysecurityMechanism
| null
| "plain"
| "curve"
| "gssapi"
ZMQ_MECHANISM
Returns the current security mechanism for the socket, if any. The security mechanism is set implictly by using any of the relevant security options. The returned value is one of:
null- No security mechanism is used."plain"- The PLAIN mechanism defines a simple username/password mechanism that lets a server authenticate a client. PLAIN makes no attempt at security or confidentiality."curve"- The CURVE mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server. CURVE is intended for use on public networks."gssapi"- The GSSAPI mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server using the Generic Security Service Application Program Interface (GSSAPI). The GSSAPI mechanism can be used on both public and private networks.
sendBufferSize
ZMQ_SNDBUF
Underlying kernel transmit buffer size in bytes. A value of -1 means leave the OS default unchanged.
sendHighWaterMark
ZMQ_SNDHWM
The high water mark is a hard limit on the maximum number of outgoing messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
sendTimeout
ZMQ_SNDTIMEO
Sets the timeout for sending messages on the socket. If the value is 0, send() will return a rejected promise immediately if the message cannot be sent. If the value is -1, it will wait asynchronously until the message is sent. For all other values, it will try to send the message for that amount of time before rejecting.
socksProxy
ZMQ_SOCKS_PROXY
The SOCKS5 proxy address that shall be used by the socket for the TCP connection(s). Does not support SOCKS5 authentication. If the endpoints are domain names instead of addresses they shall not be resolved and they shall be forwarded unchanged to the SOCKS proxy service in the client connection request message (address type 0x03 domain name).
tcpAcceptFilter
ZMQ_TCP_ACCEPT_FILTER
Assign a filter that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one filter is applied then new connection source IP should be matched. To clear all filters set to null. Filter is a string with IPv6 or IPv4 CIDR.
tcpKeepalive
ZMQ_TCP_KEEPALIVE
Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveCount
ZMQ_TCP_KEEPALIVE_CNT
Overrides TCP_KEEPCNT socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveIdle
ZMQ_TCP_KEEPALIVE_IDLE
Overrides TCP_KEEPIDLE / TCP_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveInterval
ZMQ_TCP_KEEPALIVE_INTVL
Overrides TCP_KEEPINTVL socket option (if supported by the OS). The default value of -1 leaves it to the OS default.
tcpMaxRetransmitTimeout
ZMQ_TCP_MAXRT
Sets how long before an unacknowledged TCP retransmit times out (if supported by the OS). The system normally attempts many TCP retransmits following an exponential backoff strategy. This means that after a network outage, it may take a long time before the session can be re-established. Setting this option allows the timeout to happen at a shorter interval.
ReadonlythreadSafe
ZMQ_THREAD_SAFE
Whether or not the socket is threadsafe. Currently only DRAFT sockets is thread-safe.
Readonlytype
ZMQ_TYPE
Retrieve the socket type. This is fairly useless because you can test the socket class with e.g. socket instanceof Dealer.
typeOfService
ZMQ_TOS
Sets the ToS fields (the Differentiated Services (DS) and Explicit Congestion Notification (ECN) field) of the IP header. The ToS field is typically used to specify a packet's priority. The availability of this option is dependent on intermediate network equipment that inspect the ToS field and provide a path for low-delay, high-throughput, highly-reliable service, etc.
vmciBufferMaxSize
ZMQ_VMCI_BUFFER_MAX_SIZE
Maximum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferMinSize
ZMQ_VMCI_BUFFER_MIN_SIZE
Minimum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferSize
ZMQ_VMCI_BUFFER_SIZE
The size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciConnectTimeout
ZMQ_VMCI_CONNECT_TIMEOUT
Connection timeout for the socket. For vmci:// transports only.
Readonlywritable
Whether any messages can be queued for sending. If true, the next call to Writable.send() will immediately queue a message on the socket. For sockets that cannot send messsages this is always false.
zapDomain
ZMQ_ZAP_DOMAIN
Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the default on all tcp:// connections), ZAP authentication only happens if you set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 for more details.
zapEnforceDomain
ZMQ_ZAP_ENFORCE_DOMAIN
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.
Methods
[asyncIterator]
- [async
Iterator] (): AsyncIterator<Buffer[], undefined, undefined> Asynchronously iterate over messages becoming available on the socket. When the socket is closed with Socket.close(), the iterator will return. Returning early from the iterator will not close the socket unless it also goes out of scope.
for await (const [msg] of socket) {
// handle messages
} -Returns AsyncIterator<Buffer[], undefined, undefined>
bind
- bind(address): Promise<void>
Binds the socket to the given address. During bind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.You can use
*in place of a hostname to bind on all interfaces/addresses, and you can use*in place of a port to bind to a random port (which can be retrieved with lastEndpoint later).await socket.bind("tcp://127.0.0.1:3456")
await socket.bind("tcp://*:3456") // binds on all interfaces
await socket.bind("tcp://127.0.0.1:*") // binds on random port -Parameters
- address: string
Address to bind this socket to.
Returns Promise<void>
Resolved when the socket was successfully bound.
- address: string
close
- close(): void
Closes the socket and disposes of all resources. Any messages that are queued may be discarded or sent in the background depending on the linger setting.
After this method is called, it is no longer possible to call any other methods on this socket.
Sockets that go out of scope and have no Readable.receive() or Writable.send() operations in progress will automatically be closed. Therefore it is not necessary in most applications to call close() manually.
Calling this method on a socket that is already closed is a no-op.
Returns void
connect
disconnect
- disconnect(address): void
Disconnects a previously connected socket from the given address and returns immediately. Disonnection will happen asynchronously in the background.
socket.disconnect("tcp://127.0.0.1:3456") -Parameters
- address: string
The previously connected address to disconnect from.
Returns void
- address: string
ProtectedgetBoolOption
ProtectedgetInt32Option
ProtectedgetInt64Option
ProtectedgetStringOption
ProtectedgetUint32Option
ProtectedgetUint64Option
receive
- receive(): Promise<Buffer[]>
Waits for the next single or multipart message to become availeble on the socket. Reads a message immediately if possible. If no messages can be read, it will wait asynchonously. The promise will be resolved with an array containing the parts of the next message when available.
const [msg] = await socket.receive()
const [part1, part2] = await socket.receive() -Reading may fail (eventually) if the socket has been configured with a receiveTimeout.
A call to receive() is guaranteed to return with a resolved promise immediately if a message could be read from the socket directly.
Only one asynchronously blocking call to receive() can be in progress simultaneously. If you call receive() again on the same socket it will return a rejected promise with an
EBUSYerror. For example, if no messages can be read and noawaitis used:socket.receive() // -> pending promise until read is possible
socket.receive() // -> promise rejection with `EBUSY` error -Note: Due to the nature of Node.js and to avoid blocking the main thread, this method always attempts to read messages with the
ZMQ_DONTWAITflag. It polls asynchronously if reading is not currently possible. This means that all functionality related to timeouts and blocking behaviour is reimplemented in the Node.js bindings. Any differences in behaviour with the native ZMQ library is considered a bug.Returns Promise<Buffer[]>
Resolved with message parts that were successfully read.
send
- send(message, ...options): Promise<void>
Sends a single message or a multipart message on the socket. Queues the message immediately if possible, and returns a resolved promise. If the message cannot be queued because the high water mark has been reached, it will wait asynchronously. The promise will be resolved when the message was queued successfully.
await socket.send("hello world")
await socket.send(["hello", "world"]) -Queueing may fail eventually if the socket has been configured with a sendTimeout.
A call to send() is guaranteed to return with a resolved promise immediately if the message could be queued directly.
Only one asynchronously blocking call to send() may be executed simultaneously. If you call send() again on a socket that is in the mute state it will return a rejected promise with an
EBUSYerror.The reason for disallowing multiple send() calls simultaneously is that it could create an implicit queue of unsendable outgoing messages. This would circumvent the socket's sendHighWaterMark. Such an implementation could even exhaust all system memory and cause the Node.js process to abort.
For most application you should not notice this implementation detail. Only in rare occasions will a call to send() that does not resolve immediately be undesired. Here are some common scenarios:
If you wish to send a message, use
await send(...). ZeroMQ socket types have been carefully designed to give you the correct blocking behaviour on the chosen socket type in almost all cases:If sending is not possible, it is often better to wait than to continue as if nothing happened. For example, on a Request socket, you can only receive a reply once a message has been sent; so waiting until a message could be queued before continuing with the rest of the program (likely to read from the socket) is required.
Certain socket types (such as Router) will always allow queueing messages and
await send(...)won't delay any code that comes after. This makes sense for routers, since typically you don't want a single send operation to stop the handling of other incoming or outgoing messages.
If you wish to send on an occasionally blocking socket (for example on a Router with the Router.mandatory option set, or on a Dealer) and you're 100% certain that dropping a message is better than blocking, then you can set the sendTimeout option to
0to effectively force send() to always resolve immediately. Be prepared to catch exceptions if sending a message is not immediately possible.If you wish to send on a socket and messages should be queued before they are dropped, you should implement a simple queue in JavaScript. Such a queue is not provided by this library because most real world applications need to deal with undeliverable messages in more complex ways - for example, they might need to reply with a status message; or first retry delivery a certain number of times before giving up.
Parameters
- message: MessageLike | MessageLike[]
Single message or multipart message to queue for sending.
Rest...options: []Any options, if applicable to the socket type (DRAFT only).
Returns Promise<void>
Resolved when the message was successfully queued.
ProtectedsetBoolOption
ProtectedsetInt32Option
ProtectedsetInt64Option
ProtectedsetStringOption
ProtectedsetUint32Option
ProtectedsetUint64Option
unbind
- unbind(address): Promise<void>
Unbinds the socket to the given address. During unbind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.Parameters
- address: string
Address to unbind this socket from.
Returns Promise<void>
Resolved when the socket was successfully unbound.
- address: string
Class Dealer
A Dealer socket can be used to extend request/reply sockets. Each message sent is round-robined among all connected peers, and each message received is fair-queued from all connected peers.
When a Dealer socket enters the mute state due to having reached the high water mark for all peers, or if there are no peers at all, then any Writable.send() operations on the socket shall block until the mute state ends or at least one peer becomes available for sending; messages are not discarded.
When a Dealer is connected to a Reply socket, each message sent must consist of an empty message part, the delimiter, followed by one or more body parts.
Hierarchy (View Summary)
Index
Constructors
Properties
Methods
Constructors
constructor
- new Dealer(
options?: {
affinity?: number;
backlog?: number;
conflate?: boolean;
connectTimeout?: number;
context?: Context;
curvePublicKey?: null | string;
curveSecretKey?: null | string;
curveServer?: boolean;
curveServerKey?: null | string;
gssapiPlainText?: boolean;
gssapiPrincipal?: null | string;
gssapiPrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
gssapiServer?: boolean;
gssapiServicePrincipal?: null | string;
gssapiServicePrincipalNameType?:
| "hostBased"
| "userName"
| "krb5Principal";
handshakeInterval?: number;
heartbeatInterval?: number;
heartbeatTimeout?: number;
heartbeatTimeToLive?: number;
immediate?: boolean;
interface?: null
| string;
ipv6?: boolean;
linger?: number;
loopbackFastPath?: boolean;
maxMessageSize?: number;
multicastHops?: number;
multicastMaxTransportDataUnit?: number;
plainPassword?: null | string;
plainServer?: boolean;
plainUsername?: null | string;
probeRouter?: boolean;
rate?: number;
receiveBufferSize?: number;
receiveHighWaterMark?: number;
receiveTimeout?: number;
reconnectInterval?: number;
reconnectMaxInterval?: number;
recoveryInterval?: number;
routingId?: null | string;
sendBufferSize?: number;
sendHighWaterMark?: number;
sendTimeout?: number;
socksProxy?: null | string;
tcpAcceptFilter?: null | string;
tcpKeepalive?: number;
tcpKeepaliveCount?: number;
tcpKeepaliveIdle?: number;
tcpKeepaliveInterval?: number;
tcpMaxRetransmitTimeout?: number;
typeOfService?: number;
vmciBufferMaxSize?: number;
vmciBufferMinSize?: number;
vmciBufferSize?: number;
vmciConnectTimeout?: number;
zapDomain?: null | string;
zapEnforceDomain?: boolean;
},
): Dealer Parameters
Optionaloptions: {
affinity?: number;
backlog?: number;
conflate?: boolean;
connectTimeout?: number;
context?: Context;
curvePublicKey?: null | string;
curveSecretKey?: null | string;
curveServer?: boolean;
curveServerKey?: null | string;
gssapiPlainText?: boolean;
gssapiPrincipal?: null | string;
gssapiPrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
gssapiServer?: boolean;
gssapiServicePrincipal?: null | string;
gssapiServicePrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
handshakeInterval?: number;
heartbeatInterval?: number;
heartbeatTimeout?: number;
heartbeatTimeToLive?: number;
immediate?: boolean;
interface?: null | string;
ipv6?: boolean;
linger?: number;
loopbackFastPath?: boolean;
maxMessageSize?: number;
multicastHops?: number;
multicastMaxTransportDataUnit?: number;
plainPassword?: null | string;
plainServer?: boolean;
plainUsername?: null | string;
probeRouter?: boolean;
rate?: number;
receiveBufferSize?: number;
receiveHighWaterMark?: number;
receiveTimeout?: number;
reconnectInterval?: number;
reconnectMaxInterval?: number;
recoveryInterval?: number;
routingId?: null | string;
sendBufferSize?: number;
sendHighWaterMark?: number;
sendTimeout?: number;
socksProxy?: null | string;
tcpAcceptFilter?: null | string;
tcpKeepalive?: number;
tcpKeepaliveCount?: number;
tcpKeepaliveIdle?: number;
tcpKeepaliveInterval?: number;
tcpMaxRetransmitTimeout?: number;
typeOfService?: number;
vmciBufferMaxSize?: number;
vmciBufferMinSize?: number;
vmciBufferSize?: number;
vmciConnectTimeout?: number;
zapDomain?: null | string;
zapEnforceDomain?: boolean;
}Optionalaffinity?: numberZMQ_AFFINITY
I/O thread affinity, which determines which threads from the ØMQ I/O thread pool associated with the socket's context shall handle newly created connections.
Note: This value is a bit mask, but values higher than
Number.MAX_SAFE_INTEGERmay not be represented accurately! This currently means that configurations beyond 52 threads are unreliable.Optionalbacklog?: numberZMQ_BACKLOG
Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.
Optionalconflate?: booleanZMQ_CONFLATE
If set to
true, a socket shall keep only one message in its inbound/outbound queue: the last message to be received/sent. Ignores any high water mark options. Does not support multi-part messages - in particular, only one part of it is kept in the socket internal queue.OptionalconnectTimeout?: numberZMQ_CONNECT_TIMEOUT
Sets how long to wait before timing-out a connect() system call. The connect() system call normally takes a long time before it returns a time out error. Setting this option allows the library to time out the call at an earlier interval.
Optionalcontext?: ContextOptionalcurvePublicKey?: null | stringZMQ_CURVE_PUBLICKEY
Sets the socket's long term public key. You must set this on CURVE client sockets. A server socket does not need to know its own public key. You can create a new keypair with curveKeyPair().
OptionalcurveSecretKey?: null | stringZMQ_CURVE_SECRETKEY
Sets the socket's long term secret key. You must set this on both CURVE client and server sockets. You can create a new keypair with curveKeyPair().
OptionalcurveServer?: booleanZMQ_CURVE_SERVER
Defines whether the socket will act as server for CURVE security. A value of
truemeans the socket will act as CURVE server. A value offalsemeans the socket will not act as CURVE server, and its security role then depends on other option settings.OptionalcurveServerKey?: null | stringZMQ_CURVE_SERVERKEY
Sets the socket's long term server key. This is the public key of the CURVE server socket. You must set this on CURVE client sockets. This key must have been generated together with the server's secret key. You can create a new keypair with curveKeyPair().
OptionalgssapiPlainText?: booleanOptionalgssapiPrincipal?: null | stringOptionalgssapiPrincipalNameType?: "hostBased" | "userName" | "krb5Principal"OptionalgssapiServer?: booleanOptionalgssapiServicePrincipal?: null | stringOptionalgssapiServicePrincipalNameType?: "hostBased" | "userName" | "krb5Principal"OptionalhandshakeInterval?: numberZMQ_HANDSHAKE_IVL
Handshaking is the exchange of socket configuration information (socket type, identity, security) that occurs when a connection is first opened (only for connection-oriented transports). If handshaking does not complete within the configured time, the connection shall be closed. The value 0 means no handshake time limit.
OptionalheartbeatInterval?: numberZMQ_HEARTBEAT_IVL
Interval in milliseconds between sending ZMTP heartbeats for the specified socket. If this option is greater than 0, then a PING ZMTP command will be sent after every interval.
OptionalheartbeatTimeout?: numberZMQ_HEARTBEAT_TIMEOUT
How long (in milliseconds) to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic. This option is only valid if heartbeatInterval is greater than 0. The connection will time out if there is no traffic received after sending the PING command. The received traffic does not have to be a PONG command - any received traffic will cancel the timeout.
OptionalheartbeatTimeToLive?: numberZMQ_HEARTBEAT_TTL
The timeout in milliseconds on the remote peer for ZMTP heartbeats. If this option is greater than 0, the remote side shall time out the connection if it does not receive any more traffic within the TTL period. This option does not have any effect if heartbeatInterval is 0. Internally, this value is rounded down to the nearest decisecond, any value less than 100 will have no effect.
Optionalimmediate?: booleanZMQ_IMMEDIATE
By default queues will fill on outgoing connections even if the connection has not completed. This can lead to "lost" messages on sockets with round-robin routing (Request, Push, Dealer). If this option is set to
true, messages shall be queued only to completed connections. This will cause the socket to block if there are no other connections, but will prevent queues from filling on pipes awaiting connection.Optionalinterface?: null | stringZMQ_BINDTODEVICE
Binds the socket to the given network interface (Linux only). Allows to use Linux VRF, see: https://www.kernel.org/doc/Documentation/networking/vrf.txt. Requires the program to be ran as root or with
CAP_NET_RAW.Optionalipv6?: booleanZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
Optionallinger?: numberZMQ_LINGER
Determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with close().
OptionalloopbackFastPath?: booleanZMQ_LOOPBACK_FASTPATH
Enable faster TCP connections on loopback devices. An application can enable this option to reduce the latency and improve the performance of loopback operations on a TCP socket on Windows.
OptionalmaxMessageSize?: numberZMQ_MAXMSGSIZE
Limits the size of the inbound message. If a peer sends a message larger than the limit it is disconnected. Value of -1 means no limit.
OptionalmulticastHops?: numberZMQ_MULTICAST_HOPS
Sets the time-to-live field in every multicast packet sent from this socket. The default is 1 which means that the multicast packets don't leave the local network.
OptionalmulticastMaxTransportDataUnit?: numberZMQ_MULTICAST_MAXTPDU
Sets the maximum transport data unit size used for outbound multicast packets. This must be set at or below the minimum Maximum Transmission Unit (MTU) for all network paths over which multicast reception is required.
OptionalplainPassword?: null | stringZMQ_PLAIN_PASSWORD
Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
OptionalplainServer?: booleanZMQ_PLAIN_SERVER
Defines whether the socket will act as server for PLAIN security. A value of
truemeans the socket will act as PLAIN server. A value offalsemeans the socket will not act as PLAIN server, and its security role then depends on other option settings.OptionalplainUsername?: null | stringZMQ_PLAIN_USERNAME
Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
OptionalprobeRouter?: booleanZMQ_PROBE_ROUTER
When set to
true, the socket will automatically send an empty message when a new connection is made or accepted. You may set this on sockets connected to a Router socket. The application must filter such empty messages. This option provides the Router with an event signaling the arrival of a new peer.Warning:* Do not set this option on a socket that talks to any other socket type except Router: the results are undefined.
Optionalrate?: numberZMQ_RATE
Maximum send or receive data rate for multicast transports such as
pgm.OptionalreceiveBufferSize?: numberZMQ_RCVBUF
Underlying kernel receive buffer size in bytes. A value of -1 means leave the OS default unchanged.
OptionalreceiveHighWaterMark?: numberZMQ_RCVHWM
The high water mark is a hard limit on the maximum number of incoming messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
OptionalreceiveTimeout?: numberZMQ_RCVTIMEO
Sets the timeout receiving messages on the socket. If the value is 0, receive() will return a rejected promise immediately if there is no message to receive. If the value is -1, it will wait asynchronously until a message is available. For all other values, it will wait for a message for that amount of time before rejecting.
OptionalreconnectInterval?: numberZMQ_RECONNECT_IVL
Period ØMQ shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. The value -1 means no reconnection.
OptionalreconnectMaxInterval?: numberZMQ_RECONNECT_IVL_MAX
Maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled until reconnectMaxInterval is reached. This allows for exponential backoff strategy. Zero (the default) means no exponential backoff is performed and reconnect interval calculations are only based on reconnectInterval.
OptionalrecoveryInterval?: numberZMQ_RECOVERY_IVL
Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
OptionalroutingId?: null | stringZMQ_ROUTING_ID
The identity of the specified socket when connecting to a
Routersocket.OptionalsendBufferSize?: numberZMQ_SNDBUF
Underlying kernel transmit buffer size in bytes. A value of -1 means leave the OS default unchanged.
OptionalsendHighWaterMark?: numberZMQ_SNDHWM
The high water mark is a hard limit on the maximum number of outgoing messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
OptionalsendTimeout?: numberZMQ_SNDTIMEO
Sets the timeout for sending messages on the socket. If the value is 0, send() will return a rejected promise immediately if the message cannot be sent. If the value is -1, it will wait asynchronously until the message is sent. For all other values, it will try to send the message for that amount of time before rejecting.
OptionalsocksProxy?: null | stringZMQ_SOCKS_PROXY
The SOCKS5 proxy address that shall be used by the socket for the TCP connection(s). Does not support SOCKS5 authentication. If the endpoints are domain names instead of addresses they shall not be resolved and they shall be forwarded unchanged to the SOCKS proxy service in the client connection request message (address type 0x03 domain name).
OptionaltcpAcceptFilter?: null | stringZMQ_TCP_ACCEPT_FILTER
Assign a filter that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one filter is applied then new connection source IP should be matched. To clear all filters set to
null. Filter is a string with IPv6 or IPv4 CIDR.OptionaltcpKeepalive?: numberZMQ_TCP_KEEPALIVE
Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepaliveCount?: numberZMQ_TCP_KEEPALIVE_CNT
Overrides TCP_KEEPCNT socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepaliveIdle?: numberZMQ_TCP_KEEPALIVE_IDLE
Overrides TCP_KEEPIDLE / TCP_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepaliveInterval?: numberZMQ_TCP_KEEPALIVE_INTVL
Overrides TCP_KEEPINTVL socket option (if supported by the OS). The default value of -1 leaves it to the OS default.
OptionaltcpMaxRetransmitTimeout?: numberZMQ_TCP_MAXRT
Sets how long before an unacknowledged TCP retransmit times out (if supported by the OS). The system normally attempts many TCP retransmits following an exponential backoff strategy. This means that after a network outage, it may take a long time before the session can be re-established. Setting this option allows the timeout to happen at a shorter interval.
OptionaltypeOfService?: numberZMQ_TOS
Sets the ToS fields (the Differentiated Services (DS) and Explicit Congestion Notification (ECN) field) of the IP header. The ToS field is typically used to specify a packet's priority. The availability of this option is dependent on intermediate network equipment that inspect the ToS field and provide a path for low-delay, high-throughput, highly-reliable service, etc.
OptionalvmciBufferMaxSize?: numberZMQ_VMCI_BUFFER_MAX_SIZE
Maximum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciBufferMinSize?: numberZMQ_VMCI_BUFFER_MIN_SIZE
Minimum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciBufferSize?: numberZMQ_VMCI_BUFFER_SIZE
The size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciConnectTimeout?: numberZMQ_VMCI_CONNECT_TIMEOUT
Connection timeout for the socket. For
vmci://transports only.OptionalzapDomain?: null | stringZMQ_ZAP_DOMAIN
Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the default on all
tcp://connections), ZAP authentication only happens if you set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 for more details.OptionalzapEnforceDomain?: booleanZMQ_ZAP_ENFORCE_DOMAIN
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.
Returns Dealer
Properties
affinity
ZMQ_AFFINITY
I/O thread affinity, which determines which threads from the ØMQ I/O thread pool associated with the socket's context shall handle newly created connections.
Note: This value is a bit mask, but values higher than Number.MAX_SAFE_INTEGER may not be represented accurately! This currently means that configurations beyond 52 threads are unreliable.
backlog
ZMQ_BACKLOG
Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.
Readonlyclosed
Whether this socket was previously closed with close().
conflate
ZMQ_CONFLATE
If set to true, a socket shall keep only one message in its inbound/outbound queue: the last message to be received/sent. Ignores any high water mark options. Does not support multi-part messages - in particular, only one part of it is kept in the socket internal queue.
connectTimeout
ZMQ_CONNECT_TIMEOUT
Sets how long to wait before timing-out a connect() system call. The connect() system call normally takes a long time before it returns a time out error. Setting this option allows the library to time out the call at an earlier interval.
Readonlycontext
Context that this socket belongs to.
curvePublicKey
ZMQ_CURVE_PUBLICKEY
Sets the socket's long term public key. You must set this on CURVE client sockets. A server socket does not need to know its own public key. You can create a new keypair with curveKeyPair().
curveSecretKey
ZMQ_CURVE_SECRETKEY
Sets the socket's long term secret key. You must set this on both CURVE client and server sockets. You can create a new keypair with curveKeyPair().
curveServer
ZMQ_CURVE_SERVER
Defines whether the socket will act as server for CURVE security. A value of true means the socket will act as CURVE server. A value of false means the socket will not act as CURVE server, and its security role then depends on other option settings.
curveServerKey
ZMQ_CURVE_SERVERKEY
Sets the socket's long term server key. This is the public key of the CURVE server socket. You must set this on CURVE client sockets. This key must have been generated together with the server's secret key. You can create a new keypair with curveKeyPair().
Readonlyevents
Event Observer for this socket. This starts up a ØMQ monitoring socket internally that receives all socket events.
gssapiPlainText
gssapiPrincipal
gssapiPrincipalNameType
gssapiServer
gssapiServicePrincipal
gssapiServicePrincipalNameType
handshakeInterval
ZMQ_HANDSHAKE_IVL
Handshaking is the exchange of socket configuration information (socket type, identity, security) that occurs when a connection is first opened (only for connection-oriented transports). If handshaking does not complete within the configured time, the connection shall be closed. The value 0 means no handshake time limit.
heartbeatInterval
ZMQ_HEARTBEAT_IVL
Interval in milliseconds between sending ZMTP heartbeats for the specified socket. If this option is greater than 0, then a PING ZMTP command will be sent after every interval.
heartbeatTimeout
ZMQ_HEARTBEAT_TIMEOUT
How long (in milliseconds) to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic. This option is only valid if heartbeatInterval is greater than 0. The connection will time out if there is no traffic received after sending the PING command. The received traffic does not have to be a PONG command - any received traffic will cancel the timeout.
heartbeatTimeToLive
ZMQ_HEARTBEAT_TTL
The timeout in milliseconds on the remote peer for ZMTP heartbeats. If this option is greater than 0, the remote side shall time out the connection if it does not receive any more traffic within the TTL period. This option does not have any effect if heartbeatInterval is 0. Internally, this value is rounded down to the nearest decisecond, any value less than 100 will have no effect.
immediate
ZMQ_IMMEDIATE
By default queues will fill on outgoing connections even if the connection has not completed. This can lead to "lost" messages on sockets with round-robin routing (Request, Push, Dealer). If this option is set to true, messages shall be queued only to completed connections. This will cause the socket to block if there are no other connections, but will prevent queues from filling on pipes awaiting connection.
interface
ZMQ_BINDTODEVICE
Binds the socket to the given network interface (Linux only). Allows to use Linux VRF, see: https://www.kernel.org/doc/Documentation/networking/vrf.txt. Requires the program to be ran as root or with CAP_NET_RAW.
ipv6
ZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
ReadonlylastEndpoint
ZMQ_LAST_ENDPOINT
The last endpoint bound for TCP and IPC transports.
linger
ZMQ_LINGER
Determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with close().
loopbackFastPath
ZMQ_LOOPBACK_FASTPATH
Enable faster TCP connections on loopback devices. An application can enable this option to reduce the latency and improve the performance of loopback operations on a TCP socket on Windows.
maxMessageSize
ZMQ_MAXMSGSIZE
Limits the size of the inbound message. If a peer sends a message larger than the limit it is disconnected. Value of -1 means no limit.
multicastHops
ZMQ_MULTICAST_HOPS
Sets the time-to-live field in every multicast packet sent from this socket. The default is 1 which means that the multicast packets don't leave the local network.
multicastMaxTransportDataUnit
ZMQ_MULTICAST_MAXTPDU
Sets the maximum transport data unit size used for outbound multicast packets. This must be set at or below the minimum Maximum Transmission Unit (MTU) for all network paths over which multicast reception is required.
plainPassword
ZMQ_PLAIN_PASSWORD
Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
plainServer
ZMQ_PLAIN_SERVER
Defines whether the socket will act as server for PLAIN security. A value of true means the socket will act as PLAIN server. A value of false means the socket will not act as PLAIN server, and its security role then depends on other option settings.
plainUsername
ZMQ_PLAIN_USERNAME
Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
probeRouter
ZMQ_PROBE_ROUTER
When set to true, the socket will automatically send an empty message when a new connection is made or accepted. You may set this on sockets connected to a Router socket. The application must filter such empty messages. This option provides the Router with an event signaling the arrival of a new peer.
Warning:* Do not set this option on a socket that talks to any other socket type except Router: the results are undefined.
rate
ZMQ_RATE
Maximum send or receive data rate for multicast transports such as pgm.
Readonlyreadable
Whether any messages are currently available. If true, the next call to Readable.receive() will immediately read a message from the socket. For sockets that cannot receive messsages this is always false.
receiveBufferSize
ZMQ_RCVBUF
Underlying kernel receive buffer size in bytes. A value of -1 means leave the OS default unchanged.
receiveHighWaterMark
ZMQ_RCVHWM
The high water mark is a hard limit on the maximum number of incoming messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
receiveTimeout
ZMQ_RCVTIMEO
Sets the timeout receiving messages on the socket. If the value is 0, receive() will return a rejected promise immediately if there is no message to receive. If the value is -1, it will wait asynchronously until a message is available. For all other values, it will wait for a message for that amount of time before rejecting.
reconnectInterval
ZMQ_RECONNECT_IVL
Period ØMQ shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. The value -1 means no reconnection.
reconnectMaxInterval
ZMQ_RECONNECT_IVL_MAX
Maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled until reconnectMaxInterval is reached. This allows for exponential backoff strategy. Zero (the default) means no exponential backoff is performed and reconnect interval calculations are only based on reconnectInterval.
recoveryInterval
ZMQ_RECOVERY_IVL
Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
routingId
ZMQ_ROUTING_ID
The identity of the specified socket when connecting to a Router socket.
ReadonlysecurityMechanism
ZMQ_MECHANISM
Returns the current security mechanism for the socket, if any. The security mechanism is set implictly by using any of the relevant security options. The returned value is one of:
null- No security mechanism is used."plain"- The PLAIN mechanism defines a simple username/password mechanism that lets a server authenticate a client. PLAIN makes no attempt at security or confidentiality."curve"- The CURVE mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server. CURVE is intended for use on public networks."gssapi"- The GSSAPI mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server using the Generic Security Service Application Program Interface (GSSAPI). The GSSAPI mechanism can be used on both public and private networks.
sendBufferSize
ZMQ_SNDBUF
Underlying kernel transmit buffer size in bytes. A value of -1 means leave the OS default unchanged.
sendHighWaterMark
ZMQ_SNDHWM
The high water mark is a hard limit on the maximum number of outgoing messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
sendTimeout
ZMQ_SNDTIMEO
Sets the timeout for sending messages on the socket. If the value is 0, send() will return a rejected promise immediately if the message cannot be sent. If the value is -1, it will wait asynchronously until the message is sent. For all other values, it will try to send the message for that amount of time before rejecting.
socksProxy
ZMQ_SOCKS_PROXY
The SOCKS5 proxy address that shall be used by the socket for the TCP connection(s). Does not support SOCKS5 authentication. If the endpoints are domain names instead of addresses they shall not be resolved and they shall be forwarded unchanged to the SOCKS proxy service in the client connection request message (address type 0x03 domain name).
tcpAcceptFilter
ZMQ_TCP_ACCEPT_FILTER
Assign a filter that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one filter is applied then new connection source IP should be matched. To clear all filters set to null. Filter is a string with IPv6 or IPv4 CIDR.
tcpKeepalive
ZMQ_TCP_KEEPALIVE
Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveCount
ZMQ_TCP_KEEPALIVE_CNT
Overrides TCP_KEEPCNT socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveIdle
ZMQ_TCP_KEEPALIVE_IDLE
Overrides TCP_KEEPIDLE / TCP_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveInterval
ZMQ_TCP_KEEPALIVE_INTVL
Overrides TCP_KEEPINTVL socket option (if supported by the OS). The default value of -1 leaves it to the OS default.
tcpMaxRetransmitTimeout
ZMQ_TCP_MAXRT
Sets how long before an unacknowledged TCP retransmit times out (if supported by the OS). The system normally attempts many TCP retransmits following an exponential backoff strategy. This means that after a network outage, it may take a long time before the session can be re-established. Setting this option allows the timeout to happen at a shorter interval.
ReadonlythreadSafe
ZMQ_THREAD_SAFE
Whether or not the socket is threadsafe. Currently only DRAFT sockets is thread-safe.
Readonlytype
ZMQ_TYPE
Retrieve the socket type. This is fairly useless because you can test the socket class with e.g. socket instanceof Dealer.
typeOfService
ZMQ_TOS
Sets the ToS fields (the Differentiated Services (DS) and Explicit Congestion Notification (ECN) field) of the IP header. The ToS field is typically used to specify a packet's priority. The availability of this option is dependent on intermediate network equipment that inspect the ToS field and provide a path for low-delay, high-throughput, highly-reliable service, etc.
vmciBufferMaxSize
ZMQ_VMCI_BUFFER_MAX_SIZE
Maximum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferMinSize
ZMQ_VMCI_BUFFER_MIN_SIZE
Minimum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferSize
ZMQ_VMCI_BUFFER_SIZE
The size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciConnectTimeout
ZMQ_VMCI_CONNECT_TIMEOUT
Connection timeout for the socket. For vmci:// transports only.
Readonlywritable
Whether any messages can be queued for sending. If true, the next call to Writable.send() will immediately queue a message on the socket. For sockets that cannot send messsages this is always false.
zapDomain
ZMQ_ZAP_DOMAIN
Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the default on all tcp:// connections), ZAP authentication only happens if you set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 for more details.
zapEnforceDomain
ZMQ_ZAP_ENFORCE_DOMAIN
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.
Methods
[asyncIterator]
- "[asyncIterator]"(): AsyncIterator<Buffer[]>
Asynchronously iterate over messages becoming available on the socket. When the socket is closed with Socket.close(), the iterator will return. Returning early from the iterator will not close the socket unless it also goes out of scope.
for await (const [msg] of socket) {
// handle messages
} +Returns AsyncIterator<Buffer[]>
bind
- bind(address: string): Promise<void>
Binds the socket to the given address. During bind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.You can use
*in place of a hostname to bind on all interfaces/addresses, and you can use*in place of a port to bind to a random port (which can be retrieved with lastEndpoint later).await socket.bind("tcp://127.0.0.1:3456")
await socket.bind("tcp://*:3456") // binds on all interfaces
await socket.bind("tcp://127.0.0.1:*") // binds on random port +Parameters
- address: string
Address to bind this socket to.
Returns Promise<void>
Resolved when the socket was successfully bound.
- address: string
bindSync
- bindSync(address: string): void
Binds the socket to the given address. During bind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.You can use
*in place of a hostname to bind on all interfaces/addresses, and you can use*in place of a port to bind to a random port (which can be retrieved with lastEndpoint later).socket.bindSync("tcp://127.0.0.1:3456")
socket.bindSync("tcp://*:3456") // binds on all interfaces
socket.bindSync("tcp://127.0.0.1:*") // binds on random port +Parameters
- address: string
Address to bind this socket to.
Returns void
Resolved when the socket was successfully bound.
- address: string
close
- close(): void
Closes the socket and disposes of all resources. Any messages that are queued may be discarded or sent in the background depending on the linger setting.
After this method is called, it is no longer possible to call any other methods on this socket.
Sockets that go out of scope and have no Readable.receive() or Writable.send() operations in progress will automatically be closed. Therefore it is not necessary in most applications to call close() manually.
Calling this method on a socket that is already closed is a no-op.
Returns void
connect
disconnect
- disconnect(address: string): void
Disconnects a previously connected socket from the given address and returns immediately. Disonnection will happen asynchronously in the background.
socket.disconnect("tcp://127.0.0.1:3456") +Parameters
- address: string
The previously connected address to disconnect from.
Returns void
- address: string
ProtectedgetBoolOption
ProtectedgetInt32Option
ProtectedgetInt64Option
ProtectedgetStringOption
ProtectedgetUint32Option
ProtectedgetUint64Option
receive
- receive(): Promise<Buffer[]>
Waits for the next single or multipart message to become availeble on the socket. Reads a message immediately if possible. If no messages can be read, it will wait asynchonously. The promise will be resolved with an array containing the parts of the next message when available.
const [msg] = await socket.receive()
const [part1, part2] = await socket.receive() +Reading may fail (eventually) if the socket has been configured with a receiveTimeout.
A call to receive() is guaranteed to return with a resolved promise immediately if a message could be read from the socket directly.
Only one asynchronously blocking call to receive() can be in progress simultaneously. If you call receive() again on the same socket it will return a rejected promise with an
EBUSYerror. For example, if no messages can be read and noawaitis used:socket.receive() // -> pending promise until read is possible
socket.receive() // -> promise rejection with `EBUSY` error +Note: Due to the nature of Node.js and to avoid blocking the main thread, this method always attempts to read messages with the
ZMQ_DONTWAITflag. It polls asynchronously if reading is not currently possible. This means that all functionality related to timeouts and blocking behaviour is reimplemented in the Node.js bindings. Any differences in behaviour with the native ZMQ library is considered a bug.Returns Promise<Buffer[]>
Resolved with message parts that were successfully read.
send
- send(message: MessageLike | MessageLike[], ...options: []): Promise<void>
Sends a single message or a multipart message on the socket. Queues the message immediately if possible, and returns a resolved promise. If the message cannot be queued because the high water mark has been reached, it will wait asynchronously. The promise will be resolved when the message was queued successfully.
await socket.send("hello world")
await socket.send(["hello", "world"]) +Queueing may fail eventually if the socket has been configured with a sendTimeout.
A call to send() is guaranteed to return with a resolved promise immediately if the message could be queued directly.
Only one asynchronously blocking call to send() may be executed simultaneously. If you call send() again on a socket that is in the mute state it will return a rejected promise with an
EBUSYerror.The reason for disallowing multiple send() calls simultaneously is that it could create an implicit queue of unsendable outgoing messages. This would circumvent the socket's sendHighWaterMark. Such an implementation could even exhaust all system memory and cause the Node.js process to abort.
For most application you should not notice this implementation detail. Only in rare occasions will a call to send() that does not resolve immediately be undesired. Here are some common scenarios:
If you wish to send a message, use
await send(...). ZeroMQ socket types have been carefully designed to give you the correct blocking behaviour on the chosen socket type in almost all cases:If sending is not possible, it is often better to wait than to continue as if nothing happened. For example, on a Request socket, you can only receive a reply once a message has been sent; so waiting until a message could be queued before continuing with the rest of the program (likely to read from the socket) is required.
Certain socket types (such as Router) will always allow queueing messages and
await send(...)won't delay any code that comes after. This makes sense for routers, since typically you don't want a single send operation to stop the handling of other incoming or outgoing messages.
If you wish to send on an occasionally blocking socket (for example on a Router with the Router.mandatory option set, or on a Dealer) and you're 100% certain that dropping a message is better than blocking, then you can set the sendTimeout option to
0to effectively force send() to always resolve immediately. Be prepared to catch exceptions if sending a message is not immediately possible.If you wish to send on a socket and messages should be queued before they are dropped, you should implement a simple queue in JavaScript. Such a queue is not provided by this library because most real world applications need to deal with undeliverable messages in more complex ways - for example, they might need to reply with a status message; or first retry delivery a certain number of times before giving up.
Parameters
- message: MessageLike | MessageLike[]
Single message or multipart message to queue for sending.
- ...options: []
Any options, if applicable to the socket type (DRAFT only).
Returns Promise<void>
Resolved when the message was successfully queued.
ProtectedsetBoolOption
ProtectedsetInt32Option
ProtectedsetInt64Option
ProtectedsetStringOption
ProtectedsetUint32Option
ProtectedsetUint64Option
unbind
- unbind(address: string): Promise<void>
Unbinds the socket to the given address. During unbind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.Parameters
- address: string
Address to unbind this socket from.
Returns Promise<void>
Resolved when the socket was successfully unbound.
- address: string
unbindSync
- unbindSync(address: string): void
Unbinds the socket to the given address. During unbind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.Parameters
- address: string
Address to unbind this socket from.
Returns void
Resolved when the socket was successfully unbound.
- address: string
Class Observer
Hierarchy (view full)
- EventSubscriber
- Observer
Index
Constructors
constructor
- new
Observer (socket): Observer Creates a new ØMQ observer. It should not be necessary to instantiate a new observer. Access an existing observer for a socket with Socket.events.
const socket = new Publisher()
const events = socket.events -Parameters
- socket: Socket
The socket to observe.
Returns Observer
- socket: Socket
Properties
Readonlyclosed
Whether the observer was closed, either manually or because the associated socket was closed.
Methods
[asyncIterator]
- [async
Iterator] (): AsyncIterator<Event, undefined, undefined> Asynchronously iterate over socket events. When the socket is closed or when the observer is closed manually with Observer.close(), the iterator will return.
for await (event of socket.events) {
switch (event.type) {
case "bind":
console.log(`Socket bound to ${event.address}`)
break
// ...
}
} -Returns AsyncIterator<Event, undefined, undefined>
close
off
- off<E>(type, listener): EventSubscriber
Removes the specified listener function from the list of functions to call when the given event is observed.
Type Parameters
Parameters
- type: E
The type of event that the listener was listening for.
- listener: ((data: EventOfType<E>) => void)
The previously registered listener function.
- (data): void
Parameters
- data: EventOfType<E>
Returns void
Returns EventSubscriber
- type: E
on
- on<E>(type, listener): EventSubscriber
Adds a listener function which will be invoked when the given event type is observed. Calling this method will convert the Observer to event emitter mode, which will make it impossible to call Observer.receive() at the same time.
socket.events.on("bind", event => {
console.log(`Socket bound to ${event.address}`)
// ...
}) -Type Parameters
Parameters
- type: E
The type of event to listen for.
- listener: ((data: EventOfType<E>) => void)
The listener function that will be called with all event data when the event is observed.
- (data): void
Parameters
- data: EventOfType<E>
Returns void
Returns EventSubscriber
- type: E
receive
- receive(): Promise<Event>
Waits for the next event to become availeble on the observer. Reads an event immediately if possible. If no events are queued, it will wait asynchonously. The promise will be resolved with the next event when available.
When reading events with receive() the observer may not be in event emitter mode. Avoid mixing calls to receive() with event handlers via attached with on().
for await (event of socket.events) {
switch (event.type) {
case "bind":
console.log(`Socket bound to ${event.address}`)
break
// ...
}
} -Returns Promise<Event>
Resolved with the next event and its details. See Event.
Class Observer
Hierarchy (View Summary)
- EventSubscriber
- Observer
Index
Constructors
constructor
- new Observer(socket: Socket): Observer
Creates a new ØMQ observer. It should not be necessary to instantiate a new observer. Access an existing observer for a socket with Socket.events.
const socket = new Publisher()
const events = socket.events +Parameters
- socket: Socket
The socket to observe.
Returns Observer
- socket: Socket
Properties
Readonlyclosed
Whether the observer was closed, either manually or because the associated socket was closed.
Methods
[asyncIterator]
- "[asyncIterator]"(): AsyncIterator<Event>
Asynchronously iterate over socket events. When the socket is closed or when the observer is closed manually with Observer.close(), the iterator will return.
for await (event of socket.events) {
switch (event.type) {
case "bind":
console.log(`Socket bound to ${event.address}`)
break
// ...
}
} +Returns AsyncIterator<Event>
close
off
- off<
E extends
| "unknown"
| "connect"
| "disconnect"
| "close"
| "end"
| "accept"
| "accept:error"
| "bind"
| "bind:error"
| "connect:delay"
| "connect:retry"
| "close:error"
| "handshake"
| "handshake:error:protocol"
| "handshake:error:auth"
| "handshake:error:other",
>(
type: E,
listener: (data: EventOfType<E>) => void,
): EventSubscriber Removes the specified listener function from the list of functions to call when the given event is observed.
Type Parameters
Parameters
- type: E
The type of event that the listener was listening for.
- listener: (data: EventOfType<E>) => void
The previously registered listener function.
Returns EventSubscriber
- type: E
on
- on<
E extends
| "unknown"
| "connect"
| "disconnect"
| "close"
| "end"
| "accept"
| "accept:error"
| "bind"
| "bind:error"
| "connect:delay"
| "connect:retry"
| "close:error"
| "handshake"
| "handshake:error:protocol"
| "handshake:error:auth"
| "handshake:error:other",
>(
type: E,
listener: (data: EventOfType<E>) => void,
): EventSubscriber Adds a listener function which will be invoked when the given event type is observed. Calling this method will convert the Observer to event emitter mode, which will make it impossible to call Observer.receive() at the same time.
socket.events.on("bind", event => {
console.log(`Socket bound to ${event.address}`)
// ...
}) +Type Parameters
Parameters
- type: E
The type of event to listen for.
- listener: (data: EventOfType<E>) => void
The listener function that will be called with all event data when the event is observed.
Returns EventSubscriber
- type: E
receive
- receive(): Promise<Event>
Waits for the next event to become availeble on the observer. Reads an event immediately if possible. If no events are queued, it will wait asynchonously. The promise will be resolved with the next event when available.
When reading events with receive() the observer may not be in event emitter mode. Avoid mixing calls to receive() with event handlers via attached with on().
for await (event of socket.events) {
switch (event.type) {
case "bind":
console.log(`Socket bound to ${event.address}`)
break
// ...
}
} +Returns Promise<Event>
Resolved with the next event and its details. See Event.
Class Pair
A Pair socket can only be connected to one other Pair at any one time. No message routing or filtering is performed on any messages.
When a Pair socket enters the mute state due to having reached the high water mark for the connected peer, or if no peer is connected, then any Writable.send() operations on the socket shall block until the peer becomes available for sending; messages are not discarded.
While Pair sockets can be used over transports other than inproc://, their inability to auto-reconnect coupled with the fact new incoming connections will be terminated while any previous connections (including ones in a closing state) exist makes them unsuitable for tcp:// in most cases.
Hierarchy (view full)
Index
Constructors
Properties
Methods
Constructors
constructor
- new
Pair (options?): Pair Parameters
Optionaloptions: {
affinity?: number;
backlog?: number;
connectTimeout?: number;
context?: Context;
curvePublicKey?: null | string;
curveSecretKey?: null | string;
curveServer?: boolean;
curveServerKey?: null | string;
gssapiPlainText?: boolean;
gssapiPrincipal?: null | string;
gssapiPrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
gssapiServer?: boolean;
gssapiServicePrincipal?: null | string;
gssapiServicePrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
handshakeInterval?: number;
heartbeatInterval?: number;
heartbeatTimeout?: number;
heartbeatTimeToLive?: number;
immediate?: boolean;
interface?: null | string;
ipv6?: boolean;
linger?: number;
loopbackFastPath?: boolean;
maxMessageSize?: number;
multicastHops?: number;
multicastMaxTransportDataUnit?: number;
plainPassword?: null | string;
plainServer?: boolean;
plainUsername?: null | string;
rate?: number;
receiveBufferSize?: number;
receiveHighWaterMark?: number;
receiveTimeout?: number;
reconnectInterval?: number;
reconnectMaxInterval?: number;
recoveryInterval?: number;
sendBufferSize?: number;
sendHighWaterMark?: number;
sendTimeout?: number;
socksProxy?: null | string;
tcpAcceptFilter?: null | string;
tcpKeepalive?: number;
tcpKeepaliveCount?: number;
tcpKeepaliveIdle?: number;
tcpKeepaliveInterval?: number;
tcpMaxRetransmitTimeout?: number;
typeOfService?: number;
vmciBufferMaxSize?: number;
vmciBufferMinSize?: number;
vmciBufferSize?: number;
vmciConnectTimeout?: number;
zapDomain?: null | string;
zapEnforceDomain?: boolean;
}Optionalaffinity?: numberZMQ_AFFINITY
I/O thread affinity, which determines which threads from the ØMQ I/O thread pool associated with the socket's context shall handle newly created connections.
Note: This value is a bit mask, but values higher than
Number.MAX_SAFE_INTEGERmay not be represented accurately! This currently means that configurations beyond 52 threads are unreliable.Optionalbacklog?: numberZMQ_BACKLOG
Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.
OptionalconnectTimeout ?: numberZMQ_CONNECT_TIMEOUT
Sets how long to wait before timing-out a connect() system call. The connect() system call normally takes a long time before it returns a time out error. Setting this option allows the library to time out the call at an earlier interval.
Optionalcontext?: ContextOptionalcurvePublic ?: null | stringKey ZMQ_CURVE_PUBLICKEY
Sets the socket's long term public key. You must set this on CURVE client sockets. A server socket does not need to know its own public key. You can create a new keypair with curveKeyPair().
OptionalcurveSecret ?: null | stringKey ZMQ_CURVE_SECRETKEY
Sets the socket's long term secret key. You must set this on both CURVE client and server sockets. You can create a new keypair with curveKeyPair().
OptionalcurveServer ?: booleanZMQ_CURVE_SERVER
Defines whether the socket will act as server for CURVE security. A value of
truemeans the socket will act as CURVE server. A value offalsemeans the socket will not act as CURVE server, and its security role then depends on other option settings.OptionalcurveServer ?: null | stringKey ZMQ_CURVE_SERVERKEY
Sets the socket's long term server key. This is the public key of the CURVE server socket. You must set this on CURVE client sockets. This key must have been generated together with the server's secret key. You can create a new keypair with curveKeyPair().
OptionalgssapiPlain ?: booleanText OptionalgssapiPrincipal ?: null | stringOptionalgssapiPrincipal ?: "hostBased" | "userName" | "krb5Principal"Name Type OptionalgssapiServer ?: booleanOptionalgssapiService ?: null | stringPrincipal OptionalgssapiService ?: "hostBased" | "userName" | "krb5Principal"Principal Name Type OptionalhandshakeInterval ?: numberZMQ_HANDSHAKE_IVL
Handshaking is the exchange of socket configuration information (socket type, identity, security) that occurs when a connection is first opened (only for connection-oriented transports). If handshaking does not complete within the configured time, the connection shall be closed. The value 0 means no handshake time limit.
OptionalheartbeatInterval ?: numberZMQ_HEARTBEAT_IVL
Interval in milliseconds between sending ZMTP heartbeats for the specified socket. If this option is greater than 0, then a PING ZMTP command will be sent after every interval.
OptionalheartbeatTimeout ?: numberZMQ_HEARTBEAT_TIMEOUT
How long (in milliseconds) to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic. This option is only valid if heartbeatInterval is greater than 0. The connection will time out if there is no traffic received after sending the PING command. The received traffic does not have to be a PONG command - any received traffic will cancel the timeout.
OptionalheartbeatTime ?: numberTo Live ZMQ_HEARTBEAT_TTL
The timeout in milliseconds on the remote peer for ZMTP heartbeats. If this option is greater than 0, the remote side shall time out the connection if it does not receive any more traffic within the TTL period. This option does not have any effect if heartbeatInterval is 0. Internally, this value is rounded down to the nearest decisecond, any value less than 100 will have no effect.
Optionalimmediate?: booleanZMQ_IMMEDIATE
By default queues will fill on outgoing connections even if the connection has not completed. This can lead to "lost" messages on sockets with round-robin routing (Request, Push, Dealer). If this option is set to
true, messages shall be queued only to completed connections. This will cause the socket to block if there are no other connections, but will prevent queues from filling on pipes awaiting connection.Optionalinterface?: null | stringZMQ_BINDTODEVICE
Binds the socket to the given network interface (Linux only). Allows to use Linux VRF, see: https://www.kernel.org/doc/Documentation/networking/vrf.txt. Requires the program to be ran as root or with
CAP_NET_RAW.Optionalipv6?: booleanZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
Optionallinger?: numberZMQ_LINGER
Determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with close().
OptionalloopbackFast ?: booleanPath ZMQ_LOOPBACK_FASTPATH
Enable faster TCP connections on loopback devices. An application can enable this option to reduce the latency and improve the performance of loopback operations on a TCP socket on Windows.
OptionalmaxMessage ?: numberSize ZMQ_MAXMSGSIZE
Limits the size of the inbound message. If a peer sends a message larger than the limit it is disconnected. Value of -1 means no limit.
OptionalmulticastHops ?: numberZMQ_MULTICAST_HOPS
Sets the time-to-live field in every multicast packet sent from this socket. The default is 1 which means that the multicast packets don't leave the local network.
OptionalmulticastMax ?: numberTransport Data Unit ZMQ_MULTICAST_MAXTPDU
Sets the maximum transport data unit size used for outbound multicast packets. This must be set at or below the minimum Maximum Transmission Unit (MTU) for all network paths over which multicast reception is required.
OptionalplainPassword ?: null | stringZMQ_PLAIN_PASSWORD
Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
OptionalplainServer ?: booleanZMQ_PLAIN_SERVER
Defines whether the socket will act as server for PLAIN security. A value of
truemeans the socket will act as PLAIN server. A value offalsemeans the socket will not act as PLAIN server, and its security role then depends on other option settings.OptionalplainUsername ?: null | stringZMQ_PLAIN_USERNAME
Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
Optionalrate?: numberZMQ_RATE
Maximum send or receive data rate for multicast transports such as
pgm.OptionalreceiveBuffer ?: numberSize ZMQ_RCVBUF
Underlying kernel receive buffer size in bytes. A value of -1 means leave the OS default unchanged.
OptionalreceiveHigh ?: numberWater Mark ZMQ_RCVHWM
The high water mark is a hard limit on the maximum number of incoming messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
OptionalreceiveTimeout ?: numberZMQ_RCVTIMEO
Sets the timeout receiving messages on the socket. If the value is 0, receive() will return a rejected promise immediately if there is no message to receive. If the value is -1, it will wait asynchronously until a message is available. For all other values, it will wait for a message for that amount of time before rejecting.
OptionalreconnectInterval ?: numberZMQ_RECONNECT_IVL
Period ØMQ shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. The value -1 means no reconnection.
OptionalreconnectMax ?: numberInterval ZMQ_RECONNECT_IVL_MAX
Maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled until reconnectMaxInterval is reached. This allows for exponential backoff strategy. Zero (the default) means no exponential backoff is performed and reconnect interval calculations are only based on reconnectInterval.
OptionalrecoveryInterval ?: numberZMQ_RECOVERY_IVL
Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
OptionalsendBuffer ?: numberSize ZMQ_SNDBUF
Underlying kernel transmit buffer size in bytes. A value of -1 means leave the OS default unchanged.
OptionalsendHigh ?: numberWater Mark ZMQ_SNDHWM
The high water mark is a hard limit on the maximum number of outgoing messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
OptionalsendTimeout ?: numberZMQ_SNDTIMEO
Sets the timeout for sending messages on the socket. If the value is 0, send() will return a rejected promise immediately if the message cannot be sent. If the value is -1, it will wait asynchronously until the message is sent. For all other values, it will try to send the message for that amount of time before rejecting.
OptionalsocksProxy ?: null | stringZMQ_SOCKS_PROXY
The SOCKS5 proxy address that shall be used by the socket for the TCP connection(s). Does not support SOCKS5 authentication. If the endpoints are domain names instead of addresses they shall not be resolved and they shall be forwarded unchanged to the SOCKS proxy service in the client connection request message (address type 0x03 domain name).
OptionaltcpAccept ?: null | stringFilter ZMQ_TCP_ACCEPT_FILTER
Assign a filter that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one filter is applied then new connection source IP should be matched. To clear all filters set to
null. Filter is a string with IPv6 or IPv4 CIDR.OptionaltcpKeepalive ?: numberZMQ_TCP_KEEPALIVE
Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepalive ?: numberCount ZMQ_TCP_KEEPALIVE_CNT
Overrides TCP_KEEPCNT socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepalive ?: numberIdle ZMQ_TCP_KEEPALIVE_IDLE
Overrides TCP_KEEPIDLE / TCP_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepalive ?: numberInterval ZMQ_TCP_KEEPALIVE_INTVL
Overrides TCP_KEEPINTVL socket option (if supported by the OS). The default value of -1 leaves it to the OS default.
OptionaltcpMax ?: numberRetransmit Timeout ZMQ_TCP_MAXRT
Sets how long before an unacknowledged TCP retransmit times out (if supported by the OS). The system normally attempts many TCP retransmits following an exponential backoff strategy. This means that after a network outage, it may take a long time before the session can be re-established. Setting this option allows the timeout to happen at a shorter interval.
OptionaltypeOf ?: numberService ZMQ_TOS
Sets the ToS fields (the Differentiated Services (DS) and Explicit Congestion Notification (ECN) field) of the IP header. The ToS field is typically used to specify a packet's priority. The availability of this option is dependent on intermediate network equipment that inspect the ToS field and provide a path for low-delay, high-throughput, highly-reliable service, etc.
OptionalvmciBuffer ?: numberMax Size ZMQ_VMCI_BUFFER_MAX_SIZE
Maximum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciBuffer ?: numberMin Size ZMQ_VMCI_BUFFER_MIN_SIZE
Minimum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciBuffer ?: numberSize ZMQ_VMCI_BUFFER_SIZE
The size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciConnect ?: numberTimeout ZMQ_VMCI_CONNECT_TIMEOUT
Connection timeout for the socket. For
vmci://transports only.OptionalzapDomain ?: null | stringZMQ_ZAP_DOMAIN
Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the default on all
tcp://connections), ZAP authentication only happens if you set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 for more details.OptionalzapEnforce ?: booleanDomain ZMQ_ZAP_ENFORCE_DOMAIN
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.
Returns Pair
Properties
affinity
ZMQ_AFFINITY
I/O thread affinity, which determines which threads from the ØMQ I/O thread pool associated with the socket's context shall handle newly created connections.
Note: This value is a bit mask, but values higher than Number.MAX_SAFE_INTEGER may not be represented accurately! This currently means that configurations beyond 52 threads are unreliable.
backlog
ZMQ_BACKLOG
Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.
Readonlyclosed
Whether this socket was previously closed with close().
connectTimeout
ZMQ_CONNECT_TIMEOUT
Sets how long to wait before timing-out a connect() system call. The connect() system call normally takes a long time before it returns a time out error. Setting this option allows the library to time out the call at an earlier interval.
Readonlycontext
Context that this socket belongs to.
curvePublicKey
ZMQ_CURVE_PUBLICKEY
Sets the socket's long term public key. You must set this on CURVE client sockets. A server socket does not need to know its own public key. You can create a new keypair with curveKeyPair().
curveSecretKey
ZMQ_CURVE_SECRETKEY
Sets the socket's long term secret key. You must set this on both CURVE client and server sockets. You can create a new keypair with curveKeyPair().
curveServer
ZMQ_CURVE_SERVER
Defines whether the socket will act as server for CURVE security. A value of true means the socket will act as CURVE server. A value of false means the socket will not act as CURVE server, and its security role then depends on other option settings.
curveServerKey
ZMQ_CURVE_SERVERKEY
Sets the socket's long term server key. This is the public key of the CURVE server socket. You must set this on CURVE client sockets. This key must have been generated together with the server's secret key. You can create a new keypair with curveKeyPair().
Readonlyevents
Event Observer for this socket. This starts up a ØMQ monitoring socket internally that receives all socket events.
gssapiPlainText
gssapiPrincipal
gssapiPrincipalNameType
gssapiServer
gssapiServicePrincipal
gssapiServicePrincipalNameType
handshakeInterval
ZMQ_HANDSHAKE_IVL
Handshaking is the exchange of socket configuration information (socket type, identity, security) that occurs when a connection is first opened (only for connection-oriented transports). If handshaking does not complete within the configured time, the connection shall be closed. The value 0 means no handshake time limit.
heartbeatInterval
ZMQ_HEARTBEAT_IVL
Interval in milliseconds between sending ZMTP heartbeats for the specified socket. If this option is greater than 0, then a PING ZMTP command will be sent after every interval.
heartbeatTimeout
ZMQ_HEARTBEAT_TIMEOUT
How long (in milliseconds) to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic. This option is only valid if heartbeatInterval is greater than 0. The connection will time out if there is no traffic received after sending the PING command. The received traffic does not have to be a PONG command - any received traffic will cancel the timeout.
heartbeatTimeToLive
ZMQ_HEARTBEAT_TTL
The timeout in milliseconds on the remote peer for ZMTP heartbeats. If this option is greater than 0, the remote side shall time out the connection if it does not receive any more traffic within the TTL period. This option does not have any effect if heartbeatInterval is 0. Internally, this value is rounded down to the nearest decisecond, any value less than 100 will have no effect.
immediate
ZMQ_IMMEDIATE
By default queues will fill on outgoing connections even if the connection has not completed. This can lead to "lost" messages on sockets with round-robin routing (Request, Push, Dealer). If this option is set to true, messages shall be queued only to completed connections. This will cause the socket to block if there are no other connections, but will prevent queues from filling on pipes awaiting connection.
interface
ZMQ_BINDTODEVICE
Binds the socket to the given network interface (Linux only). Allows to use Linux VRF, see: https://www.kernel.org/doc/Documentation/networking/vrf.txt. Requires the program to be ran as root or with CAP_NET_RAW.
ipv6
ZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
ReadonlylastEndpoint
ZMQ_LAST_ENDPOINT
The last endpoint bound for TCP and IPC transports.
linger
ZMQ_LINGER
Determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with close().
loopbackFastPath
ZMQ_LOOPBACK_FASTPATH
Enable faster TCP connections on loopback devices. An application can enable this option to reduce the latency and improve the performance of loopback operations on a TCP socket on Windows.
maxMessageSize
ZMQ_MAXMSGSIZE
Limits the size of the inbound message. If a peer sends a message larger than the limit it is disconnected. Value of -1 means no limit.
multicastHops
ZMQ_MULTICAST_HOPS
Sets the time-to-live field in every multicast packet sent from this socket. The default is 1 which means that the multicast packets don't leave the local network.
multicastMaxTransportDataUnit
ZMQ_MULTICAST_MAXTPDU
Sets the maximum transport data unit size used for outbound multicast packets. This must be set at or below the minimum Maximum Transmission Unit (MTU) for all network paths over which multicast reception is required.
plainPassword
ZMQ_PLAIN_PASSWORD
Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
plainServer
ZMQ_PLAIN_SERVER
Defines whether the socket will act as server for PLAIN security. A value of true means the socket will act as PLAIN server. A value of false means the socket will not act as PLAIN server, and its security role then depends on other option settings.
plainUsername
ZMQ_PLAIN_USERNAME
Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
rate
ZMQ_RATE
Maximum send or receive data rate for multicast transports such as pgm.
Readonlyreadable
Whether any messages are currently available. If true, the next call to Readable.receive() will immediately read a message from the socket. For sockets that cannot receive messsages this is always false.
receiveBufferSize
ZMQ_RCVBUF
Underlying kernel receive buffer size in bytes. A value of -1 means leave the OS default unchanged.
receiveHighWaterMark
ZMQ_RCVHWM
The high water mark is a hard limit on the maximum number of incoming messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
receiveTimeout
ZMQ_RCVTIMEO
Sets the timeout receiving messages on the socket. If the value is 0, receive() will return a rejected promise immediately if there is no message to receive. If the value is -1, it will wait asynchronously until a message is available. For all other values, it will wait for a message for that amount of time before rejecting.
reconnectInterval
ZMQ_RECONNECT_IVL
Period ØMQ shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. The value -1 means no reconnection.
reconnectMaxInterval
ZMQ_RECONNECT_IVL_MAX
Maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled until reconnectMaxInterval is reached. This allows for exponential backoff strategy. Zero (the default) means no exponential backoff is performed and reconnect interval calculations are only based on reconnectInterval.
recoveryInterval
ZMQ_RECOVERY_IVL
Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
ReadonlysecurityMechanism
| null
| "plain"
| "curve"
| "gssapi"
ZMQ_MECHANISM
Returns the current security mechanism for the socket, if any. The security mechanism is set implictly by using any of the relevant security options. The returned value is one of:
null- No security mechanism is used."plain"- The PLAIN mechanism defines a simple username/password mechanism that lets a server authenticate a client. PLAIN makes no attempt at security or confidentiality."curve"- The CURVE mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server. CURVE is intended for use on public networks."gssapi"- The GSSAPI mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server using the Generic Security Service Application Program Interface (GSSAPI). The GSSAPI mechanism can be used on both public and private networks.
sendBufferSize
ZMQ_SNDBUF
Underlying kernel transmit buffer size in bytes. A value of -1 means leave the OS default unchanged.
sendHighWaterMark
ZMQ_SNDHWM
The high water mark is a hard limit on the maximum number of outgoing messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
sendTimeout
ZMQ_SNDTIMEO
Sets the timeout for sending messages on the socket. If the value is 0, send() will return a rejected promise immediately if the message cannot be sent. If the value is -1, it will wait asynchronously until the message is sent. For all other values, it will try to send the message for that amount of time before rejecting.
socksProxy
ZMQ_SOCKS_PROXY
The SOCKS5 proxy address that shall be used by the socket for the TCP connection(s). Does not support SOCKS5 authentication. If the endpoints are domain names instead of addresses they shall not be resolved and they shall be forwarded unchanged to the SOCKS proxy service in the client connection request message (address type 0x03 domain name).
tcpAcceptFilter
ZMQ_TCP_ACCEPT_FILTER
Assign a filter that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one filter is applied then new connection source IP should be matched. To clear all filters set to null. Filter is a string with IPv6 or IPv4 CIDR.
tcpKeepalive
ZMQ_TCP_KEEPALIVE
Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveCount
ZMQ_TCP_KEEPALIVE_CNT
Overrides TCP_KEEPCNT socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveIdle
ZMQ_TCP_KEEPALIVE_IDLE
Overrides TCP_KEEPIDLE / TCP_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveInterval
ZMQ_TCP_KEEPALIVE_INTVL
Overrides TCP_KEEPINTVL socket option (if supported by the OS). The default value of -1 leaves it to the OS default.
tcpMaxRetransmitTimeout
ZMQ_TCP_MAXRT
Sets how long before an unacknowledged TCP retransmit times out (if supported by the OS). The system normally attempts many TCP retransmits following an exponential backoff strategy. This means that after a network outage, it may take a long time before the session can be re-established. Setting this option allows the timeout to happen at a shorter interval.
ReadonlythreadSafe
ZMQ_THREAD_SAFE
Whether or not the socket is threadsafe. Currently only DRAFT sockets is thread-safe.
Readonlytype
ZMQ_TYPE
Retrieve the socket type. This is fairly useless because you can test the socket class with e.g. socket instanceof Dealer.
typeOfService
ZMQ_TOS
Sets the ToS fields (the Differentiated Services (DS) and Explicit Congestion Notification (ECN) field) of the IP header. The ToS field is typically used to specify a packet's priority. The availability of this option is dependent on intermediate network equipment that inspect the ToS field and provide a path for low-delay, high-throughput, highly-reliable service, etc.
vmciBufferMaxSize
ZMQ_VMCI_BUFFER_MAX_SIZE
Maximum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferMinSize
ZMQ_VMCI_BUFFER_MIN_SIZE
Minimum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferSize
ZMQ_VMCI_BUFFER_SIZE
The size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciConnectTimeout
ZMQ_VMCI_CONNECT_TIMEOUT
Connection timeout for the socket. For vmci:// transports only.
Readonlywritable
Whether any messages can be queued for sending. If true, the next call to Writable.send() will immediately queue a message on the socket. For sockets that cannot send messsages this is always false.
zapDomain
ZMQ_ZAP_DOMAIN
Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the default on all tcp:// connections), ZAP authentication only happens if you set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 for more details.
zapEnforceDomain
ZMQ_ZAP_ENFORCE_DOMAIN
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.
Methods
[asyncIterator]
- [async
Iterator] (): AsyncIterator<Buffer[], undefined, undefined> Asynchronously iterate over messages becoming available on the socket. When the socket is closed with Socket.close(), the iterator will return. Returning early from the iterator will not close the socket unless it also goes out of scope.
for await (const [msg] of socket) {
// handle messages
} -Returns AsyncIterator<Buffer[], undefined, undefined>
bind
- bind(address): Promise<void>
Binds the socket to the given address. During bind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.You can use
*in place of a hostname to bind on all interfaces/addresses, and you can use*in place of a port to bind to a random port (which can be retrieved with lastEndpoint later).await socket.bind("tcp://127.0.0.1:3456")
await socket.bind("tcp://*:3456") // binds on all interfaces
await socket.bind("tcp://127.0.0.1:*") // binds on random port -Parameters
- address: string
Address to bind this socket to.
Returns Promise<void>
Resolved when the socket was successfully bound.
- address: string
close
- close(): void
Closes the socket and disposes of all resources. Any messages that are queued may be discarded or sent in the background depending on the linger setting.
After this method is called, it is no longer possible to call any other methods on this socket.
Sockets that go out of scope and have no Readable.receive() or Writable.send() operations in progress will automatically be closed. Therefore it is not necessary in most applications to call close() manually.
Calling this method on a socket that is already closed is a no-op.
Returns void
connect
disconnect
- disconnect(address): void
Disconnects a previously connected socket from the given address and returns immediately. Disonnection will happen asynchronously in the background.
socket.disconnect("tcp://127.0.0.1:3456") -Parameters
- address: string
The previously connected address to disconnect from.
Returns void
- address: string
ProtectedgetBoolOption
ProtectedgetInt32Option
ProtectedgetInt64Option
ProtectedgetStringOption
ProtectedgetUint32Option
ProtectedgetUint64Option
receive
- receive(): Promise<Buffer[]>
Waits for the next single or multipart message to become availeble on the socket. Reads a message immediately if possible. If no messages can be read, it will wait asynchonously. The promise will be resolved with an array containing the parts of the next message when available.
const [msg] = await socket.receive()
const [part1, part2] = await socket.receive() -Reading may fail (eventually) if the socket has been configured with a receiveTimeout.
A call to receive() is guaranteed to return with a resolved promise immediately if a message could be read from the socket directly.
Only one asynchronously blocking call to receive() can be in progress simultaneously. If you call receive() again on the same socket it will return a rejected promise with an
EBUSYerror. For example, if no messages can be read and noawaitis used:socket.receive() // -> pending promise until read is possible
socket.receive() // -> promise rejection with `EBUSY` error -Note: Due to the nature of Node.js and to avoid blocking the main thread, this method always attempts to read messages with the
ZMQ_DONTWAITflag. It polls asynchronously if reading is not currently possible. This means that all functionality related to timeouts and blocking behaviour is reimplemented in the Node.js bindings. Any differences in behaviour with the native ZMQ library is considered a bug.Returns Promise<Buffer[]>
Resolved with message parts that were successfully read.
send
- send(message, ...options): Promise<void>
Sends a single message or a multipart message on the socket. Queues the message immediately if possible, and returns a resolved promise. If the message cannot be queued because the high water mark has been reached, it will wait asynchronously. The promise will be resolved when the message was queued successfully.
await socket.send("hello world")
await socket.send(["hello", "world"]) -Queueing may fail eventually if the socket has been configured with a sendTimeout.
A call to send() is guaranteed to return with a resolved promise immediately if the message could be queued directly.
Only one asynchronously blocking call to send() may be executed simultaneously. If you call send() again on a socket that is in the mute state it will return a rejected promise with an
EBUSYerror.The reason for disallowing multiple send() calls simultaneously is that it could create an implicit queue of unsendable outgoing messages. This would circumvent the socket's sendHighWaterMark. Such an implementation could even exhaust all system memory and cause the Node.js process to abort.
For most application you should not notice this implementation detail. Only in rare occasions will a call to send() that does not resolve immediately be undesired. Here are some common scenarios:
If you wish to send a message, use
await send(...). ZeroMQ socket types have been carefully designed to give you the correct blocking behaviour on the chosen socket type in almost all cases:If sending is not possible, it is often better to wait than to continue as if nothing happened. For example, on a Request socket, you can only receive a reply once a message has been sent; so waiting until a message could be queued before continuing with the rest of the program (likely to read from the socket) is required.
Certain socket types (such as Router) will always allow queueing messages and
await send(...)won't delay any code that comes after. This makes sense for routers, since typically you don't want a single send operation to stop the handling of other incoming or outgoing messages.
If you wish to send on an occasionally blocking socket (for example on a Router with the Router.mandatory option set, or on a Dealer) and you're 100% certain that dropping a message is better than blocking, then you can set the sendTimeout option to
0to effectively force send() to always resolve immediately. Be prepared to catch exceptions if sending a message is not immediately possible.If you wish to send on a socket and messages should be queued before they are dropped, you should implement a simple queue in JavaScript. Such a queue is not provided by this library because most real world applications need to deal with undeliverable messages in more complex ways - for example, they might need to reply with a status message; or first retry delivery a certain number of times before giving up.
Parameters
- message: MessageLike | MessageLike[]
Single message or multipart message to queue for sending.
Rest...options: []Any options, if applicable to the socket type (DRAFT only).
Returns Promise<void>
Resolved when the message was successfully queued.
ProtectedsetBoolOption
ProtectedsetInt32Option
ProtectedsetInt64Option
ProtectedsetStringOption
ProtectedsetUint32Option
ProtectedsetUint64Option
unbind
- unbind(address): Promise<void>
Unbinds the socket to the given address. During unbind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.Parameters
- address: string
Address to unbind this socket from.
Returns Promise<void>
Resolved when the socket was successfully unbound.
- address: string
Class Pair
A Pair socket can only be connected to one other Pair at any one time. No message routing or filtering is performed on any messages.
When a Pair socket enters the mute state due to having reached the high water mark for the connected peer, or if no peer is connected, then any Writable.send() operations on the socket shall block until the peer becomes available for sending; messages are not discarded.
While Pair sockets can be used over transports other than inproc://, their inability to auto-reconnect coupled with the fact new incoming connections will be terminated while any previous connections (including ones in a closing state) exist makes them unsuitable for tcp:// in most cases.
Hierarchy (View Summary)
Index
Constructors
Properties
Methods
Constructors
constructor
- new Pair(
options?: {
affinity?: number;
backlog?: number;
connectTimeout?: number;
context?: Context;
curvePublicKey?: null | string;
curveSecretKey?: null | string;
curveServer?: boolean;
curveServerKey?: null | string;
gssapiPlainText?: boolean;
gssapiPrincipal?: null | string;
gssapiPrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
gssapiServer?: boolean;
gssapiServicePrincipal?: null | string;
gssapiServicePrincipalNameType?:
| "hostBased"
| "userName"
| "krb5Principal";
handshakeInterval?: number;
heartbeatInterval?: number;
heartbeatTimeout?: number;
heartbeatTimeToLive?: number;
immediate?: boolean;
interface?: null
| string;
ipv6?: boolean;
linger?: number;
loopbackFastPath?: boolean;
maxMessageSize?: number;
multicastHops?: number;
multicastMaxTransportDataUnit?: number;
plainPassword?: null | string;
plainServer?: boolean;
plainUsername?: null | string;
rate?: number;
receiveBufferSize?: number;
receiveHighWaterMark?: number;
receiveTimeout?: number;
reconnectInterval?: number;
reconnectMaxInterval?: number;
recoveryInterval?: number;
sendBufferSize?: number;
sendHighWaterMark?: number;
sendTimeout?: number;
socksProxy?: null | string;
tcpAcceptFilter?: null | string;
tcpKeepalive?: number;
tcpKeepaliveCount?: number;
tcpKeepaliveIdle?: number;
tcpKeepaliveInterval?: number;
tcpMaxRetransmitTimeout?: number;
typeOfService?: number;
vmciBufferMaxSize?: number;
vmciBufferMinSize?: number;
vmciBufferSize?: number;
vmciConnectTimeout?: number;
zapDomain?: null | string;
zapEnforceDomain?: boolean;
},
): Pair Parameters
Optionaloptions: {
affinity?: number;
backlog?: number;
connectTimeout?: number;
context?: Context;
curvePublicKey?: null | string;
curveSecretKey?: null | string;
curveServer?: boolean;
curveServerKey?: null | string;
gssapiPlainText?: boolean;
gssapiPrincipal?: null | string;
gssapiPrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
gssapiServer?: boolean;
gssapiServicePrincipal?: null | string;
gssapiServicePrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
handshakeInterval?: number;
heartbeatInterval?: number;
heartbeatTimeout?: number;
heartbeatTimeToLive?: number;
immediate?: boolean;
interface?: null | string;
ipv6?: boolean;
linger?: number;
loopbackFastPath?: boolean;
maxMessageSize?: number;
multicastHops?: number;
multicastMaxTransportDataUnit?: number;
plainPassword?: null | string;
plainServer?: boolean;
plainUsername?: null | string;
rate?: number;
receiveBufferSize?: number;
receiveHighWaterMark?: number;
receiveTimeout?: number;
reconnectInterval?: number;
reconnectMaxInterval?: number;
recoveryInterval?: number;
sendBufferSize?: number;
sendHighWaterMark?: number;
sendTimeout?: number;
socksProxy?: null | string;
tcpAcceptFilter?: null | string;
tcpKeepalive?: number;
tcpKeepaliveCount?: number;
tcpKeepaliveIdle?: number;
tcpKeepaliveInterval?: number;
tcpMaxRetransmitTimeout?: number;
typeOfService?: number;
vmciBufferMaxSize?: number;
vmciBufferMinSize?: number;
vmciBufferSize?: number;
vmciConnectTimeout?: number;
zapDomain?: null | string;
zapEnforceDomain?: boolean;
}Optionalaffinity?: numberZMQ_AFFINITY
I/O thread affinity, which determines which threads from the ØMQ I/O thread pool associated with the socket's context shall handle newly created connections.
Note: This value is a bit mask, but values higher than
Number.MAX_SAFE_INTEGERmay not be represented accurately! This currently means that configurations beyond 52 threads are unreliable.Optionalbacklog?: numberZMQ_BACKLOG
Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.
OptionalconnectTimeout?: numberZMQ_CONNECT_TIMEOUT
Sets how long to wait before timing-out a connect() system call. The connect() system call normally takes a long time before it returns a time out error. Setting this option allows the library to time out the call at an earlier interval.
Optionalcontext?: ContextOptionalcurvePublicKey?: null | stringZMQ_CURVE_PUBLICKEY
Sets the socket's long term public key. You must set this on CURVE client sockets. A server socket does not need to know its own public key. You can create a new keypair with curveKeyPair().
OptionalcurveSecretKey?: null | stringZMQ_CURVE_SECRETKEY
Sets the socket's long term secret key. You must set this on both CURVE client and server sockets. You can create a new keypair with curveKeyPair().
OptionalcurveServer?: booleanZMQ_CURVE_SERVER
Defines whether the socket will act as server for CURVE security. A value of
truemeans the socket will act as CURVE server. A value offalsemeans the socket will not act as CURVE server, and its security role then depends on other option settings.OptionalcurveServerKey?: null | stringZMQ_CURVE_SERVERKEY
Sets the socket's long term server key. This is the public key of the CURVE server socket. You must set this on CURVE client sockets. This key must have been generated together with the server's secret key. You can create a new keypair with curveKeyPair().
OptionalgssapiPlainText?: booleanOptionalgssapiPrincipal?: null | stringOptionalgssapiPrincipalNameType?: "hostBased" | "userName" | "krb5Principal"OptionalgssapiServer?: booleanOptionalgssapiServicePrincipal?: null | stringOptionalgssapiServicePrincipalNameType?: "hostBased" | "userName" | "krb5Principal"OptionalhandshakeInterval?: numberZMQ_HANDSHAKE_IVL
Handshaking is the exchange of socket configuration information (socket type, identity, security) that occurs when a connection is first opened (only for connection-oriented transports). If handshaking does not complete within the configured time, the connection shall be closed. The value 0 means no handshake time limit.
OptionalheartbeatInterval?: numberZMQ_HEARTBEAT_IVL
Interval in milliseconds between sending ZMTP heartbeats for the specified socket. If this option is greater than 0, then a PING ZMTP command will be sent after every interval.
OptionalheartbeatTimeout?: numberZMQ_HEARTBEAT_TIMEOUT
How long (in milliseconds) to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic. This option is only valid if heartbeatInterval is greater than 0. The connection will time out if there is no traffic received after sending the PING command. The received traffic does not have to be a PONG command - any received traffic will cancel the timeout.
OptionalheartbeatTimeToLive?: numberZMQ_HEARTBEAT_TTL
The timeout in milliseconds on the remote peer for ZMTP heartbeats. If this option is greater than 0, the remote side shall time out the connection if it does not receive any more traffic within the TTL period. This option does not have any effect if heartbeatInterval is 0. Internally, this value is rounded down to the nearest decisecond, any value less than 100 will have no effect.
Optionalimmediate?: booleanZMQ_IMMEDIATE
By default queues will fill on outgoing connections even if the connection has not completed. This can lead to "lost" messages on sockets with round-robin routing (Request, Push, Dealer). If this option is set to
true, messages shall be queued only to completed connections. This will cause the socket to block if there are no other connections, but will prevent queues from filling on pipes awaiting connection.Optionalinterface?: null | stringZMQ_BINDTODEVICE
Binds the socket to the given network interface (Linux only). Allows to use Linux VRF, see: https://www.kernel.org/doc/Documentation/networking/vrf.txt. Requires the program to be ran as root or with
CAP_NET_RAW.Optionalipv6?: booleanZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
Optionallinger?: numberZMQ_LINGER
Determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with close().
OptionalloopbackFastPath?: booleanZMQ_LOOPBACK_FASTPATH
Enable faster TCP connections on loopback devices. An application can enable this option to reduce the latency and improve the performance of loopback operations on a TCP socket on Windows.
OptionalmaxMessageSize?: numberZMQ_MAXMSGSIZE
Limits the size of the inbound message. If a peer sends a message larger than the limit it is disconnected. Value of -1 means no limit.
OptionalmulticastHops?: numberZMQ_MULTICAST_HOPS
Sets the time-to-live field in every multicast packet sent from this socket. The default is 1 which means that the multicast packets don't leave the local network.
OptionalmulticastMaxTransportDataUnit?: numberZMQ_MULTICAST_MAXTPDU
Sets the maximum transport data unit size used for outbound multicast packets. This must be set at or below the minimum Maximum Transmission Unit (MTU) for all network paths over which multicast reception is required.
OptionalplainPassword?: null | stringZMQ_PLAIN_PASSWORD
Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
OptionalplainServer?: booleanZMQ_PLAIN_SERVER
Defines whether the socket will act as server for PLAIN security. A value of
truemeans the socket will act as PLAIN server. A value offalsemeans the socket will not act as PLAIN server, and its security role then depends on other option settings.OptionalplainUsername?: null | stringZMQ_PLAIN_USERNAME
Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
Optionalrate?: numberZMQ_RATE
Maximum send or receive data rate for multicast transports such as
pgm.OptionalreceiveBufferSize?: numberZMQ_RCVBUF
Underlying kernel receive buffer size in bytes. A value of -1 means leave the OS default unchanged.
OptionalreceiveHighWaterMark?: numberZMQ_RCVHWM
The high water mark is a hard limit on the maximum number of incoming messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
OptionalreceiveTimeout?: numberZMQ_RCVTIMEO
Sets the timeout receiving messages on the socket. If the value is 0, receive() will return a rejected promise immediately if there is no message to receive. If the value is -1, it will wait asynchronously until a message is available. For all other values, it will wait for a message for that amount of time before rejecting.
OptionalreconnectInterval?: numberZMQ_RECONNECT_IVL
Period ØMQ shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. The value -1 means no reconnection.
OptionalreconnectMaxInterval?: numberZMQ_RECONNECT_IVL_MAX
Maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled until reconnectMaxInterval is reached. This allows for exponential backoff strategy. Zero (the default) means no exponential backoff is performed and reconnect interval calculations are only based on reconnectInterval.
OptionalrecoveryInterval?: numberZMQ_RECOVERY_IVL
Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
OptionalsendBufferSize?: numberZMQ_SNDBUF
Underlying kernel transmit buffer size in bytes. A value of -1 means leave the OS default unchanged.
OptionalsendHighWaterMark?: numberZMQ_SNDHWM
The high water mark is a hard limit on the maximum number of outgoing messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
OptionalsendTimeout?: numberZMQ_SNDTIMEO
Sets the timeout for sending messages on the socket. If the value is 0, send() will return a rejected promise immediately if the message cannot be sent. If the value is -1, it will wait asynchronously until the message is sent. For all other values, it will try to send the message for that amount of time before rejecting.
OptionalsocksProxy?: null | stringZMQ_SOCKS_PROXY
The SOCKS5 proxy address that shall be used by the socket for the TCP connection(s). Does not support SOCKS5 authentication. If the endpoints are domain names instead of addresses they shall not be resolved and they shall be forwarded unchanged to the SOCKS proxy service in the client connection request message (address type 0x03 domain name).
OptionaltcpAcceptFilter?: null | stringZMQ_TCP_ACCEPT_FILTER
Assign a filter that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one filter is applied then new connection source IP should be matched. To clear all filters set to
null. Filter is a string with IPv6 or IPv4 CIDR.OptionaltcpKeepalive?: numberZMQ_TCP_KEEPALIVE
Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepaliveCount?: numberZMQ_TCP_KEEPALIVE_CNT
Overrides TCP_KEEPCNT socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepaliveIdle?: numberZMQ_TCP_KEEPALIVE_IDLE
Overrides TCP_KEEPIDLE / TCP_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepaliveInterval?: numberZMQ_TCP_KEEPALIVE_INTVL
Overrides TCP_KEEPINTVL socket option (if supported by the OS). The default value of -1 leaves it to the OS default.
OptionaltcpMaxRetransmitTimeout?: numberZMQ_TCP_MAXRT
Sets how long before an unacknowledged TCP retransmit times out (if supported by the OS). The system normally attempts many TCP retransmits following an exponential backoff strategy. This means that after a network outage, it may take a long time before the session can be re-established. Setting this option allows the timeout to happen at a shorter interval.
OptionaltypeOfService?: numberZMQ_TOS
Sets the ToS fields (the Differentiated Services (DS) and Explicit Congestion Notification (ECN) field) of the IP header. The ToS field is typically used to specify a packet's priority. The availability of this option is dependent on intermediate network equipment that inspect the ToS field and provide a path for low-delay, high-throughput, highly-reliable service, etc.
OptionalvmciBufferMaxSize?: numberZMQ_VMCI_BUFFER_MAX_SIZE
Maximum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciBufferMinSize?: numberZMQ_VMCI_BUFFER_MIN_SIZE
Minimum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciBufferSize?: numberZMQ_VMCI_BUFFER_SIZE
The size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciConnectTimeout?: numberZMQ_VMCI_CONNECT_TIMEOUT
Connection timeout for the socket. For
vmci://transports only.OptionalzapDomain?: null | stringZMQ_ZAP_DOMAIN
Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the default on all
tcp://connections), ZAP authentication only happens if you set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 for more details.OptionalzapEnforceDomain?: booleanZMQ_ZAP_ENFORCE_DOMAIN
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.
Returns Pair
Properties
affinity
ZMQ_AFFINITY
I/O thread affinity, which determines which threads from the ØMQ I/O thread pool associated with the socket's context shall handle newly created connections.
Note: This value is a bit mask, but values higher than Number.MAX_SAFE_INTEGER may not be represented accurately! This currently means that configurations beyond 52 threads are unreliable.
backlog
ZMQ_BACKLOG
Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.
Readonlyclosed
Whether this socket was previously closed with close().
connectTimeout
ZMQ_CONNECT_TIMEOUT
Sets how long to wait before timing-out a connect() system call. The connect() system call normally takes a long time before it returns a time out error. Setting this option allows the library to time out the call at an earlier interval.
Readonlycontext
Context that this socket belongs to.
curvePublicKey
ZMQ_CURVE_PUBLICKEY
Sets the socket's long term public key. You must set this on CURVE client sockets. A server socket does not need to know its own public key. You can create a new keypair with curveKeyPair().
curveSecretKey
ZMQ_CURVE_SECRETKEY
Sets the socket's long term secret key. You must set this on both CURVE client and server sockets. You can create a new keypair with curveKeyPair().
curveServer
ZMQ_CURVE_SERVER
Defines whether the socket will act as server for CURVE security. A value of true means the socket will act as CURVE server. A value of false means the socket will not act as CURVE server, and its security role then depends on other option settings.
curveServerKey
ZMQ_CURVE_SERVERKEY
Sets the socket's long term server key. This is the public key of the CURVE server socket. You must set this on CURVE client sockets. This key must have been generated together with the server's secret key. You can create a new keypair with curveKeyPair().
Readonlyevents
Event Observer for this socket. This starts up a ØMQ monitoring socket internally that receives all socket events.
gssapiPlainText
gssapiPrincipal
gssapiPrincipalNameType
gssapiServer
gssapiServicePrincipal
gssapiServicePrincipalNameType
handshakeInterval
ZMQ_HANDSHAKE_IVL
Handshaking is the exchange of socket configuration information (socket type, identity, security) that occurs when a connection is first opened (only for connection-oriented transports). If handshaking does not complete within the configured time, the connection shall be closed. The value 0 means no handshake time limit.
heartbeatInterval
ZMQ_HEARTBEAT_IVL
Interval in milliseconds between sending ZMTP heartbeats for the specified socket. If this option is greater than 0, then a PING ZMTP command will be sent after every interval.
heartbeatTimeout
ZMQ_HEARTBEAT_TIMEOUT
How long (in milliseconds) to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic. This option is only valid if heartbeatInterval is greater than 0. The connection will time out if there is no traffic received after sending the PING command. The received traffic does not have to be a PONG command - any received traffic will cancel the timeout.
heartbeatTimeToLive
ZMQ_HEARTBEAT_TTL
The timeout in milliseconds on the remote peer for ZMTP heartbeats. If this option is greater than 0, the remote side shall time out the connection if it does not receive any more traffic within the TTL period. This option does not have any effect if heartbeatInterval is 0. Internally, this value is rounded down to the nearest decisecond, any value less than 100 will have no effect.
immediate
ZMQ_IMMEDIATE
By default queues will fill on outgoing connections even if the connection has not completed. This can lead to "lost" messages on sockets with round-robin routing (Request, Push, Dealer). If this option is set to true, messages shall be queued only to completed connections. This will cause the socket to block if there are no other connections, but will prevent queues from filling on pipes awaiting connection.
interface
ZMQ_BINDTODEVICE
Binds the socket to the given network interface (Linux only). Allows to use Linux VRF, see: https://www.kernel.org/doc/Documentation/networking/vrf.txt. Requires the program to be ran as root or with CAP_NET_RAW.
ipv6
ZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
ReadonlylastEndpoint
ZMQ_LAST_ENDPOINT
The last endpoint bound for TCP and IPC transports.
linger
ZMQ_LINGER
Determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with close().
loopbackFastPath
ZMQ_LOOPBACK_FASTPATH
Enable faster TCP connections on loopback devices. An application can enable this option to reduce the latency and improve the performance of loopback operations on a TCP socket on Windows.
maxMessageSize
ZMQ_MAXMSGSIZE
Limits the size of the inbound message. If a peer sends a message larger than the limit it is disconnected. Value of -1 means no limit.
multicastHops
ZMQ_MULTICAST_HOPS
Sets the time-to-live field in every multicast packet sent from this socket. The default is 1 which means that the multicast packets don't leave the local network.
multicastMaxTransportDataUnit
ZMQ_MULTICAST_MAXTPDU
Sets the maximum transport data unit size used for outbound multicast packets. This must be set at or below the minimum Maximum Transmission Unit (MTU) for all network paths over which multicast reception is required.
plainPassword
ZMQ_PLAIN_PASSWORD
Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
plainServer
ZMQ_PLAIN_SERVER
Defines whether the socket will act as server for PLAIN security. A value of true means the socket will act as PLAIN server. A value of false means the socket will not act as PLAIN server, and its security role then depends on other option settings.
plainUsername
ZMQ_PLAIN_USERNAME
Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
rate
ZMQ_RATE
Maximum send or receive data rate for multicast transports such as pgm.
Readonlyreadable
Whether any messages are currently available. If true, the next call to Readable.receive() will immediately read a message from the socket. For sockets that cannot receive messsages this is always false.
receiveBufferSize
ZMQ_RCVBUF
Underlying kernel receive buffer size in bytes. A value of -1 means leave the OS default unchanged.
receiveHighWaterMark
ZMQ_RCVHWM
The high water mark is a hard limit on the maximum number of incoming messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
receiveTimeout
ZMQ_RCVTIMEO
Sets the timeout receiving messages on the socket. If the value is 0, receive() will return a rejected promise immediately if there is no message to receive. If the value is -1, it will wait asynchronously until a message is available. For all other values, it will wait for a message for that amount of time before rejecting.
reconnectInterval
ZMQ_RECONNECT_IVL
Period ØMQ shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. The value -1 means no reconnection.
reconnectMaxInterval
ZMQ_RECONNECT_IVL_MAX
Maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled until reconnectMaxInterval is reached. This allows for exponential backoff strategy. Zero (the default) means no exponential backoff is performed and reconnect interval calculations are only based on reconnectInterval.
recoveryInterval
ZMQ_RECOVERY_IVL
Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
ReadonlysecurityMechanism
ZMQ_MECHANISM
Returns the current security mechanism for the socket, if any. The security mechanism is set implictly by using any of the relevant security options. The returned value is one of:
null- No security mechanism is used."plain"- The PLAIN mechanism defines a simple username/password mechanism that lets a server authenticate a client. PLAIN makes no attempt at security or confidentiality."curve"- The CURVE mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server. CURVE is intended for use on public networks."gssapi"- The GSSAPI mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server using the Generic Security Service Application Program Interface (GSSAPI). The GSSAPI mechanism can be used on both public and private networks.
sendBufferSize
ZMQ_SNDBUF
Underlying kernel transmit buffer size in bytes. A value of -1 means leave the OS default unchanged.
sendHighWaterMark
ZMQ_SNDHWM
The high water mark is a hard limit on the maximum number of outgoing messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
sendTimeout
ZMQ_SNDTIMEO
Sets the timeout for sending messages on the socket. If the value is 0, send() will return a rejected promise immediately if the message cannot be sent. If the value is -1, it will wait asynchronously until the message is sent. For all other values, it will try to send the message for that amount of time before rejecting.
socksProxy
ZMQ_SOCKS_PROXY
The SOCKS5 proxy address that shall be used by the socket for the TCP connection(s). Does not support SOCKS5 authentication. If the endpoints are domain names instead of addresses they shall not be resolved and they shall be forwarded unchanged to the SOCKS proxy service in the client connection request message (address type 0x03 domain name).
tcpAcceptFilter
ZMQ_TCP_ACCEPT_FILTER
Assign a filter that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one filter is applied then new connection source IP should be matched. To clear all filters set to null. Filter is a string with IPv6 or IPv4 CIDR.
tcpKeepalive
ZMQ_TCP_KEEPALIVE
Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveCount
ZMQ_TCP_KEEPALIVE_CNT
Overrides TCP_KEEPCNT socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveIdle
ZMQ_TCP_KEEPALIVE_IDLE
Overrides TCP_KEEPIDLE / TCP_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveInterval
ZMQ_TCP_KEEPALIVE_INTVL
Overrides TCP_KEEPINTVL socket option (if supported by the OS). The default value of -1 leaves it to the OS default.
tcpMaxRetransmitTimeout
ZMQ_TCP_MAXRT
Sets how long before an unacknowledged TCP retransmit times out (if supported by the OS). The system normally attempts many TCP retransmits following an exponential backoff strategy. This means that after a network outage, it may take a long time before the session can be re-established. Setting this option allows the timeout to happen at a shorter interval.
ReadonlythreadSafe
ZMQ_THREAD_SAFE
Whether or not the socket is threadsafe. Currently only DRAFT sockets is thread-safe.
Readonlytype
ZMQ_TYPE
Retrieve the socket type. This is fairly useless because you can test the socket class with e.g. socket instanceof Dealer.
typeOfService
ZMQ_TOS
Sets the ToS fields (the Differentiated Services (DS) and Explicit Congestion Notification (ECN) field) of the IP header. The ToS field is typically used to specify a packet's priority. The availability of this option is dependent on intermediate network equipment that inspect the ToS field and provide a path for low-delay, high-throughput, highly-reliable service, etc.
vmciBufferMaxSize
ZMQ_VMCI_BUFFER_MAX_SIZE
Maximum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferMinSize
ZMQ_VMCI_BUFFER_MIN_SIZE
Minimum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferSize
ZMQ_VMCI_BUFFER_SIZE
The size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciConnectTimeout
ZMQ_VMCI_CONNECT_TIMEOUT
Connection timeout for the socket. For vmci:// transports only.
Readonlywritable
Whether any messages can be queued for sending. If true, the next call to Writable.send() will immediately queue a message on the socket. For sockets that cannot send messsages this is always false.
zapDomain
ZMQ_ZAP_DOMAIN
Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the default on all tcp:// connections), ZAP authentication only happens if you set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 for more details.
zapEnforceDomain
ZMQ_ZAP_ENFORCE_DOMAIN
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.
Methods
[asyncIterator]
- "[asyncIterator]"(): AsyncIterator<Buffer[]>
Asynchronously iterate over messages becoming available on the socket. When the socket is closed with Socket.close(), the iterator will return. Returning early from the iterator will not close the socket unless it also goes out of scope.
for await (const [msg] of socket) {
// handle messages
} +Returns AsyncIterator<Buffer[]>
bind
- bind(address: string): Promise<void>
Binds the socket to the given address. During bind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.You can use
*in place of a hostname to bind on all interfaces/addresses, and you can use*in place of a port to bind to a random port (which can be retrieved with lastEndpoint later).await socket.bind("tcp://127.0.0.1:3456")
await socket.bind("tcp://*:3456") // binds on all interfaces
await socket.bind("tcp://127.0.0.1:*") // binds on random port +Parameters
- address: string
Address to bind this socket to.
Returns Promise<void>
Resolved when the socket was successfully bound.
- address: string
bindSync
- bindSync(address: string): void
Binds the socket to the given address. During bind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.You can use
*in place of a hostname to bind on all interfaces/addresses, and you can use*in place of a port to bind to a random port (which can be retrieved with lastEndpoint later).socket.bindSync("tcp://127.0.0.1:3456")
socket.bindSync("tcp://*:3456") // binds on all interfaces
socket.bindSync("tcp://127.0.0.1:*") // binds on random port +Parameters
- address: string
Address to bind this socket to.
Returns void
Resolved when the socket was successfully bound.
- address: string
close
- close(): void
Closes the socket and disposes of all resources. Any messages that are queued may be discarded or sent in the background depending on the linger setting.
After this method is called, it is no longer possible to call any other methods on this socket.
Sockets that go out of scope and have no Readable.receive() or Writable.send() operations in progress will automatically be closed. Therefore it is not necessary in most applications to call close() manually.
Calling this method on a socket that is already closed is a no-op.
Returns void
connect
disconnect
- disconnect(address: string): void
Disconnects a previously connected socket from the given address and returns immediately. Disonnection will happen asynchronously in the background.
socket.disconnect("tcp://127.0.0.1:3456") +Parameters
- address: string
The previously connected address to disconnect from.
Returns void
- address: string
ProtectedgetBoolOption
ProtectedgetInt32Option
ProtectedgetInt64Option
ProtectedgetStringOption
ProtectedgetUint32Option
ProtectedgetUint64Option
receive
- receive(): Promise<Buffer[]>
Waits for the next single or multipart message to become availeble on the socket. Reads a message immediately if possible. If no messages can be read, it will wait asynchonously. The promise will be resolved with an array containing the parts of the next message when available.
const [msg] = await socket.receive()
const [part1, part2] = await socket.receive() +Reading may fail (eventually) if the socket has been configured with a receiveTimeout.
A call to receive() is guaranteed to return with a resolved promise immediately if a message could be read from the socket directly.
Only one asynchronously blocking call to receive() can be in progress simultaneously. If you call receive() again on the same socket it will return a rejected promise with an
EBUSYerror. For example, if no messages can be read and noawaitis used:socket.receive() // -> pending promise until read is possible
socket.receive() // -> promise rejection with `EBUSY` error +Note: Due to the nature of Node.js and to avoid blocking the main thread, this method always attempts to read messages with the
ZMQ_DONTWAITflag. It polls asynchronously if reading is not currently possible. This means that all functionality related to timeouts and blocking behaviour is reimplemented in the Node.js bindings. Any differences in behaviour with the native ZMQ library is considered a bug.Returns Promise<Buffer[]>
Resolved with message parts that were successfully read.
send
- send(message: MessageLike | MessageLike[], ...options: []): Promise<void>
Sends a single message or a multipart message on the socket. Queues the message immediately if possible, and returns a resolved promise. If the message cannot be queued because the high water mark has been reached, it will wait asynchronously. The promise will be resolved when the message was queued successfully.
await socket.send("hello world")
await socket.send(["hello", "world"]) +Queueing may fail eventually if the socket has been configured with a sendTimeout.
A call to send() is guaranteed to return with a resolved promise immediately if the message could be queued directly.
Only one asynchronously blocking call to send() may be executed simultaneously. If you call send() again on a socket that is in the mute state it will return a rejected promise with an
EBUSYerror.The reason for disallowing multiple send() calls simultaneously is that it could create an implicit queue of unsendable outgoing messages. This would circumvent the socket's sendHighWaterMark. Such an implementation could even exhaust all system memory and cause the Node.js process to abort.
For most application you should not notice this implementation detail. Only in rare occasions will a call to send() that does not resolve immediately be undesired. Here are some common scenarios:
If you wish to send a message, use
await send(...). ZeroMQ socket types have been carefully designed to give you the correct blocking behaviour on the chosen socket type in almost all cases:If sending is not possible, it is often better to wait than to continue as if nothing happened. For example, on a Request socket, you can only receive a reply once a message has been sent; so waiting until a message could be queued before continuing with the rest of the program (likely to read from the socket) is required.
Certain socket types (such as Router) will always allow queueing messages and
await send(...)won't delay any code that comes after. This makes sense for routers, since typically you don't want a single send operation to stop the handling of other incoming or outgoing messages.
If you wish to send on an occasionally blocking socket (for example on a Router with the Router.mandatory option set, or on a Dealer) and you're 100% certain that dropping a message is better than blocking, then you can set the sendTimeout option to
0to effectively force send() to always resolve immediately. Be prepared to catch exceptions if sending a message is not immediately possible.If you wish to send on a socket and messages should be queued before they are dropped, you should implement a simple queue in JavaScript. Such a queue is not provided by this library because most real world applications need to deal with undeliverable messages in more complex ways - for example, they might need to reply with a status message; or first retry delivery a certain number of times before giving up.
Parameters
- message: MessageLike | MessageLike[]
Single message or multipart message to queue for sending.
- ...options: []
Any options, if applicable to the socket type (DRAFT only).
Returns Promise<void>
Resolved when the message was successfully queued.
ProtectedsetBoolOption
ProtectedsetInt32Option
ProtectedsetInt64Option
ProtectedsetStringOption
ProtectedsetUint32Option
ProtectedsetUint64Option
unbind
- unbind(address: string): Promise<void>
Unbinds the socket to the given address. During unbind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.Parameters
- address: string
Address to unbind this socket from.
Returns Promise<void>
Resolved when the socket was successfully unbound.
- address: string
unbindSync
- unbindSync(address: string): void
Unbinds the socket to the given address. During unbind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.Parameters
- address: string
Address to unbind this socket from.
Returns void
Resolved when the socket was successfully unbound.
- address: string
Class Proxy<F, B>
Proxy messages between two ØMQ sockets. The proxy connects a front-end socket to a back-end socket. Conceptually, data flows from front-end to back-end. Depending on the socket types, replies may flow in the opposite direction. The direction is conceptual only; the proxy is fully symmetric and there is no technical difference between front-end and back-end.
// Proxy between a router/dealer socket for 5 seconds.
const proxy = new Proxy(new Router, new Dealer)
await proxy.frontEnd.bind("tcp://*:3001")
await proxy.backEnd.bind("tcp://*:3002")
setTimeout(() => proxy.terminate(), 5000)
await proxy.run()
-Review the ØMQ documentation for an overview of some example applications of a proxy.
Type Parameters
Properties
ReadonlybackEnd
Returns the original back-end socket.
ReadonlyfrontEnd
Returns the original front-end socket.
Methods
pause
- pause(): void
Temporarily suspends any proxy activity. Resume activity with resume().
Returns void
resume
- resume(): void
Resumes proxy activity after suspending it with pause().
Returns void
run
- run(): Promise<void>
Starts the proxy loop in a worker thread and waits for its termination. Before starting, you must set any socket options, and connect or bind both front-end and back-end sockets.
On termination the front-end and back-end sockets will be closed automatically.
Returns Promise<void>
Resolved when the proxy has terminated.
terminate
- terminate(): void
Gracefully shuts down the proxy. The front-end and back-end sockets will be closed automatically. There might be a slight delay between terminating and the run() method resolving.
Returns void
Class Proxy<F, B>
Proxy messages between two ØMQ sockets. The proxy connects a front-end socket to a back-end socket. Conceptually, data flows from front-end to back-end. Depending on the socket types, replies may flow in the opposite direction. The direction is conceptual only; the proxy is fully symmetric and there is no technical difference between front-end and back-end.
// Proxy between a router/dealer socket for 5 seconds.
const proxy = new Proxy(new Router, new Dealer)
await proxy.frontEnd.bind("tcp://*:3001")
await proxy.backEnd.bind("tcp://*:3002")
setTimeout(() => proxy.terminate(), 5000)
await proxy.run()
+Review the ØMQ documentation for an overview of some example applications of a proxy.
Type Parameters
Constructors
constructor
- new Proxy<F extends Socket<F> = Socket, B extends Socket<B> = Socket>(
frontEnd: F,
backEnd: B,
): Proxy<F, B> Creates a new ØMQ proxy. Proxying will start between the front-end and back-end sockets when run() is called after both sockets have been bound or connected.
Type Parameters
Returns Proxy<F, B>
Properties
ReadonlybackEnd
Returns the original back-end socket.
ReadonlyfrontEnd
Returns the original front-end socket.
Methods
pause
- pause(): void
Temporarily suspends any proxy activity. Resume activity with resume().
Returns void
resume
- resume(): void
Resumes proxy activity after suspending it with pause().
Returns void
run
- run(): Promise<void>
Starts the proxy loop in a worker thread and waits for its termination. Before starting, you must set any socket options, and connect or bind both front-end and back-end sockets.
On termination the front-end and back-end sockets will be closed automatically.
Returns Promise<void>
Resolved when the proxy has terminated.
terminate
- terminate(): void
Gracefully shuts down the proxy. The front-end and back-end sockets will be closed automatically. There might be a slight delay between terminating and the run() method resolving.
Returns void
Class Publisher
A Publisher socket is used to distribute data to Subscribers. Messages sent are distributed in a fan out fashion to all connected peers. This socket cannot receive messages.
When a Publisher enters the mute state due to having reached the high water mark for a connected Subscriber, then any messages that would be sent to the subscriber in question shall instead be dropped until the mute state ends. The Writable.send() method will never block.
Hierarchy (view full)
Index
Constructors
Properties
Methods
Constructors
constructor
- new
Publisher (options?): Publisher Parameters
Optionaloptions: {
affinity?: number;
backlog?: number;
conflate?: boolean;
connectTimeout?: number;
context?: Context;
curvePublicKey?: null | string;
curveSecretKey?: null | string;
curveServer?: boolean;
curveServerKey?: null | string;
gssapiPlainText?: boolean;
gssapiPrincipal?: null | string;
gssapiPrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
gssapiServer?: boolean;
gssapiServicePrincipal?: null | string;
gssapiServicePrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
handshakeInterval?: number;
heartbeatInterval?: number;
heartbeatTimeout?: number;
heartbeatTimeToLive?: number;
immediate?: boolean;
interface?: null | string;
invertMatching?: boolean;
ipv6?: boolean;
linger?: number;
loopbackFastPath?: boolean;
maxMessageSize?: number;
multicastHops?: number;
multicastMaxTransportDataUnit?: number;
noDrop?: boolean;
plainPassword?: null | string;
plainServer?: boolean;
plainUsername?: null | string;
rate?: number;
reconnectInterval?: number;
reconnectMaxInterval?: number;
recoveryInterval?: number;
sendBufferSize?: number;
sendHighWaterMark?: number;
sendTimeout?: number;
socksProxy?: null | string;
tcpAcceptFilter?: null | string;
tcpKeepalive?: number;
tcpKeepaliveCount?: number;
tcpKeepaliveIdle?: number;
tcpKeepaliveInterval?: number;
tcpMaxRetransmitTimeout?: number;
typeOfService?: number;
vmciBufferMaxSize?: number;
vmciBufferMinSize?: number;
vmciBufferSize?: number;
vmciConnectTimeout?: number;
zapDomain?: null | string;
zapEnforceDomain?: boolean;
}Optionalaffinity?: numberZMQ_AFFINITY
I/O thread affinity, which determines which threads from the ØMQ I/O thread pool associated with the socket's context shall handle newly created connections.
Note: This value is a bit mask, but values higher than
Number.MAX_SAFE_INTEGERmay not be represented accurately! This currently means that configurations beyond 52 threads are unreliable.Optionalbacklog?: numberZMQ_BACKLOG
Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.
Optionalconflate?: booleanZMQ_CONFLATE
If set to
true, a socket shall keep only one message in its inbound/outbound queue: the last message to be received/sent. Ignores any high water mark options. Does not support multi-part messages - in particular, only one part of it is kept in the socket internal queue.OptionalconnectTimeout ?: numberZMQ_CONNECT_TIMEOUT
Sets how long to wait before timing-out a connect() system call. The connect() system call normally takes a long time before it returns a time out error. Setting this option allows the library to time out the call at an earlier interval.
Optionalcontext?: ContextOptionalcurvePublic ?: null | stringKey ZMQ_CURVE_PUBLICKEY
Sets the socket's long term public key. You must set this on CURVE client sockets. A server socket does not need to know its own public key. You can create a new keypair with curveKeyPair().
OptionalcurveSecret ?: null | stringKey ZMQ_CURVE_SECRETKEY
Sets the socket's long term secret key. You must set this on both CURVE client and server sockets. You can create a new keypair with curveKeyPair().
OptionalcurveServer ?: booleanZMQ_CURVE_SERVER
Defines whether the socket will act as server for CURVE security. A value of
truemeans the socket will act as CURVE server. A value offalsemeans the socket will not act as CURVE server, and its security role then depends on other option settings.OptionalcurveServer ?: null | stringKey ZMQ_CURVE_SERVERKEY
Sets the socket's long term server key. This is the public key of the CURVE server socket. You must set this on CURVE client sockets. This key must have been generated together with the server's secret key. You can create a new keypair with curveKeyPair().
OptionalgssapiPlain ?: booleanText OptionalgssapiPrincipal ?: null | stringOptionalgssapiPrincipal ?: "hostBased" | "userName" | "krb5Principal"Name Type OptionalgssapiServer ?: booleanOptionalgssapiService ?: null | stringPrincipal OptionalgssapiService ?: "hostBased" | "userName" | "krb5Principal"Principal Name Type OptionalhandshakeInterval ?: numberZMQ_HANDSHAKE_IVL
Handshaking is the exchange of socket configuration information (socket type, identity, security) that occurs when a connection is first opened (only for connection-oriented transports). If handshaking does not complete within the configured time, the connection shall be closed. The value 0 means no handshake time limit.
OptionalheartbeatInterval ?: numberZMQ_HEARTBEAT_IVL
Interval in milliseconds between sending ZMTP heartbeats for the specified socket. If this option is greater than 0, then a PING ZMTP command will be sent after every interval.
OptionalheartbeatTimeout ?: numberZMQ_HEARTBEAT_TIMEOUT
How long (in milliseconds) to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic. This option is only valid if heartbeatInterval is greater than 0. The connection will time out if there is no traffic received after sending the PING command. The received traffic does not have to be a PONG command - any received traffic will cancel the timeout.
OptionalheartbeatTime ?: numberTo Live ZMQ_HEARTBEAT_TTL
The timeout in milliseconds on the remote peer for ZMTP heartbeats. If this option is greater than 0, the remote side shall time out the connection if it does not receive any more traffic within the TTL period. This option does not have any effect if heartbeatInterval is 0. Internally, this value is rounded down to the nearest decisecond, any value less than 100 will have no effect.
Optionalimmediate?: booleanZMQ_IMMEDIATE
By default queues will fill on outgoing connections even if the connection has not completed. This can lead to "lost" messages on sockets with round-robin routing (Request, Push, Dealer). If this option is set to
true, messages shall be queued only to completed connections. This will cause the socket to block if there are no other connections, but will prevent queues from filling on pipes awaiting connection.Optionalinterface?: null | stringZMQ_BINDTODEVICE
Binds the socket to the given network interface (Linux only). Allows to use Linux VRF, see: https://www.kernel.org/doc/Documentation/networking/vrf.txt. Requires the program to be ran as root or with
CAP_NET_RAW.OptionalinvertMatching ?: booleanZMQ_INVERT_MATCHING
Causes messages to be sent to all connected sockets except those subscribed to a prefix that matches the message.
All Subscriber sockets connecting to the Publisher must also have the option set to
true. Failure to do so will have the Subscriber sockets reject everything the Publisher socket sends them.Optionalipv6?: booleanZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
Optionallinger?: numberZMQ_LINGER
Determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with close().
OptionalloopbackFast ?: booleanPath ZMQ_LOOPBACK_FASTPATH
Enable faster TCP connections on loopback devices. An application can enable this option to reduce the latency and improve the performance of loopback operations on a TCP socket on Windows.
OptionalmaxMessage ?: numberSize ZMQ_MAXMSGSIZE
Limits the size of the inbound message. If a peer sends a message larger than the limit it is disconnected. Value of -1 means no limit.
OptionalmulticastHops ?: numberZMQ_MULTICAST_HOPS
Sets the time-to-live field in every multicast packet sent from this socket. The default is 1 which means that the multicast packets don't leave the local network.
OptionalmulticastMax ?: numberTransport Data Unit ZMQ_MULTICAST_MAXTPDU
Sets the maximum transport data unit size used for outbound multicast packets. This must be set at or below the minimum Maximum Transmission Unit (MTU) for all network paths over which multicast reception is required.
OptionalnoDrop ?: booleanZMQ_XPUB_NODROP
Sets the socket behaviour to return an error if the high water mark is reached and the message could not be send. The default is to drop the message silently when the peer high water mark is reached.
OptionalplainPassword ?: null | stringZMQ_PLAIN_PASSWORD
Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
OptionalplainServer ?: booleanZMQ_PLAIN_SERVER
Defines whether the socket will act as server for PLAIN security. A value of
truemeans the socket will act as PLAIN server. A value offalsemeans the socket will not act as PLAIN server, and its security role then depends on other option settings.OptionalplainUsername ?: null | stringZMQ_PLAIN_USERNAME
Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
Optionalrate?: numberZMQ_RATE
Maximum send or receive data rate for multicast transports such as
pgm.OptionalreconnectInterval ?: numberZMQ_RECONNECT_IVL
Period ØMQ shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. The value -1 means no reconnection.
OptionalreconnectMax ?: numberInterval ZMQ_RECONNECT_IVL_MAX
Maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled until reconnectMaxInterval is reached. This allows for exponential backoff strategy. Zero (the default) means no exponential backoff is performed and reconnect interval calculations are only based on reconnectInterval.
OptionalrecoveryInterval ?: numberZMQ_RECOVERY_IVL
Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
OptionalsendBuffer ?: numberSize ZMQ_SNDBUF
Underlying kernel transmit buffer size in bytes. A value of -1 means leave the OS default unchanged.
OptionalsendHigh ?: numberWater Mark ZMQ_SNDHWM
The high water mark is a hard limit on the maximum number of outgoing messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
OptionalsendTimeout ?: numberZMQ_SNDTIMEO
Sets the timeout for sending messages on the socket. If the value is 0, send() will return a rejected promise immediately if the message cannot be sent. If the value is -1, it will wait asynchronously until the message is sent. For all other values, it will try to send the message for that amount of time before rejecting.
OptionalsocksProxy ?: null | stringZMQ_SOCKS_PROXY
The SOCKS5 proxy address that shall be used by the socket for the TCP connection(s). Does not support SOCKS5 authentication. If the endpoints are domain names instead of addresses they shall not be resolved and they shall be forwarded unchanged to the SOCKS proxy service in the client connection request message (address type 0x03 domain name).
OptionaltcpAccept ?: null | stringFilter ZMQ_TCP_ACCEPT_FILTER
Assign a filter that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one filter is applied then new connection source IP should be matched. To clear all filters set to
null. Filter is a string with IPv6 or IPv4 CIDR.OptionaltcpKeepalive ?: numberZMQ_TCP_KEEPALIVE
Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepalive ?: numberCount ZMQ_TCP_KEEPALIVE_CNT
Overrides TCP_KEEPCNT socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepalive ?: numberIdle ZMQ_TCP_KEEPALIVE_IDLE
Overrides TCP_KEEPIDLE / TCP_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepalive ?: numberInterval ZMQ_TCP_KEEPALIVE_INTVL
Overrides TCP_KEEPINTVL socket option (if supported by the OS). The default value of -1 leaves it to the OS default.
OptionaltcpMax ?: numberRetransmit Timeout ZMQ_TCP_MAXRT
Sets how long before an unacknowledged TCP retransmit times out (if supported by the OS). The system normally attempts many TCP retransmits following an exponential backoff strategy. This means that after a network outage, it may take a long time before the session can be re-established. Setting this option allows the timeout to happen at a shorter interval.
OptionaltypeOf ?: numberService ZMQ_TOS
Sets the ToS fields (the Differentiated Services (DS) and Explicit Congestion Notification (ECN) field) of the IP header. The ToS field is typically used to specify a packet's priority. The availability of this option is dependent on intermediate network equipment that inspect the ToS field and provide a path for low-delay, high-throughput, highly-reliable service, etc.
OptionalvmciBuffer ?: numberMax Size ZMQ_VMCI_BUFFER_MAX_SIZE
Maximum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciBuffer ?: numberMin Size ZMQ_VMCI_BUFFER_MIN_SIZE
Minimum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciBuffer ?: numberSize ZMQ_VMCI_BUFFER_SIZE
The size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciConnect ?: numberTimeout ZMQ_VMCI_CONNECT_TIMEOUT
Connection timeout for the socket. For
vmci://transports only.OptionalzapDomain ?: null | stringZMQ_ZAP_DOMAIN
Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the default on all
tcp://connections), ZAP authentication only happens if you set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 for more details.OptionalzapEnforce ?: booleanDomain ZMQ_ZAP_ENFORCE_DOMAIN
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.
Returns Publisher
Properties
affinity
ZMQ_AFFINITY
I/O thread affinity, which determines which threads from the ØMQ I/O thread pool associated with the socket's context shall handle newly created connections.
Note: This value is a bit mask, but values higher than Number.MAX_SAFE_INTEGER may not be represented accurately! This currently means that configurations beyond 52 threads are unreliable.
backlog
ZMQ_BACKLOG
Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.
Readonlyclosed
Whether this socket was previously closed with close().
conflate
ZMQ_CONFLATE
If set to true, a socket shall keep only one message in its inbound/outbound queue: the last message to be received/sent. Ignores any high water mark options. Does not support multi-part messages - in particular, only one part of it is kept in the socket internal queue.
connectTimeout
ZMQ_CONNECT_TIMEOUT
Sets how long to wait before timing-out a connect() system call. The connect() system call normally takes a long time before it returns a time out error. Setting this option allows the library to time out the call at an earlier interval.
Readonlycontext
Context that this socket belongs to.
curvePublicKey
ZMQ_CURVE_PUBLICKEY
Sets the socket's long term public key. You must set this on CURVE client sockets. A server socket does not need to know its own public key. You can create a new keypair with curveKeyPair().
curveSecretKey
ZMQ_CURVE_SECRETKEY
Sets the socket's long term secret key. You must set this on both CURVE client and server sockets. You can create a new keypair with curveKeyPair().
curveServer
ZMQ_CURVE_SERVER
Defines whether the socket will act as server for CURVE security. A value of true means the socket will act as CURVE server. A value of false means the socket will not act as CURVE server, and its security role then depends on other option settings.
curveServerKey
ZMQ_CURVE_SERVERKEY
Sets the socket's long term server key. This is the public key of the CURVE server socket. You must set this on CURVE client sockets. This key must have been generated together with the server's secret key. You can create a new keypair with curveKeyPair().
Readonlyevents
Event Observer for this socket. This starts up a ØMQ monitoring socket internally that receives all socket events.
gssapiPlainText
gssapiPrincipal
gssapiPrincipalNameType
gssapiServer
gssapiServicePrincipal
gssapiServicePrincipalNameType
handshakeInterval
ZMQ_HANDSHAKE_IVL
Handshaking is the exchange of socket configuration information (socket type, identity, security) that occurs when a connection is first opened (only for connection-oriented transports). If handshaking does not complete within the configured time, the connection shall be closed. The value 0 means no handshake time limit.
heartbeatInterval
ZMQ_HEARTBEAT_IVL
Interval in milliseconds between sending ZMTP heartbeats for the specified socket. If this option is greater than 0, then a PING ZMTP command will be sent after every interval.
heartbeatTimeout
ZMQ_HEARTBEAT_TIMEOUT
How long (in milliseconds) to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic. This option is only valid if heartbeatInterval is greater than 0. The connection will time out if there is no traffic received after sending the PING command. The received traffic does not have to be a PONG command - any received traffic will cancel the timeout.
heartbeatTimeToLive
ZMQ_HEARTBEAT_TTL
The timeout in milliseconds on the remote peer for ZMTP heartbeats. If this option is greater than 0, the remote side shall time out the connection if it does not receive any more traffic within the TTL period. This option does not have any effect if heartbeatInterval is 0. Internally, this value is rounded down to the nearest decisecond, any value less than 100 will have no effect.
immediate
ZMQ_IMMEDIATE
By default queues will fill on outgoing connections even if the connection has not completed. This can lead to "lost" messages on sockets with round-robin routing (Request, Push, Dealer). If this option is set to true, messages shall be queued only to completed connections. This will cause the socket to block if there are no other connections, but will prevent queues from filling on pipes awaiting connection.
interface
ZMQ_BINDTODEVICE
Binds the socket to the given network interface (Linux only). Allows to use Linux VRF, see: https://www.kernel.org/doc/Documentation/networking/vrf.txt. Requires the program to be ran as root or with CAP_NET_RAW.
invertMatching
ZMQ_INVERT_MATCHING
Causes messages to be sent to all connected sockets except those subscribed to a prefix that matches the message.
All Subscriber sockets connecting to the Publisher must also have the option set to true. Failure to do so will have the Subscriber sockets reject everything the Publisher socket sends them.
ipv6
ZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
ReadonlylastEndpoint
ZMQ_LAST_ENDPOINT
The last endpoint bound for TCP and IPC transports.
linger
ZMQ_LINGER
Determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with close().
loopbackFastPath
ZMQ_LOOPBACK_FASTPATH
Enable faster TCP connections on loopback devices. An application can enable this option to reduce the latency and improve the performance of loopback operations on a TCP socket on Windows.
maxMessageSize
ZMQ_MAXMSGSIZE
Limits the size of the inbound message. If a peer sends a message larger than the limit it is disconnected. Value of -1 means no limit.
multicastHops
ZMQ_MULTICAST_HOPS
Sets the time-to-live field in every multicast packet sent from this socket. The default is 1 which means that the multicast packets don't leave the local network.
multicastMaxTransportDataUnit
ZMQ_MULTICAST_MAXTPDU
Sets the maximum transport data unit size used for outbound multicast packets. This must be set at or below the minimum Maximum Transmission Unit (MTU) for all network paths over which multicast reception is required.
noDrop
ZMQ_XPUB_NODROP
Sets the socket behaviour to return an error if the high water mark is reached and the message could not be send. The default is to drop the message silently when the peer high water mark is reached.
plainPassword
ZMQ_PLAIN_PASSWORD
Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
plainServer
ZMQ_PLAIN_SERVER
Defines whether the socket will act as server for PLAIN security. A value of true means the socket will act as PLAIN server. A value of false means the socket will not act as PLAIN server, and its security role then depends on other option settings.
plainUsername
ZMQ_PLAIN_USERNAME
Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
rate
ZMQ_RATE
Maximum send or receive data rate for multicast transports such as pgm.
Readonlyreadable
Whether any messages are currently available. If true, the next call to Readable.receive() will immediately read a message from the socket. For sockets that cannot receive messsages this is always false.
reconnectInterval
ZMQ_RECONNECT_IVL
Period ØMQ shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. The value -1 means no reconnection.
reconnectMaxInterval
ZMQ_RECONNECT_IVL_MAX
Maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled until reconnectMaxInterval is reached. This allows for exponential backoff strategy. Zero (the default) means no exponential backoff is performed and reconnect interval calculations are only based on reconnectInterval.
recoveryInterval
ZMQ_RECOVERY_IVL
Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
ReadonlysecurityMechanism
| null
| "plain"
| "curve"
| "gssapi"
ZMQ_MECHANISM
Returns the current security mechanism for the socket, if any. The security mechanism is set implictly by using any of the relevant security options. The returned value is one of:
null- No security mechanism is used."plain"- The PLAIN mechanism defines a simple username/password mechanism that lets a server authenticate a client. PLAIN makes no attempt at security or confidentiality."curve"- The CURVE mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server. CURVE is intended for use on public networks."gssapi"- The GSSAPI mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server using the Generic Security Service Application Program Interface (GSSAPI). The GSSAPI mechanism can be used on both public and private networks.
sendBufferSize
ZMQ_SNDBUF
Underlying kernel transmit buffer size in bytes. A value of -1 means leave the OS default unchanged.
sendHighWaterMark
ZMQ_SNDHWM
The high water mark is a hard limit on the maximum number of outgoing messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
sendTimeout
ZMQ_SNDTIMEO
Sets the timeout for sending messages on the socket. If the value is 0, send() will return a rejected promise immediately if the message cannot be sent. If the value is -1, it will wait asynchronously until the message is sent. For all other values, it will try to send the message for that amount of time before rejecting.
socksProxy
ZMQ_SOCKS_PROXY
The SOCKS5 proxy address that shall be used by the socket for the TCP connection(s). Does not support SOCKS5 authentication. If the endpoints are domain names instead of addresses they shall not be resolved and they shall be forwarded unchanged to the SOCKS proxy service in the client connection request message (address type 0x03 domain name).
tcpAcceptFilter
ZMQ_TCP_ACCEPT_FILTER
Assign a filter that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one filter is applied then new connection source IP should be matched. To clear all filters set to null. Filter is a string with IPv6 or IPv4 CIDR.
tcpKeepalive
ZMQ_TCP_KEEPALIVE
Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveCount
ZMQ_TCP_KEEPALIVE_CNT
Overrides TCP_KEEPCNT socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveIdle
ZMQ_TCP_KEEPALIVE_IDLE
Overrides TCP_KEEPIDLE / TCP_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveInterval
ZMQ_TCP_KEEPALIVE_INTVL
Overrides TCP_KEEPINTVL socket option (if supported by the OS). The default value of -1 leaves it to the OS default.
tcpMaxRetransmitTimeout
ZMQ_TCP_MAXRT
Sets how long before an unacknowledged TCP retransmit times out (if supported by the OS). The system normally attempts many TCP retransmits following an exponential backoff strategy. This means that after a network outage, it may take a long time before the session can be re-established. Setting this option allows the timeout to happen at a shorter interval.
ReadonlythreadSafe
ZMQ_THREAD_SAFE
Whether or not the socket is threadsafe. Currently only DRAFT sockets is thread-safe.
Readonlytype
ZMQ_TYPE
Retrieve the socket type. This is fairly useless because you can test the socket class with e.g. socket instanceof Dealer.
typeOfService
ZMQ_TOS
Sets the ToS fields (the Differentiated Services (DS) and Explicit Congestion Notification (ECN) field) of the IP header. The ToS field is typically used to specify a packet's priority. The availability of this option is dependent on intermediate network equipment that inspect the ToS field and provide a path for low-delay, high-throughput, highly-reliable service, etc.
vmciBufferMaxSize
ZMQ_VMCI_BUFFER_MAX_SIZE
Maximum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferMinSize
ZMQ_VMCI_BUFFER_MIN_SIZE
Minimum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferSize
ZMQ_VMCI_BUFFER_SIZE
The size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciConnectTimeout
ZMQ_VMCI_CONNECT_TIMEOUT
Connection timeout for the socket. For vmci:// transports only.
Readonlywritable
Whether any messages can be queued for sending. If true, the next call to Writable.send() will immediately queue a message on the socket. For sockets that cannot send messsages this is always false.
zapDomain
ZMQ_ZAP_DOMAIN
Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the default on all tcp:// connections), ZAP authentication only happens if you set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 for more details.
zapEnforceDomain
ZMQ_ZAP_ENFORCE_DOMAIN
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.
Methods
bind
- bind(address): Promise<void>
Binds the socket to the given address. During bind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.You can use
*in place of a hostname to bind on all interfaces/addresses, and you can use*in place of a port to bind to a random port (which can be retrieved with lastEndpoint later).await socket.bind("tcp://127.0.0.1:3456")
await socket.bind("tcp://*:3456") // binds on all interfaces
await socket.bind("tcp://127.0.0.1:*") // binds on random port -Parameters
- address: string
Address to bind this socket to.
Returns Promise<void>
Resolved when the socket was successfully bound.
- address: string
close
- close(): void
Closes the socket and disposes of all resources. Any messages that are queued may be discarded or sent in the background depending on the linger setting.
After this method is called, it is no longer possible to call any other methods on this socket.
Sockets that go out of scope and have no Readable.receive() or Writable.send() operations in progress will automatically be closed. Therefore it is not necessary in most applications to call close() manually.
Calling this method on a socket that is already closed is a no-op.
Returns void
connect
disconnect
- disconnect(address): void
Disconnects a previously connected socket from the given address and returns immediately. Disonnection will happen asynchronously in the background.
socket.disconnect("tcp://127.0.0.1:3456") -Parameters
- address: string
The previously connected address to disconnect from.
Returns void
- address: string
ProtectedgetBoolOption
ProtectedgetInt32Option
ProtectedgetInt64Option
ProtectedgetStringOption
ProtectedgetUint32Option
ProtectedgetUint64Option
send
- send(message, ...options): Promise<void>
Sends a single message or a multipart message on the socket. Queues the message immediately if possible, and returns a resolved promise. If the message cannot be queued because the high water mark has been reached, it will wait asynchronously. The promise will be resolved when the message was queued successfully.
await socket.send("hello world")
await socket.send(["hello", "world"]) -Queueing may fail eventually if the socket has been configured with a sendTimeout.
A call to send() is guaranteed to return with a resolved promise immediately if the message could be queued directly.
Only one asynchronously blocking call to send() may be executed simultaneously. If you call send() again on a socket that is in the mute state it will return a rejected promise with an
EBUSYerror.The reason for disallowing multiple send() calls simultaneously is that it could create an implicit queue of unsendable outgoing messages. This would circumvent the socket's sendHighWaterMark. Such an implementation could even exhaust all system memory and cause the Node.js process to abort.
For most application you should not notice this implementation detail. Only in rare occasions will a call to send() that does not resolve immediately be undesired. Here are some common scenarios:
If you wish to send a message, use
await send(...). ZeroMQ socket types have been carefully designed to give you the correct blocking behaviour on the chosen socket type in almost all cases:If sending is not possible, it is often better to wait than to continue as if nothing happened. For example, on a Request socket, you can only receive a reply once a message has been sent; so waiting until a message could be queued before continuing with the rest of the program (likely to read from the socket) is required.
Certain socket types (such as Router) will always allow queueing messages and
await send(...)won't delay any code that comes after. This makes sense for routers, since typically you don't want a single send operation to stop the handling of other incoming or outgoing messages.
If you wish to send on an occasionally blocking socket (for example on a Router with the Router.mandatory option set, or on a Dealer) and you're 100% certain that dropping a message is better than blocking, then you can set the sendTimeout option to
0to effectively force send() to always resolve immediately. Be prepared to catch exceptions if sending a message is not immediately possible.If you wish to send on a socket and messages should be queued before they are dropped, you should implement a simple queue in JavaScript. Such a queue is not provided by this library because most real world applications need to deal with undeliverable messages in more complex ways - for example, they might need to reply with a status message; or first retry delivery a certain number of times before giving up.
Parameters
- message: MessageLike | MessageLike[]
Single message or multipart message to queue for sending.
Rest...options: []Any options, if applicable to the socket type (DRAFT only).
Returns Promise<void>
Resolved when the message was successfully queued.
ProtectedsetBoolOption
ProtectedsetInt32Option
ProtectedsetInt64Option
ProtectedsetStringOption
ProtectedsetUint32Option
ProtectedsetUint64Option
unbind
- unbind(address): Promise<void>
Unbinds the socket to the given address. During unbind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.Parameters
- address: string
Address to unbind this socket from.
Returns Promise<void>
Resolved when the socket was successfully unbound.
- address: string
Class Publisher
A Publisher socket is used to distribute data to Subscribers. Messages sent are distributed in a fan out fashion to all connected peers. This socket cannot receive messages.
When a Publisher enters the mute state due to having reached the high water mark for a connected Subscriber, then any messages that would be sent to the subscriber in question shall instead be dropped until the mute state ends. The Writable.send() method will never block.
Hierarchy (View Summary)
Index
Constructors
Properties
Methods
Constructors
constructor
- new Publisher(
options?: {
affinity?: number;
backlog?: number;
conflate?: boolean;
connectTimeout?: number;
context?: Context;
curvePublicKey?: null | string;
curveSecretKey?: null | string;
curveServer?: boolean;
curveServerKey?: null | string;
gssapiPlainText?: boolean;
gssapiPrincipal?: null | string;
gssapiPrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
gssapiServer?: boolean;
gssapiServicePrincipal?: null | string;
gssapiServicePrincipalNameType?:
| "hostBased"
| "userName"
| "krb5Principal";
handshakeInterval?: number;
heartbeatInterval?: number;
heartbeatTimeout?: number;
heartbeatTimeToLive?: number;
immediate?: boolean;
interface?: null
| string;
invertMatching?: boolean;
ipv6?: boolean;
linger?: number;
loopbackFastPath?: boolean;
maxMessageSize?: number;
multicastHops?: number;
multicastMaxTransportDataUnit?: number;
noDrop?: boolean;
plainPassword?: null | string;
plainServer?: boolean;
plainUsername?: null | string;
rate?: number;
reconnectInterval?: number;
reconnectMaxInterval?: number;
recoveryInterval?: number;
sendBufferSize?: number;
sendHighWaterMark?: number;
sendTimeout?: number;
socksProxy?: null | string;
tcpAcceptFilter?: null | string;
tcpKeepalive?: number;
tcpKeepaliveCount?: number;
tcpKeepaliveIdle?: number;
tcpKeepaliveInterval?: number;
tcpMaxRetransmitTimeout?: number;
typeOfService?: number;
vmciBufferMaxSize?: number;
vmciBufferMinSize?: number;
vmciBufferSize?: number;
vmciConnectTimeout?: number;
zapDomain?: null | string;
zapEnforceDomain?: boolean;
},
): Publisher Parameters
Optionaloptions: {
affinity?: number;
backlog?: number;
conflate?: boolean;
connectTimeout?: number;
context?: Context;
curvePublicKey?: null | string;
curveSecretKey?: null | string;
curveServer?: boolean;
curveServerKey?: null | string;
gssapiPlainText?: boolean;
gssapiPrincipal?: null | string;
gssapiPrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
gssapiServer?: boolean;
gssapiServicePrincipal?: null | string;
gssapiServicePrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
handshakeInterval?: number;
heartbeatInterval?: number;
heartbeatTimeout?: number;
heartbeatTimeToLive?: number;
immediate?: boolean;
interface?: null | string;
invertMatching?: boolean;
ipv6?: boolean;
linger?: number;
loopbackFastPath?: boolean;
maxMessageSize?: number;
multicastHops?: number;
multicastMaxTransportDataUnit?: number;
noDrop?: boolean;
plainPassword?: null | string;
plainServer?: boolean;
plainUsername?: null | string;
rate?: number;
reconnectInterval?: number;
reconnectMaxInterval?: number;
recoveryInterval?: number;
sendBufferSize?: number;
sendHighWaterMark?: number;
sendTimeout?: number;
socksProxy?: null | string;
tcpAcceptFilter?: null | string;
tcpKeepalive?: number;
tcpKeepaliveCount?: number;
tcpKeepaliveIdle?: number;
tcpKeepaliveInterval?: number;
tcpMaxRetransmitTimeout?: number;
typeOfService?: number;
vmciBufferMaxSize?: number;
vmciBufferMinSize?: number;
vmciBufferSize?: number;
vmciConnectTimeout?: number;
zapDomain?: null | string;
zapEnforceDomain?: boolean;
}Optionalaffinity?: numberZMQ_AFFINITY
I/O thread affinity, which determines which threads from the ØMQ I/O thread pool associated with the socket's context shall handle newly created connections.
Note: This value is a bit mask, but values higher than
Number.MAX_SAFE_INTEGERmay not be represented accurately! This currently means that configurations beyond 52 threads are unreliable.Optionalbacklog?: numberZMQ_BACKLOG
Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.
Optionalconflate?: booleanZMQ_CONFLATE
If set to
true, a socket shall keep only one message in its inbound/outbound queue: the last message to be received/sent. Ignores any high water mark options. Does not support multi-part messages - in particular, only one part of it is kept in the socket internal queue.OptionalconnectTimeout?: numberZMQ_CONNECT_TIMEOUT
Sets how long to wait before timing-out a connect() system call. The connect() system call normally takes a long time before it returns a time out error. Setting this option allows the library to time out the call at an earlier interval.
Optionalcontext?: ContextOptionalcurvePublicKey?: null | stringZMQ_CURVE_PUBLICKEY
Sets the socket's long term public key. You must set this on CURVE client sockets. A server socket does not need to know its own public key. You can create a new keypair with curveKeyPair().
OptionalcurveSecretKey?: null | stringZMQ_CURVE_SECRETKEY
Sets the socket's long term secret key. You must set this on both CURVE client and server sockets. You can create a new keypair with curveKeyPair().
OptionalcurveServer?: booleanZMQ_CURVE_SERVER
Defines whether the socket will act as server for CURVE security. A value of
truemeans the socket will act as CURVE server. A value offalsemeans the socket will not act as CURVE server, and its security role then depends on other option settings.OptionalcurveServerKey?: null | stringZMQ_CURVE_SERVERKEY
Sets the socket's long term server key. This is the public key of the CURVE server socket. You must set this on CURVE client sockets. This key must have been generated together with the server's secret key. You can create a new keypair with curveKeyPair().
OptionalgssapiPlainText?: booleanOptionalgssapiPrincipal?: null | stringOptionalgssapiPrincipalNameType?: "hostBased" | "userName" | "krb5Principal"OptionalgssapiServer?: booleanOptionalgssapiServicePrincipal?: null | stringOptionalgssapiServicePrincipalNameType?: "hostBased" | "userName" | "krb5Principal"OptionalhandshakeInterval?: numberZMQ_HANDSHAKE_IVL
Handshaking is the exchange of socket configuration information (socket type, identity, security) that occurs when a connection is first opened (only for connection-oriented transports). If handshaking does not complete within the configured time, the connection shall be closed. The value 0 means no handshake time limit.
OptionalheartbeatInterval?: numberZMQ_HEARTBEAT_IVL
Interval in milliseconds between sending ZMTP heartbeats for the specified socket. If this option is greater than 0, then a PING ZMTP command will be sent after every interval.
OptionalheartbeatTimeout?: numberZMQ_HEARTBEAT_TIMEOUT
How long (in milliseconds) to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic. This option is only valid if heartbeatInterval is greater than 0. The connection will time out if there is no traffic received after sending the PING command. The received traffic does not have to be a PONG command - any received traffic will cancel the timeout.
OptionalheartbeatTimeToLive?: numberZMQ_HEARTBEAT_TTL
The timeout in milliseconds on the remote peer for ZMTP heartbeats. If this option is greater than 0, the remote side shall time out the connection if it does not receive any more traffic within the TTL period. This option does not have any effect if heartbeatInterval is 0. Internally, this value is rounded down to the nearest decisecond, any value less than 100 will have no effect.
Optionalimmediate?: booleanZMQ_IMMEDIATE
By default queues will fill on outgoing connections even if the connection has not completed. This can lead to "lost" messages on sockets with round-robin routing (Request, Push, Dealer). If this option is set to
true, messages shall be queued only to completed connections. This will cause the socket to block if there are no other connections, but will prevent queues from filling on pipes awaiting connection.Optionalinterface?: null | stringZMQ_BINDTODEVICE
Binds the socket to the given network interface (Linux only). Allows to use Linux VRF, see: https://www.kernel.org/doc/Documentation/networking/vrf.txt. Requires the program to be ran as root or with
CAP_NET_RAW.OptionalinvertMatching?: booleanZMQ_INVERT_MATCHING
Causes messages to be sent to all connected sockets except those subscribed to a prefix that matches the message.
All Subscriber sockets connecting to the Publisher must also have the option set to
true. Failure to do so will have the Subscriber sockets reject everything the Publisher socket sends them.Optionalipv6?: booleanZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
Optionallinger?: numberZMQ_LINGER
Determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with close().
OptionalloopbackFastPath?: booleanZMQ_LOOPBACK_FASTPATH
Enable faster TCP connections on loopback devices. An application can enable this option to reduce the latency and improve the performance of loopback operations on a TCP socket on Windows.
OptionalmaxMessageSize?: numberZMQ_MAXMSGSIZE
Limits the size of the inbound message. If a peer sends a message larger than the limit it is disconnected. Value of -1 means no limit.
OptionalmulticastHops?: numberZMQ_MULTICAST_HOPS
Sets the time-to-live field in every multicast packet sent from this socket. The default is 1 which means that the multicast packets don't leave the local network.
OptionalmulticastMaxTransportDataUnit?: numberZMQ_MULTICAST_MAXTPDU
Sets the maximum transport data unit size used for outbound multicast packets. This must be set at or below the minimum Maximum Transmission Unit (MTU) for all network paths over which multicast reception is required.
OptionalnoDrop?: booleanZMQ_XPUB_NODROP
Sets the socket behaviour to return an error if the high water mark is reached and the message could not be send. The default is to drop the message silently when the peer high water mark is reached.
OptionalplainPassword?: null | stringZMQ_PLAIN_PASSWORD
Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
OptionalplainServer?: booleanZMQ_PLAIN_SERVER
Defines whether the socket will act as server for PLAIN security. A value of
truemeans the socket will act as PLAIN server. A value offalsemeans the socket will not act as PLAIN server, and its security role then depends on other option settings.OptionalplainUsername?: null | stringZMQ_PLAIN_USERNAME
Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
Optionalrate?: numberZMQ_RATE
Maximum send or receive data rate for multicast transports such as
pgm.OptionalreconnectInterval?: numberZMQ_RECONNECT_IVL
Period ØMQ shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. The value -1 means no reconnection.
OptionalreconnectMaxInterval?: numberZMQ_RECONNECT_IVL_MAX
Maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled until reconnectMaxInterval is reached. This allows for exponential backoff strategy. Zero (the default) means no exponential backoff is performed and reconnect interval calculations are only based on reconnectInterval.
OptionalrecoveryInterval?: numberZMQ_RECOVERY_IVL
Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
OptionalsendBufferSize?: numberZMQ_SNDBUF
Underlying kernel transmit buffer size in bytes. A value of -1 means leave the OS default unchanged.
OptionalsendHighWaterMark?: numberZMQ_SNDHWM
The high water mark is a hard limit on the maximum number of outgoing messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
OptionalsendTimeout?: numberZMQ_SNDTIMEO
Sets the timeout for sending messages on the socket. If the value is 0, send() will return a rejected promise immediately if the message cannot be sent. If the value is -1, it will wait asynchronously until the message is sent. For all other values, it will try to send the message for that amount of time before rejecting.
OptionalsocksProxy?: null | stringZMQ_SOCKS_PROXY
The SOCKS5 proxy address that shall be used by the socket for the TCP connection(s). Does not support SOCKS5 authentication. If the endpoints are domain names instead of addresses they shall not be resolved and they shall be forwarded unchanged to the SOCKS proxy service in the client connection request message (address type 0x03 domain name).
OptionaltcpAcceptFilter?: null | stringZMQ_TCP_ACCEPT_FILTER
Assign a filter that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one filter is applied then new connection source IP should be matched. To clear all filters set to
null. Filter is a string with IPv6 or IPv4 CIDR.OptionaltcpKeepalive?: numberZMQ_TCP_KEEPALIVE
Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepaliveCount?: numberZMQ_TCP_KEEPALIVE_CNT
Overrides TCP_KEEPCNT socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepaliveIdle?: numberZMQ_TCP_KEEPALIVE_IDLE
Overrides TCP_KEEPIDLE / TCP_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepaliveInterval?: numberZMQ_TCP_KEEPALIVE_INTVL
Overrides TCP_KEEPINTVL socket option (if supported by the OS). The default value of -1 leaves it to the OS default.
OptionaltcpMaxRetransmitTimeout?: numberZMQ_TCP_MAXRT
Sets how long before an unacknowledged TCP retransmit times out (if supported by the OS). The system normally attempts many TCP retransmits following an exponential backoff strategy. This means that after a network outage, it may take a long time before the session can be re-established. Setting this option allows the timeout to happen at a shorter interval.
OptionaltypeOfService?: numberZMQ_TOS
Sets the ToS fields (the Differentiated Services (DS) and Explicit Congestion Notification (ECN) field) of the IP header. The ToS field is typically used to specify a packet's priority. The availability of this option is dependent on intermediate network equipment that inspect the ToS field and provide a path for low-delay, high-throughput, highly-reliable service, etc.
OptionalvmciBufferMaxSize?: numberZMQ_VMCI_BUFFER_MAX_SIZE
Maximum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciBufferMinSize?: numberZMQ_VMCI_BUFFER_MIN_SIZE
Minimum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciBufferSize?: numberZMQ_VMCI_BUFFER_SIZE
The size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciConnectTimeout?: numberZMQ_VMCI_CONNECT_TIMEOUT
Connection timeout for the socket. For
vmci://transports only.OptionalzapDomain?: null | stringZMQ_ZAP_DOMAIN
Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the default on all
tcp://connections), ZAP authentication only happens if you set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 for more details.OptionalzapEnforceDomain?: booleanZMQ_ZAP_ENFORCE_DOMAIN
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.
Returns Publisher
Properties
affinity
ZMQ_AFFINITY
I/O thread affinity, which determines which threads from the ØMQ I/O thread pool associated with the socket's context shall handle newly created connections.
Note: This value is a bit mask, but values higher than Number.MAX_SAFE_INTEGER may not be represented accurately! This currently means that configurations beyond 52 threads are unreliable.
backlog
ZMQ_BACKLOG
Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.
Readonlyclosed
Whether this socket was previously closed with close().
conflate
ZMQ_CONFLATE
If set to true, a socket shall keep only one message in its inbound/outbound queue: the last message to be received/sent. Ignores any high water mark options. Does not support multi-part messages - in particular, only one part of it is kept in the socket internal queue.
connectTimeout
ZMQ_CONNECT_TIMEOUT
Sets how long to wait before timing-out a connect() system call. The connect() system call normally takes a long time before it returns a time out error. Setting this option allows the library to time out the call at an earlier interval.
Readonlycontext
Context that this socket belongs to.
curvePublicKey
ZMQ_CURVE_PUBLICKEY
Sets the socket's long term public key. You must set this on CURVE client sockets. A server socket does not need to know its own public key. You can create a new keypair with curveKeyPair().
curveSecretKey
ZMQ_CURVE_SECRETKEY
Sets the socket's long term secret key. You must set this on both CURVE client and server sockets. You can create a new keypair with curveKeyPair().
curveServer
ZMQ_CURVE_SERVER
Defines whether the socket will act as server for CURVE security. A value of true means the socket will act as CURVE server. A value of false means the socket will not act as CURVE server, and its security role then depends on other option settings.
curveServerKey
ZMQ_CURVE_SERVERKEY
Sets the socket's long term server key. This is the public key of the CURVE server socket. You must set this on CURVE client sockets. This key must have been generated together with the server's secret key. You can create a new keypair with curveKeyPair().
Readonlyevents
Event Observer for this socket. This starts up a ØMQ monitoring socket internally that receives all socket events.
gssapiPlainText
gssapiPrincipal
gssapiPrincipalNameType
gssapiServer
gssapiServicePrincipal
gssapiServicePrincipalNameType
handshakeInterval
ZMQ_HANDSHAKE_IVL
Handshaking is the exchange of socket configuration information (socket type, identity, security) that occurs when a connection is first opened (only for connection-oriented transports). If handshaking does not complete within the configured time, the connection shall be closed. The value 0 means no handshake time limit.
heartbeatInterval
ZMQ_HEARTBEAT_IVL
Interval in milliseconds between sending ZMTP heartbeats for the specified socket. If this option is greater than 0, then a PING ZMTP command will be sent after every interval.
heartbeatTimeout
ZMQ_HEARTBEAT_TIMEOUT
How long (in milliseconds) to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic. This option is only valid if heartbeatInterval is greater than 0. The connection will time out if there is no traffic received after sending the PING command. The received traffic does not have to be a PONG command - any received traffic will cancel the timeout.
heartbeatTimeToLive
ZMQ_HEARTBEAT_TTL
The timeout in milliseconds on the remote peer for ZMTP heartbeats. If this option is greater than 0, the remote side shall time out the connection if it does not receive any more traffic within the TTL period. This option does not have any effect if heartbeatInterval is 0. Internally, this value is rounded down to the nearest decisecond, any value less than 100 will have no effect.
immediate
ZMQ_IMMEDIATE
By default queues will fill on outgoing connections even if the connection has not completed. This can lead to "lost" messages on sockets with round-robin routing (Request, Push, Dealer). If this option is set to true, messages shall be queued only to completed connections. This will cause the socket to block if there are no other connections, but will prevent queues from filling on pipes awaiting connection.
interface
ZMQ_BINDTODEVICE
Binds the socket to the given network interface (Linux only). Allows to use Linux VRF, see: https://www.kernel.org/doc/Documentation/networking/vrf.txt. Requires the program to be ran as root or with CAP_NET_RAW.
invertMatching
ZMQ_INVERT_MATCHING
Causes messages to be sent to all connected sockets except those subscribed to a prefix that matches the message.
All Subscriber sockets connecting to the Publisher must also have the option set to true. Failure to do so will have the Subscriber sockets reject everything the Publisher socket sends them.
ipv6
ZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
ReadonlylastEndpoint
ZMQ_LAST_ENDPOINT
The last endpoint bound for TCP and IPC transports.
linger
ZMQ_LINGER
Determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with close().
loopbackFastPath
ZMQ_LOOPBACK_FASTPATH
Enable faster TCP connections on loopback devices. An application can enable this option to reduce the latency and improve the performance of loopback operations on a TCP socket on Windows.
maxMessageSize
ZMQ_MAXMSGSIZE
Limits the size of the inbound message. If a peer sends a message larger than the limit it is disconnected. Value of -1 means no limit.
multicastHops
ZMQ_MULTICAST_HOPS
Sets the time-to-live field in every multicast packet sent from this socket. The default is 1 which means that the multicast packets don't leave the local network.
multicastMaxTransportDataUnit
ZMQ_MULTICAST_MAXTPDU
Sets the maximum transport data unit size used for outbound multicast packets. This must be set at or below the minimum Maximum Transmission Unit (MTU) for all network paths over which multicast reception is required.
noDrop
ZMQ_XPUB_NODROP
Sets the socket behaviour to return an error if the high water mark is reached and the message could not be send. The default is to drop the message silently when the peer high water mark is reached.
plainPassword
ZMQ_PLAIN_PASSWORD
Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
plainServer
ZMQ_PLAIN_SERVER
Defines whether the socket will act as server for PLAIN security. A value of true means the socket will act as PLAIN server. A value of false means the socket will not act as PLAIN server, and its security role then depends on other option settings.
plainUsername
ZMQ_PLAIN_USERNAME
Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
rate
ZMQ_RATE
Maximum send or receive data rate for multicast transports such as pgm.
Readonlyreadable
Whether any messages are currently available. If true, the next call to Readable.receive() will immediately read a message from the socket. For sockets that cannot receive messsages this is always false.
reconnectInterval
ZMQ_RECONNECT_IVL
Period ØMQ shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. The value -1 means no reconnection.
reconnectMaxInterval
ZMQ_RECONNECT_IVL_MAX
Maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled until reconnectMaxInterval is reached. This allows for exponential backoff strategy. Zero (the default) means no exponential backoff is performed and reconnect interval calculations are only based on reconnectInterval.
recoveryInterval
ZMQ_RECOVERY_IVL
Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
ReadonlysecurityMechanism
ZMQ_MECHANISM
Returns the current security mechanism for the socket, if any. The security mechanism is set implictly by using any of the relevant security options. The returned value is one of:
null- No security mechanism is used."plain"- The PLAIN mechanism defines a simple username/password mechanism that lets a server authenticate a client. PLAIN makes no attempt at security or confidentiality."curve"- The CURVE mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server. CURVE is intended for use on public networks."gssapi"- The GSSAPI mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server using the Generic Security Service Application Program Interface (GSSAPI). The GSSAPI mechanism can be used on both public and private networks.
sendBufferSize
ZMQ_SNDBUF
Underlying kernel transmit buffer size in bytes. A value of -1 means leave the OS default unchanged.
sendHighWaterMark
ZMQ_SNDHWM
The high water mark is a hard limit on the maximum number of outgoing messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
sendTimeout
ZMQ_SNDTIMEO
Sets the timeout for sending messages on the socket. If the value is 0, send() will return a rejected promise immediately if the message cannot be sent. If the value is -1, it will wait asynchronously until the message is sent. For all other values, it will try to send the message for that amount of time before rejecting.
socksProxy
ZMQ_SOCKS_PROXY
The SOCKS5 proxy address that shall be used by the socket for the TCP connection(s). Does not support SOCKS5 authentication. If the endpoints are domain names instead of addresses they shall not be resolved and they shall be forwarded unchanged to the SOCKS proxy service in the client connection request message (address type 0x03 domain name).
tcpAcceptFilter
ZMQ_TCP_ACCEPT_FILTER
Assign a filter that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one filter is applied then new connection source IP should be matched. To clear all filters set to null. Filter is a string with IPv6 or IPv4 CIDR.
tcpKeepalive
ZMQ_TCP_KEEPALIVE
Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveCount
ZMQ_TCP_KEEPALIVE_CNT
Overrides TCP_KEEPCNT socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveIdle
ZMQ_TCP_KEEPALIVE_IDLE
Overrides TCP_KEEPIDLE / TCP_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveInterval
ZMQ_TCP_KEEPALIVE_INTVL
Overrides TCP_KEEPINTVL socket option (if supported by the OS). The default value of -1 leaves it to the OS default.
tcpMaxRetransmitTimeout
ZMQ_TCP_MAXRT
Sets how long before an unacknowledged TCP retransmit times out (if supported by the OS). The system normally attempts many TCP retransmits following an exponential backoff strategy. This means that after a network outage, it may take a long time before the session can be re-established. Setting this option allows the timeout to happen at a shorter interval.
ReadonlythreadSafe
ZMQ_THREAD_SAFE
Whether or not the socket is threadsafe. Currently only DRAFT sockets is thread-safe.
Readonlytype
ZMQ_TYPE
Retrieve the socket type. This is fairly useless because you can test the socket class with e.g. socket instanceof Dealer.
typeOfService
ZMQ_TOS
Sets the ToS fields (the Differentiated Services (DS) and Explicit Congestion Notification (ECN) field) of the IP header. The ToS field is typically used to specify a packet's priority. The availability of this option is dependent on intermediate network equipment that inspect the ToS field and provide a path for low-delay, high-throughput, highly-reliable service, etc.
vmciBufferMaxSize
ZMQ_VMCI_BUFFER_MAX_SIZE
Maximum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferMinSize
ZMQ_VMCI_BUFFER_MIN_SIZE
Minimum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferSize
ZMQ_VMCI_BUFFER_SIZE
The size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciConnectTimeout
ZMQ_VMCI_CONNECT_TIMEOUT
Connection timeout for the socket. For vmci:// transports only.
Readonlywritable
Whether any messages can be queued for sending. If true, the next call to Writable.send() will immediately queue a message on the socket. For sockets that cannot send messsages this is always false.
zapDomain
ZMQ_ZAP_DOMAIN
Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the default on all tcp:// connections), ZAP authentication only happens if you set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 for more details.
zapEnforceDomain
ZMQ_ZAP_ENFORCE_DOMAIN
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.
Methods
bind
- bind(address: string): Promise<void>
Binds the socket to the given address. During bind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.You can use
*in place of a hostname to bind on all interfaces/addresses, and you can use*in place of a port to bind to a random port (which can be retrieved with lastEndpoint later).await socket.bind("tcp://127.0.0.1:3456")
await socket.bind("tcp://*:3456") // binds on all interfaces
await socket.bind("tcp://127.0.0.1:*") // binds on random port +Parameters
- address: string
Address to bind this socket to.
Returns Promise<void>
Resolved when the socket was successfully bound.
- address: string
bindSync
- bindSync(address: string): void
Binds the socket to the given address. During bind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.You can use
*in place of a hostname to bind on all interfaces/addresses, and you can use*in place of a port to bind to a random port (which can be retrieved with lastEndpoint later).socket.bindSync("tcp://127.0.0.1:3456")
socket.bindSync("tcp://*:3456") // binds on all interfaces
socket.bindSync("tcp://127.0.0.1:*") // binds on random port +Parameters
- address: string
Address to bind this socket to.
Returns void
Resolved when the socket was successfully bound.
- address: string
close
- close(): void
Closes the socket and disposes of all resources. Any messages that are queued may be discarded or sent in the background depending on the linger setting.
After this method is called, it is no longer possible to call any other methods on this socket.
Sockets that go out of scope and have no Readable.receive() or Writable.send() operations in progress will automatically be closed. Therefore it is not necessary in most applications to call close() manually.
Calling this method on a socket that is already closed is a no-op.
Returns void
connect
disconnect
- disconnect(address: string): void
Disconnects a previously connected socket from the given address and returns immediately. Disonnection will happen asynchronously in the background.
socket.disconnect("tcp://127.0.0.1:3456") +Parameters
- address: string
The previously connected address to disconnect from.
Returns void
- address: string
ProtectedgetBoolOption
ProtectedgetInt32Option
ProtectedgetInt64Option
ProtectedgetStringOption
ProtectedgetUint32Option
ProtectedgetUint64Option
send
- send(message: MessageLike | MessageLike[], ...options: []): Promise<void>
Sends a single message or a multipart message on the socket. Queues the message immediately if possible, and returns a resolved promise. If the message cannot be queued because the high water mark has been reached, it will wait asynchronously. The promise will be resolved when the message was queued successfully.
await socket.send("hello world")
await socket.send(["hello", "world"]) +Queueing may fail eventually if the socket has been configured with a sendTimeout.
A call to send() is guaranteed to return with a resolved promise immediately if the message could be queued directly.
Only one asynchronously blocking call to send() may be executed simultaneously. If you call send() again on a socket that is in the mute state it will return a rejected promise with an
EBUSYerror.The reason for disallowing multiple send() calls simultaneously is that it could create an implicit queue of unsendable outgoing messages. This would circumvent the socket's sendHighWaterMark. Such an implementation could even exhaust all system memory and cause the Node.js process to abort.
For most application you should not notice this implementation detail. Only in rare occasions will a call to send() that does not resolve immediately be undesired. Here are some common scenarios:
If you wish to send a message, use
await send(...). ZeroMQ socket types have been carefully designed to give you the correct blocking behaviour on the chosen socket type in almost all cases:If sending is not possible, it is often better to wait than to continue as if nothing happened. For example, on a Request socket, you can only receive a reply once a message has been sent; so waiting until a message could be queued before continuing with the rest of the program (likely to read from the socket) is required.
Certain socket types (such as Router) will always allow queueing messages and
await send(...)won't delay any code that comes after. This makes sense for routers, since typically you don't want a single send operation to stop the handling of other incoming or outgoing messages.
If you wish to send on an occasionally blocking socket (for example on a Router with the Router.mandatory option set, or on a Dealer) and you're 100% certain that dropping a message is better than blocking, then you can set the sendTimeout option to
0to effectively force send() to always resolve immediately. Be prepared to catch exceptions if sending a message is not immediately possible.If you wish to send on a socket and messages should be queued before they are dropped, you should implement a simple queue in JavaScript. Such a queue is not provided by this library because most real world applications need to deal with undeliverable messages in more complex ways - for example, they might need to reply with a status message; or first retry delivery a certain number of times before giving up.
Parameters
- message: MessageLike | MessageLike[]
Single message or multipart message to queue for sending.
- ...options: []
Any options, if applicable to the socket type (DRAFT only).
Returns Promise<void>
Resolved when the message was successfully queued.
ProtectedsetBoolOption
ProtectedsetInt32Option
ProtectedsetInt64Option
ProtectedsetStringOption
ProtectedsetUint32Option
ProtectedsetUint64Option
unbind
- unbind(address: string): Promise<void>
Unbinds the socket to the given address. During unbind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.Parameters
- address: string
Address to unbind this socket from.
Returns Promise<void>
Resolved when the socket was successfully unbound.
- address: string
unbindSync
- unbindSync(address: string): void
Unbinds the socket to the given address. During unbind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.Parameters
- address: string
Address to unbind this socket from.
Returns void
Resolved when the socket was successfully unbound.
- address: string
Class Pull
A Pull socket is used by a pipeline node to receive messages from upstream pipeline nodes. Messages are fair-queued from among all connected upstream nodes. This socket cannot send messages.
Hierarchy (view full)
Index
Constructors
Properties
Methods
Constructors
constructor
- new
Pull (options?): Pull Parameters
Optionaloptions: {
affinity?: number;
backlog?: number;
conflate?: boolean;
connectTimeout?: number;
context?: Context;
curvePublicKey?: null | string;
curveSecretKey?: null | string;
curveServer?: boolean;
curveServerKey?: null | string;
gssapiPlainText?: boolean;
gssapiPrincipal?: null | string;
gssapiPrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
gssapiServer?: boolean;
gssapiServicePrincipal?: null | string;
gssapiServicePrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
handshakeInterval?: number;
heartbeatInterval?: number;
heartbeatTimeout?: number;
heartbeatTimeToLive?: number;
immediate?: boolean;
interface?: null | string;
ipv6?: boolean;
linger?: number;
loopbackFastPath?: boolean;
maxMessageSize?: number;
multicastMaxTransportDataUnit?: number;
plainPassword?: null | string;
plainServer?: boolean;
plainUsername?: null | string;
rate?: number;
receiveBufferSize?: number;
receiveHighWaterMark?: number;
receiveTimeout?: number;
reconnectInterval?: number;
reconnectMaxInterval?: number;
recoveryInterval?: number;
socksProxy?: null | string;
tcpAcceptFilter?: null | string;
tcpKeepalive?: number;
tcpKeepaliveCount?: number;
tcpKeepaliveIdle?: number;
tcpKeepaliveInterval?: number;
tcpMaxRetransmitTimeout?: number;
typeOfService?: number;
vmciBufferMaxSize?: number;
vmciBufferMinSize?: number;
vmciBufferSize?: number;
vmciConnectTimeout?: number;
zapDomain?: null | string;
zapEnforceDomain?: boolean;
}Optionalaffinity?: numberZMQ_AFFINITY
I/O thread affinity, which determines which threads from the ØMQ I/O thread pool associated with the socket's context shall handle newly created connections.
Note: This value is a bit mask, but values higher than
Number.MAX_SAFE_INTEGERmay not be represented accurately! This currently means that configurations beyond 52 threads are unreliable.Optionalbacklog?: numberZMQ_BACKLOG
Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.
Optionalconflate?: booleanZMQ_CONFLATE
If set to
true, a socket shall keep only one message in its inbound/outbound queue: the last message to be received/sent. Ignores any high water mark options. Does not support multi-part messages - in particular, only one part of it is kept in the socket internal queue.OptionalconnectTimeout ?: numberZMQ_CONNECT_TIMEOUT
Sets how long to wait before timing-out a connect() system call. The connect() system call normally takes a long time before it returns a time out error. Setting this option allows the library to time out the call at an earlier interval.
Optionalcontext?: ContextOptionalcurvePublic ?: null | stringKey ZMQ_CURVE_PUBLICKEY
Sets the socket's long term public key. You must set this on CURVE client sockets. A server socket does not need to know its own public key. You can create a new keypair with curveKeyPair().
OptionalcurveSecret ?: null | stringKey ZMQ_CURVE_SECRETKEY
Sets the socket's long term secret key. You must set this on both CURVE client and server sockets. You can create a new keypair with curveKeyPair().
OptionalcurveServer ?: booleanZMQ_CURVE_SERVER
Defines whether the socket will act as server for CURVE security. A value of
truemeans the socket will act as CURVE server. A value offalsemeans the socket will not act as CURVE server, and its security role then depends on other option settings.OptionalcurveServer ?: null | stringKey ZMQ_CURVE_SERVERKEY
Sets the socket's long term server key. This is the public key of the CURVE server socket. You must set this on CURVE client sockets. This key must have been generated together with the server's secret key. You can create a new keypair with curveKeyPair().
OptionalgssapiPlain ?: booleanText OptionalgssapiPrincipal ?: null | stringOptionalgssapiPrincipal ?: "hostBased" | "userName" | "krb5Principal"Name Type OptionalgssapiServer ?: booleanOptionalgssapiService ?: null | stringPrincipal OptionalgssapiService ?: "hostBased" | "userName" | "krb5Principal"Principal Name Type OptionalhandshakeInterval ?: numberZMQ_HANDSHAKE_IVL
Handshaking is the exchange of socket configuration information (socket type, identity, security) that occurs when a connection is first opened (only for connection-oriented transports). If handshaking does not complete within the configured time, the connection shall be closed. The value 0 means no handshake time limit.
OptionalheartbeatInterval ?: numberZMQ_HEARTBEAT_IVL
Interval in milliseconds between sending ZMTP heartbeats for the specified socket. If this option is greater than 0, then a PING ZMTP command will be sent after every interval.
OptionalheartbeatTimeout ?: numberZMQ_HEARTBEAT_TIMEOUT
How long (in milliseconds) to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic. This option is only valid if heartbeatInterval is greater than 0. The connection will time out if there is no traffic received after sending the PING command. The received traffic does not have to be a PONG command - any received traffic will cancel the timeout.
OptionalheartbeatTime ?: numberTo Live ZMQ_HEARTBEAT_TTL
The timeout in milliseconds on the remote peer for ZMTP heartbeats. If this option is greater than 0, the remote side shall time out the connection if it does not receive any more traffic within the TTL period. This option does not have any effect if heartbeatInterval is 0. Internally, this value is rounded down to the nearest decisecond, any value less than 100 will have no effect.
Optionalimmediate?: booleanZMQ_IMMEDIATE
By default queues will fill on outgoing connections even if the connection has not completed. This can lead to "lost" messages on sockets with round-robin routing (Request, Push, Dealer). If this option is set to
true, messages shall be queued only to completed connections. This will cause the socket to block if there are no other connections, but will prevent queues from filling on pipes awaiting connection.Optionalinterface?: null | stringZMQ_BINDTODEVICE
Binds the socket to the given network interface (Linux only). Allows to use Linux VRF, see: https://www.kernel.org/doc/Documentation/networking/vrf.txt. Requires the program to be ran as root or with
CAP_NET_RAW.Optionalipv6?: booleanZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
Optionallinger?: numberZMQ_LINGER
Determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with close().
OptionalloopbackFast ?: booleanPath ZMQ_LOOPBACK_FASTPATH
Enable faster TCP connections on loopback devices. An application can enable this option to reduce the latency and improve the performance of loopback operations on a TCP socket on Windows.
OptionalmaxMessage ?: numberSize ZMQ_MAXMSGSIZE
Limits the size of the inbound message. If a peer sends a message larger than the limit it is disconnected. Value of -1 means no limit.
OptionalmulticastMax ?: numberTransport Data Unit ZMQ_MULTICAST_MAXTPDU
Sets the maximum transport data unit size used for outbound multicast packets. This must be set at or below the minimum Maximum Transmission Unit (MTU) for all network paths over which multicast reception is required.
OptionalplainPassword ?: null | stringZMQ_PLAIN_PASSWORD
Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
OptionalplainServer ?: booleanZMQ_PLAIN_SERVER
Defines whether the socket will act as server for PLAIN security. A value of
truemeans the socket will act as PLAIN server. A value offalsemeans the socket will not act as PLAIN server, and its security role then depends on other option settings.OptionalplainUsername ?: null | stringZMQ_PLAIN_USERNAME
Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
Optionalrate?: numberZMQ_RATE
Maximum send or receive data rate for multicast transports such as
pgm.OptionalreceiveBuffer ?: numberSize ZMQ_RCVBUF
Underlying kernel receive buffer size in bytes. A value of -1 means leave the OS default unchanged.
OptionalreceiveHigh ?: numberWater Mark ZMQ_RCVHWM
The high water mark is a hard limit on the maximum number of incoming messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
OptionalreceiveTimeout ?: numberZMQ_RCVTIMEO
Sets the timeout receiving messages on the socket. If the value is 0, receive() will return a rejected promise immediately if there is no message to receive. If the value is -1, it will wait asynchronously until a message is available. For all other values, it will wait for a message for that amount of time before rejecting.
OptionalreconnectInterval ?: numberZMQ_RECONNECT_IVL
Period ØMQ shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. The value -1 means no reconnection.
OptionalreconnectMax ?: numberInterval ZMQ_RECONNECT_IVL_MAX
Maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled until reconnectMaxInterval is reached. This allows for exponential backoff strategy. Zero (the default) means no exponential backoff is performed and reconnect interval calculations are only based on reconnectInterval.
OptionalrecoveryInterval ?: numberZMQ_RECOVERY_IVL
Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
OptionalsocksProxy ?: null | stringZMQ_SOCKS_PROXY
The SOCKS5 proxy address that shall be used by the socket for the TCP connection(s). Does not support SOCKS5 authentication. If the endpoints are domain names instead of addresses they shall not be resolved and they shall be forwarded unchanged to the SOCKS proxy service in the client connection request message (address type 0x03 domain name).
OptionaltcpAccept ?: null | stringFilter ZMQ_TCP_ACCEPT_FILTER
Assign a filter that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one filter is applied then new connection source IP should be matched. To clear all filters set to
null. Filter is a string with IPv6 or IPv4 CIDR.OptionaltcpKeepalive ?: numberZMQ_TCP_KEEPALIVE
Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepalive ?: numberCount ZMQ_TCP_KEEPALIVE_CNT
Overrides TCP_KEEPCNT socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepalive ?: numberIdle ZMQ_TCP_KEEPALIVE_IDLE
Overrides TCP_KEEPIDLE / TCP_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepalive ?: numberInterval ZMQ_TCP_KEEPALIVE_INTVL
Overrides TCP_KEEPINTVL socket option (if supported by the OS). The default value of -1 leaves it to the OS default.
OptionaltcpMax ?: numberRetransmit Timeout ZMQ_TCP_MAXRT
Sets how long before an unacknowledged TCP retransmit times out (if supported by the OS). The system normally attempts many TCP retransmits following an exponential backoff strategy. This means that after a network outage, it may take a long time before the session can be re-established. Setting this option allows the timeout to happen at a shorter interval.
OptionaltypeOf ?: numberService ZMQ_TOS
Sets the ToS fields (the Differentiated Services (DS) and Explicit Congestion Notification (ECN) field) of the IP header. The ToS field is typically used to specify a packet's priority. The availability of this option is dependent on intermediate network equipment that inspect the ToS field and provide a path for low-delay, high-throughput, highly-reliable service, etc.
OptionalvmciBuffer ?: numberMax Size ZMQ_VMCI_BUFFER_MAX_SIZE
Maximum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciBuffer ?: numberMin Size ZMQ_VMCI_BUFFER_MIN_SIZE
Minimum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciBuffer ?: numberSize ZMQ_VMCI_BUFFER_SIZE
The size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciConnect ?: numberTimeout ZMQ_VMCI_CONNECT_TIMEOUT
Connection timeout for the socket. For
vmci://transports only.OptionalzapDomain ?: null | stringZMQ_ZAP_DOMAIN
Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the default on all
tcp://connections), ZAP authentication only happens if you set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 for more details.OptionalzapEnforce ?: booleanDomain ZMQ_ZAP_ENFORCE_DOMAIN
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.
Returns Pull
Properties
affinity
ZMQ_AFFINITY
I/O thread affinity, which determines which threads from the ØMQ I/O thread pool associated with the socket's context shall handle newly created connections.
Note: This value is a bit mask, but values higher than Number.MAX_SAFE_INTEGER may not be represented accurately! This currently means that configurations beyond 52 threads are unreliable.
backlog
ZMQ_BACKLOG
Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.
Readonlyclosed
Whether this socket was previously closed with close().
conflate
ZMQ_CONFLATE
If set to true, a socket shall keep only one message in its inbound/outbound queue: the last message to be received/sent. Ignores any high water mark options. Does not support multi-part messages - in particular, only one part of it is kept in the socket internal queue.
connectTimeout
ZMQ_CONNECT_TIMEOUT
Sets how long to wait before timing-out a connect() system call. The connect() system call normally takes a long time before it returns a time out error. Setting this option allows the library to time out the call at an earlier interval.
Readonlycontext
Context that this socket belongs to.
curvePublicKey
ZMQ_CURVE_PUBLICKEY
Sets the socket's long term public key. You must set this on CURVE client sockets. A server socket does not need to know its own public key. You can create a new keypair with curveKeyPair().
curveSecretKey
ZMQ_CURVE_SECRETKEY
Sets the socket's long term secret key. You must set this on both CURVE client and server sockets. You can create a new keypair with curveKeyPair().
curveServer
ZMQ_CURVE_SERVER
Defines whether the socket will act as server for CURVE security. A value of true means the socket will act as CURVE server. A value of false means the socket will not act as CURVE server, and its security role then depends on other option settings.
curveServerKey
ZMQ_CURVE_SERVERKEY
Sets the socket's long term server key. This is the public key of the CURVE server socket. You must set this on CURVE client sockets. This key must have been generated together with the server's secret key. You can create a new keypair with curveKeyPair().
Readonlyevents
Event Observer for this socket. This starts up a ØMQ monitoring socket internally that receives all socket events.
gssapiPlainText
gssapiPrincipal
gssapiPrincipalNameType
gssapiServer
gssapiServicePrincipal
gssapiServicePrincipalNameType
handshakeInterval
ZMQ_HANDSHAKE_IVL
Handshaking is the exchange of socket configuration information (socket type, identity, security) that occurs when a connection is first opened (only for connection-oriented transports). If handshaking does not complete within the configured time, the connection shall be closed. The value 0 means no handshake time limit.
heartbeatInterval
ZMQ_HEARTBEAT_IVL
Interval in milliseconds between sending ZMTP heartbeats for the specified socket. If this option is greater than 0, then a PING ZMTP command will be sent after every interval.
heartbeatTimeout
ZMQ_HEARTBEAT_TIMEOUT
How long (in milliseconds) to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic. This option is only valid if heartbeatInterval is greater than 0. The connection will time out if there is no traffic received after sending the PING command. The received traffic does not have to be a PONG command - any received traffic will cancel the timeout.
heartbeatTimeToLive
ZMQ_HEARTBEAT_TTL
The timeout in milliseconds on the remote peer for ZMTP heartbeats. If this option is greater than 0, the remote side shall time out the connection if it does not receive any more traffic within the TTL period. This option does not have any effect if heartbeatInterval is 0. Internally, this value is rounded down to the nearest decisecond, any value less than 100 will have no effect.
immediate
ZMQ_IMMEDIATE
By default queues will fill on outgoing connections even if the connection has not completed. This can lead to "lost" messages on sockets with round-robin routing (Request, Push, Dealer). If this option is set to true, messages shall be queued only to completed connections. This will cause the socket to block if there are no other connections, but will prevent queues from filling on pipes awaiting connection.
interface
ZMQ_BINDTODEVICE
Binds the socket to the given network interface (Linux only). Allows to use Linux VRF, see: https://www.kernel.org/doc/Documentation/networking/vrf.txt. Requires the program to be ran as root or with CAP_NET_RAW.
ipv6
ZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
ReadonlylastEndpoint
ZMQ_LAST_ENDPOINT
The last endpoint bound for TCP and IPC transports.
linger
ZMQ_LINGER
Determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with close().
loopbackFastPath
ZMQ_LOOPBACK_FASTPATH
Enable faster TCP connections on loopback devices. An application can enable this option to reduce the latency and improve the performance of loopback operations on a TCP socket on Windows.
maxMessageSize
ZMQ_MAXMSGSIZE
Limits the size of the inbound message. If a peer sends a message larger than the limit it is disconnected. Value of -1 means no limit.
multicastMaxTransportDataUnit
ZMQ_MULTICAST_MAXTPDU
Sets the maximum transport data unit size used for outbound multicast packets. This must be set at or below the minimum Maximum Transmission Unit (MTU) for all network paths over which multicast reception is required.
plainPassword
ZMQ_PLAIN_PASSWORD
Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
plainServer
ZMQ_PLAIN_SERVER
Defines whether the socket will act as server for PLAIN security. A value of true means the socket will act as PLAIN server. A value of false means the socket will not act as PLAIN server, and its security role then depends on other option settings.
plainUsername
ZMQ_PLAIN_USERNAME
Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
rate
ZMQ_RATE
Maximum send or receive data rate for multicast transports such as pgm.
Readonlyreadable
Whether any messages are currently available. If true, the next call to Readable.receive() will immediately read a message from the socket. For sockets that cannot receive messsages this is always false.
receiveBufferSize
ZMQ_RCVBUF
Underlying kernel receive buffer size in bytes. A value of -1 means leave the OS default unchanged.
receiveHighWaterMark
ZMQ_RCVHWM
The high water mark is a hard limit on the maximum number of incoming messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
receiveTimeout
ZMQ_RCVTIMEO
Sets the timeout receiving messages on the socket. If the value is 0, receive() will return a rejected promise immediately if there is no message to receive. If the value is -1, it will wait asynchronously until a message is available. For all other values, it will wait for a message for that amount of time before rejecting.
reconnectInterval
ZMQ_RECONNECT_IVL
Period ØMQ shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. The value -1 means no reconnection.
reconnectMaxInterval
ZMQ_RECONNECT_IVL_MAX
Maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled until reconnectMaxInterval is reached. This allows for exponential backoff strategy. Zero (the default) means no exponential backoff is performed and reconnect interval calculations are only based on reconnectInterval.
recoveryInterval
ZMQ_RECOVERY_IVL
Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
ReadonlysecurityMechanism
| null
| "plain"
| "curve"
| "gssapi"
ZMQ_MECHANISM
Returns the current security mechanism for the socket, if any. The security mechanism is set implictly by using any of the relevant security options. The returned value is one of:
null- No security mechanism is used."plain"- The PLAIN mechanism defines a simple username/password mechanism that lets a server authenticate a client. PLAIN makes no attempt at security or confidentiality."curve"- The CURVE mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server. CURVE is intended for use on public networks."gssapi"- The GSSAPI mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server using the Generic Security Service Application Program Interface (GSSAPI). The GSSAPI mechanism can be used on both public and private networks.
socksProxy
ZMQ_SOCKS_PROXY
The SOCKS5 proxy address that shall be used by the socket for the TCP connection(s). Does not support SOCKS5 authentication. If the endpoints are domain names instead of addresses they shall not be resolved and they shall be forwarded unchanged to the SOCKS proxy service in the client connection request message (address type 0x03 domain name).
tcpAcceptFilter
ZMQ_TCP_ACCEPT_FILTER
Assign a filter that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one filter is applied then new connection source IP should be matched. To clear all filters set to null. Filter is a string with IPv6 or IPv4 CIDR.
tcpKeepalive
ZMQ_TCP_KEEPALIVE
Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveCount
ZMQ_TCP_KEEPALIVE_CNT
Overrides TCP_KEEPCNT socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveIdle
ZMQ_TCP_KEEPALIVE_IDLE
Overrides TCP_KEEPIDLE / TCP_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveInterval
ZMQ_TCP_KEEPALIVE_INTVL
Overrides TCP_KEEPINTVL socket option (if supported by the OS). The default value of -1 leaves it to the OS default.
tcpMaxRetransmitTimeout
ZMQ_TCP_MAXRT
Sets how long before an unacknowledged TCP retransmit times out (if supported by the OS). The system normally attempts many TCP retransmits following an exponential backoff strategy. This means that after a network outage, it may take a long time before the session can be re-established. Setting this option allows the timeout to happen at a shorter interval.
ReadonlythreadSafe
ZMQ_THREAD_SAFE
Whether or not the socket is threadsafe. Currently only DRAFT sockets is thread-safe.
Readonlytype
ZMQ_TYPE
Retrieve the socket type. This is fairly useless because you can test the socket class with e.g. socket instanceof Dealer.
typeOfService
ZMQ_TOS
Sets the ToS fields (the Differentiated Services (DS) and Explicit Congestion Notification (ECN) field) of the IP header. The ToS field is typically used to specify a packet's priority. The availability of this option is dependent on intermediate network equipment that inspect the ToS field and provide a path for low-delay, high-throughput, highly-reliable service, etc.
vmciBufferMaxSize
ZMQ_VMCI_BUFFER_MAX_SIZE
Maximum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferMinSize
ZMQ_VMCI_BUFFER_MIN_SIZE
Minimum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferSize
ZMQ_VMCI_BUFFER_SIZE
The size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciConnectTimeout
ZMQ_VMCI_CONNECT_TIMEOUT
Connection timeout for the socket. For vmci:// transports only.
Readonlywritable
Whether any messages can be queued for sending. If true, the next call to Writable.send() will immediately queue a message on the socket. For sockets that cannot send messsages this is always false.
zapDomain
ZMQ_ZAP_DOMAIN
Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the default on all tcp:// connections), ZAP authentication only happens if you set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 for more details.
zapEnforceDomain
ZMQ_ZAP_ENFORCE_DOMAIN
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.
Methods
[asyncIterator]
- [async
Iterator] (): AsyncIterator<Buffer[], undefined, undefined> Asynchronously iterate over messages becoming available on the socket. When the socket is closed with Socket.close(), the iterator will return. Returning early from the iterator will not close the socket unless it also goes out of scope.
for await (const [msg] of socket) {
// handle messages
} -Returns AsyncIterator<Buffer[], undefined, undefined>
bind
- bind(address): Promise<void>
Binds the socket to the given address. During bind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.You can use
*in place of a hostname to bind on all interfaces/addresses, and you can use*in place of a port to bind to a random port (which can be retrieved with lastEndpoint later).await socket.bind("tcp://127.0.0.1:3456")
await socket.bind("tcp://*:3456") // binds on all interfaces
await socket.bind("tcp://127.0.0.1:*") // binds on random port -Parameters
- address: string
Address to bind this socket to.
Returns Promise<void>
Resolved when the socket was successfully bound.
- address: string
close
- close(): void
Closes the socket and disposes of all resources. Any messages that are queued may be discarded or sent in the background depending on the linger setting.
After this method is called, it is no longer possible to call any other methods on this socket.
Sockets that go out of scope and have no Readable.receive() or Writable.send() operations in progress will automatically be closed. Therefore it is not necessary in most applications to call close() manually.
Calling this method on a socket that is already closed is a no-op.
Returns void
connect
disconnect
- disconnect(address): void
Disconnects a previously connected socket from the given address and returns immediately. Disonnection will happen asynchronously in the background.
socket.disconnect("tcp://127.0.0.1:3456") -Parameters
- address: string
The previously connected address to disconnect from.
Returns void
- address: string
ProtectedgetBoolOption
ProtectedgetInt32Option
ProtectedgetInt64Option
ProtectedgetStringOption
ProtectedgetUint32Option
ProtectedgetUint64Option
receive
- receive(): Promise<Buffer[]>
Waits for the next single or multipart message to become availeble on the socket. Reads a message immediately if possible. If no messages can be read, it will wait asynchonously. The promise will be resolved with an array containing the parts of the next message when available.
const [msg] = await socket.receive()
const [part1, part2] = await socket.receive() -Reading may fail (eventually) if the socket has been configured with a receiveTimeout.
A call to receive() is guaranteed to return with a resolved promise immediately if a message could be read from the socket directly.
Only one asynchronously blocking call to receive() can be in progress simultaneously. If you call receive() again on the same socket it will return a rejected promise with an
EBUSYerror. For example, if no messages can be read and noawaitis used:socket.receive() // -> pending promise until read is possible
socket.receive() // -> promise rejection with `EBUSY` error -Note: Due to the nature of Node.js and to avoid blocking the main thread, this method always attempts to read messages with the
ZMQ_DONTWAITflag. It polls asynchronously if reading is not currently possible. This means that all functionality related to timeouts and blocking behaviour is reimplemented in the Node.js bindings. Any differences in behaviour with the native ZMQ library is considered a bug.Returns Promise<Buffer[]>
Resolved with message parts that were successfully read.
ProtectedsetBoolOption
ProtectedsetInt32Option
ProtectedsetInt64Option
ProtectedsetStringOption
ProtectedsetUint32Option
ProtectedsetUint64Option
unbind
- unbind(address): Promise<void>
Unbinds the socket to the given address. During unbind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.Parameters
- address: string
Address to unbind this socket from.
Returns Promise<void>
Resolved when the socket was successfully unbound.
- address: string
Class Pull
A Pull socket is used by a pipeline node to receive messages from upstream pipeline nodes. Messages are fair-queued from among all connected upstream nodes. This socket cannot send messages.
Hierarchy (View Summary)
Index
Constructors
Properties
Methods
Constructors
constructor
- new Pull(
options?: {
affinity?: number;
backlog?: number;
conflate?: boolean;
connectTimeout?: number;
context?: Context;
curvePublicKey?: null | string;
curveSecretKey?: null | string;
curveServer?: boolean;
curveServerKey?: null | string;
gssapiPlainText?: boolean;
gssapiPrincipal?: null | string;
gssapiPrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
gssapiServer?: boolean;
gssapiServicePrincipal?: null | string;
gssapiServicePrincipalNameType?:
| "hostBased"
| "userName"
| "krb5Principal";
handshakeInterval?: number;
heartbeatInterval?: number;
heartbeatTimeout?: number;
heartbeatTimeToLive?: number;
immediate?: boolean;
interface?: null
| string;
ipv6?: boolean;
linger?: number;
loopbackFastPath?: boolean;
maxMessageSize?: number;
multicastMaxTransportDataUnit?: number;
plainPassword?: null | string;
plainServer?: boolean;
plainUsername?: null | string;
rate?: number;
receiveBufferSize?: number;
receiveHighWaterMark?: number;
receiveTimeout?: number;
reconnectInterval?: number;
reconnectMaxInterval?: number;
recoveryInterval?: number;
socksProxy?: null | string;
tcpAcceptFilter?: null | string;
tcpKeepalive?: number;
tcpKeepaliveCount?: number;
tcpKeepaliveIdle?: number;
tcpKeepaliveInterval?: number;
tcpMaxRetransmitTimeout?: number;
typeOfService?: number;
vmciBufferMaxSize?: number;
vmciBufferMinSize?: number;
vmciBufferSize?: number;
vmciConnectTimeout?: number;
zapDomain?: null | string;
zapEnforceDomain?: boolean;
},
): Pull Parameters
Optionaloptions: {
affinity?: number;
backlog?: number;
conflate?: boolean;
connectTimeout?: number;
context?: Context;
curvePublicKey?: null | string;
curveSecretKey?: null | string;
curveServer?: boolean;
curveServerKey?: null | string;
gssapiPlainText?: boolean;
gssapiPrincipal?: null | string;
gssapiPrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
gssapiServer?: boolean;
gssapiServicePrincipal?: null | string;
gssapiServicePrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
handshakeInterval?: number;
heartbeatInterval?: number;
heartbeatTimeout?: number;
heartbeatTimeToLive?: number;
immediate?: boolean;
interface?: null | string;
ipv6?: boolean;
linger?: number;
loopbackFastPath?: boolean;
maxMessageSize?: number;
multicastMaxTransportDataUnit?: number;
plainPassword?: null | string;
plainServer?: boolean;
plainUsername?: null | string;
rate?: number;
receiveBufferSize?: number;
receiveHighWaterMark?: number;
receiveTimeout?: number;
reconnectInterval?: number;
reconnectMaxInterval?: number;
recoveryInterval?: number;
socksProxy?: null | string;
tcpAcceptFilter?: null | string;
tcpKeepalive?: number;
tcpKeepaliveCount?: number;
tcpKeepaliveIdle?: number;
tcpKeepaliveInterval?: number;
tcpMaxRetransmitTimeout?: number;
typeOfService?: number;
vmciBufferMaxSize?: number;
vmciBufferMinSize?: number;
vmciBufferSize?: number;
vmciConnectTimeout?: number;
zapDomain?: null | string;
zapEnforceDomain?: boolean;
}Optionalaffinity?: numberZMQ_AFFINITY
I/O thread affinity, which determines which threads from the ØMQ I/O thread pool associated with the socket's context shall handle newly created connections.
Note: This value is a bit mask, but values higher than
Number.MAX_SAFE_INTEGERmay not be represented accurately! This currently means that configurations beyond 52 threads are unreliable.Optionalbacklog?: numberZMQ_BACKLOG
Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.
Optionalconflate?: booleanZMQ_CONFLATE
If set to
true, a socket shall keep only one message in its inbound/outbound queue: the last message to be received/sent. Ignores any high water mark options. Does not support multi-part messages - in particular, only one part of it is kept in the socket internal queue.OptionalconnectTimeout?: numberZMQ_CONNECT_TIMEOUT
Sets how long to wait before timing-out a connect() system call. The connect() system call normally takes a long time before it returns a time out error. Setting this option allows the library to time out the call at an earlier interval.
Optionalcontext?: ContextOptionalcurvePublicKey?: null | stringZMQ_CURVE_PUBLICKEY
Sets the socket's long term public key. You must set this on CURVE client sockets. A server socket does not need to know its own public key. You can create a new keypair with curveKeyPair().
OptionalcurveSecretKey?: null | stringZMQ_CURVE_SECRETKEY
Sets the socket's long term secret key. You must set this on both CURVE client and server sockets. You can create a new keypair with curveKeyPair().
OptionalcurveServer?: booleanZMQ_CURVE_SERVER
Defines whether the socket will act as server for CURVE security. A value of
truemeans the socket will act as CURVE server. A value offalsemeans the socket will not act as CURVE server, and its security role then depends on other option settings.OptionalcurveServerKey?: null | stringZMQ_CURVE_SERVERKEY
Sets the socket's long term server key. This is the public key of the CURVE server socket. You must set this on CURVE client sockets. This key must have been generated together with the server's secret key. You can create a new keypair with curveKeyPair().
OptionalgssapiPlainText?: booleanOptionalgssapiPrincipal?: null | stringOptionalgssapiPrincipalNameType?: "hostBased" | "userName" | "krb5Principal"OptionalgssapiServer?: booleanOptionalgssapiServicePrincipal?: null | stringOptionalgssapiServicePrincipalNameType?: "hostBased" | "userName" | "krb5Principal"OptionalhandshakeInterval?: numberZMQ_HANDSHAKE_IVL
Handshaking is the exchange of socket configuration information (socket type, identity, security) that occurs when a connection is first opened (only for connection-oriented transports). If handshaking does not complete within the configured time, the connection shall be closed. The value 0 means no handshake time limit.
OptionalheartbeatInterval?: numberZMQ_HEARTBEAT_IVL
Interval in milliseconds between sending ZMTP heartbeats for the specified socket. If this option is greater than 0, then a PING ZMTP command will be sent after every interval.
OptionalheartbeatTimeout?: numberZMQ_HEARTBEAT_TIMEOUT
How long (in milliseconds) to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic. This option is only valid if heartbeatInterval is greater than 0. The connection will time out if there is no traffic received after sending the PING command. The received traffic does not have to be a PONG command - any received traffic will cancel the timeout.
OptionalheartbeatTimeToLive?: numberZMQ_HEARTBEAT_TTL
The timeout in milliseconds on the remote peer for ZMTP heartbeats. If this option is greater than 0, the remote side shall time out the connection if it does not receive any more traffic within the TTL period. This option does not have any effect if heartbeatInterval is 0. Internally, this value is rounded down to the nearest decisecond, any value less than 100 will have no effect.
Optionalimmediate?: booleanZMQ_IMMEDIATE
By default queues will fill on outgoing connections even if the connection has not completed. This can lead to "lost" messages on sockets with round-robin routing (Request, Push, Dealer). If this option is set to
true, messages shall be queued only to completed connections. This will cause the socket to block if there are no other connections, but will prevent queues from filling on pipes awaiting connection.Optionalinterface?: null | stringZMQ_BINDTODEVICE
Binds the socket to the given network interface (Linux only). Allows to use Linux VRF, see: https://www.kernel.org/doc/Documentation/networking/vrf.txt. Requires the program to be ran as root or with
CAP_NET_RAW.Optionalipv6?: booleanZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
Optionallinger?: numberZMQ_LINGER
Determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with close().
OptionalloopbackFastPath?: booleanZMQ_LOOPBACK_FASTPATH
Enable faster TCP connections on loopback devices. An application can enable this option to reduce the latency and improve the performance of loopback operations on a TCP socket on Windows.
OptionalmaxMessageSize?: numberZMQ_MAXMSGSIZE
Limits the size of the inbound message. If a peer sends a message larger than the limit it is disconnected. Value of -1 means no limit.
OptionalmulticastMaxTransportDataUnit?: numberZMQ_MULTICAST_MAXTPDU
Sets the maximum transport data unit size used for outbound multicast packets. This must be set at or below the minimum Maximum Transmission Unit (MTU) for all network paths over which multicast reception is required.
OptionalplainPassword?: null | stringZMQ_PLAIN_PASSWORD
Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
OptionalplainServer?: booleanZMQ_PLAIN_SERVER
Defines whether the socket will act as server for PLAIN security. A value of
truemeans the socket will act as PLAIN server. A value offalsemeans the socket will not act as PLAIN server, and its security role then depends on other option settings.OptionalplainUsername?: null | stringZMQ_PLAIN_USERNAME
Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
Optionalrate?: numberZMQ_RATE
Maximum send or receive data rate for multicast transports such as
pgm.OptionalreceiveBufferSize?: numberZMQ_RCVBUF
Underlying kernel receive buffer size in bytes. A value of -1 means leave the OS default unchanged.
OptionalreceiveHighWaterMark?: numberZMQ_RCVHWM
The high water mark is a hard limit on the maximum number of incoming messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
OptionalreceiveTimeout?: numberZMQ_RCVTIMEO
Sets the timeout receiving messages on the socket. If the value is 0, receive() will return a rejected promise immediately if there is no message to receive. If the value is -1, it will wait asynchronously until a message is available. For all other values, it will wait for a message for that amount of time before rejecting.
OptionalreconnectInterval?: numberZMQ_RECONNECT_IVL
Period ØMQ shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. The value -1 means no reconnection.
OptionalreconnectMaxInterval?: numberZMQ_RECONNECT_IVL_MAX
Maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled until reconnectMaxInterval is reached. This allows for exponential backoff strategy. Zero (the default) means no exponential backoff is performed and reconnect interval calculations are only based on reconnectInterval.
OptionalrecoveryInterval?: numberZMQ_RECOVERY_IVL
Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
OptionalsocksProxy?: null | stringZMQ_SOCKS_PROXY
The SOCKS5 proxy address that shall be used by the socket for the TCP connection(s). Does not support SOCKS5 authentication. If the endpoints are domain names instead of addresses they shall not be resolved and they shall be forwarded unchanged to the SOCKS proxy service in the client connection request message (address type 0x03 domain name).
OptionaltcpAcceptFilter?: null | stringZMQ_TCP_ACCEPT_FILTER
Assign a filter that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one filter is applied then new connection source IP should be matched. To clear all filters set to
null. Filter is a string with IPv6 or IPv4 CIDR.OptionaltcpKeepalive?: numberZMQ_TCP_KEEPALIVE
Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepaliveCount?: numberZMQ_TCP_KEEPALIVE_CNT
Overrides TCP_KEEPCNT socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepaliveIdle?: numberZMQ_TCP_KEEPALIVE_IDLE
Overrides TCP_KEEPIDLE / TCP_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepaliveInterval?: numberZMQ_TCP_KEEPALIVE_INTVL
Overrides TCP_KEEPINTVL socket option (if supported by the OS). The default value of -1 leaves it to the OS default.
OptionaltcpMaxRetransmitTimeout?: numberZMQ_TCP_MAXRT
Sets how long before an unacknowledged TCP retransmit times out (if supported by the OS). The system normally attempts many TCP retransmits following an exponential backoff strategy. This means that after a network outage, it may take a long time before the session can be re-established. Setting this option allows the timeout to happen at a shorter interval.
OptionaltypeOfService?: numberZMQ_TOS
Sets the ToS fields (the Differentiated Services (DS) and Explicit Congestion Notification (ECN) field) of the IP header. The ToS field is typically used to specify a packet's priority. The availability of this option is dependent on intermediate network equipment that inspect the ToS field and provide a path for low-delay, high-throughput, highly-reliable service, etc.
OptionalvmciBufferMaxSize?: numberZMQ_VMCI_BUFFER_MAX_SIZE
Maximum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciBufferMinSize?: numberZMQ_VMCI_BUFFER_MIN_SIZE
Minimum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciBufferSize?: numberZMQ_VMCI_BUFFER_SIZE
The size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciConnectTimeout?: numberZMQ_VMCI_CONNECT_TIMEOUT
Connection timeout for the socket. For
vmci://transports only.OptionalzapDomain?: null | stringZMQ_ZAP_DOMAIN
Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the default on all
tcp://connections), ZAP authentication only happens if you set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 for more details.OptionalzapEnforceDomain?: booleanZMQ_ZAP_ENFORCE_DOMAIN
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.
Returns Pull
Properties
affinity
ZMQ_AFFINITY
I/O thread affinity, which determines which threads from the ØMQ I/O thread pool associated with the socket's context shall handle newly created connections.
Note: This value is a bit mask, but values higher than Number.MAX_SAFE_INTEGER may not be represented accurately! This currently means that configurations beyond 52 threads are unreliable.
backlog
ZMQ_BACKLOG
Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.
Readonlyclosed
Whether this socket was previously closed with close().
conflate
ZMQ_CONFLATE
If set to true, a socket shall keep only one message in its inbound/outbound queue: the last message to be received/sent. Ignores any high water mark options. Does not support multi-part messages - in particular, only one part of it is kept in the socket internal queue.
connectTimeout
ZMQ_CONNECT_TIMEOUT
Sets how long to wait before timing-out a connect() system call. The connect() system call normally takes a long time before it returns a time out error. Setting this option allows the library to time out the call at an earlier interval.
Readonlycontext
Context that this socket belongs to.
curvePublicKey
ZMQ_CURVE_PUBLICKEY
Sets the socket's long term public key. You must set this on CURVE client sockets. A server socket does not need to know its own public key. You can create a new keypair with curveKeyPair().
curveSecretKey
ZMQ_CURVE_SECRETKEY
Sets the socket's long term secret key. You must set this on both CURVE client and server sockets. You can create a new keypair with curveKeyPair().
curveServer
ZMQ_CURVE_SERVER
Defines whether the socket will act as server for CURVE security. A value of true means the socket will act as CURVE server. A value of false means the socket will not act as CURVE server, and its security role then depends on other option settings.
curveServerKey
ZMQ_CURVE_SERVERKEY
Sets the socket's long term server key. This is the public key of the CURVE server socket. You must set this on CURVE client sockets. This key must have been generated together with the server's secret key. You can create a new keypair with curveKeyPair().
Readonlyevents
Event Observer for this socket. This starts up a ØMQ monitoring socket internally that receives all socket events.
gssapiPlainText
gssapiPrincipal
gssapiPrincipalNameType
gssapiServer
gssapiServicePrincipal
gssapiServicePrincipalNameType
handshakeInterval
ZMQ_HANDSHAKE_IVL
Handshaking is the exchange of socket configuration information (socket type, identity, security) that occurs when a connection is first opened (only for connection-oriented transports). If handshaking does not complete within the configured time, the connection shall be closed. The value 0 means no handshake time limit.
heartbeatInterval
ZMQ_HEARTBEAT_IVL
Interval in milliseconds between sending ZMTP heartbeats for the specified socket. If this option is greater than 0, then a PING ZMTP command will be sent after every interval.
heartbeatTimeout
ZMQ_HEARTBEAT_TIMEOUT
How long (in milliseconds) to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic. This option is only valid if heartbeatInterval is greater than 0. The connection will time out if there is no traffic received after sending the PING command. The received traffic does not have to be a PONG command - any received traffic will cancel the timeout.
heartbeatTimeToLive
ZMQ_HEARTBEAT_TTL
The timeout in milliseconds on the remote peer for ZMTP heartbeats. If this option is greater than 0, the remote side shall time out the connection if it does not receive any more traffic within the TTL period. This option does not have any effect if heartbeatInterval is 0. Internally, this value is rounded down to the nearest decisecond, any value less than 100 will have no effect.
immediate
ZMQ_IMMEDIATE
By default queues will fill on outgoing connections even if the connection has not completed. This can lead to "lost" messages on sockets with round-robin routing (Request, Push, Dealer). If this option is set to true, messages shall be queued only to completed connections. This will cause the socket to block if there are no other connections, but will prevent queues from filling on pipes awaiting connection.
interface
ZMQ_BINDTODEVICE
Binds the socket to the given network interface (Linux only). Allows to use Linux VRF, see: https://www.kernel.org/doc/Documentation/networking/vrf.txt. Requires the program to be ran as root or with CAP_NET_RAW.
ipv6
ZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
ReadonlylastEndpoint
ZMQ_LAST_ENDPOINT
The last endpoint bound for TCP and IPC transports.
linger
ZMQ_LINGER
Determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with close().
loopbackFastPath
ZMQ_LOOPBACK_FASTPATH
Enable faster TCP connections on loopback devices. An application can enable this option to reduce the latency and improve the performance of loopback operations on a TCP socket on Windows.
maxMessageSize
ZMQ_MAXMSGSIZE
Limits the size of the inbound message. If a peer sends a message larger than the limit it is disconnected. Value of -1 means no limit.
multicastMaxTransportDataUnit
ZMQ_MULTICAST_MAXTPDU
Sets the maximum transport data unit size used for outbound multicast packets. This must be set at or below the minimum Maximum Transmission Unit (MTU) for all network paths over which multicast reception is required.
plainPassword
ZMQ_PLAIN_PASSWORD
Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
plainServer
ZMQ_PLAIN_SERVER
Defines whether the socket will act as server for PLAIN security. A value of true means the socket will act as PLAIN server. A value of false means the socket will not act as PLAIN server, and its security role then depends on other option settings.
plainUsername
ZMQ_PLAIN_USERNAME
Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
rate
ZMQ_RATE
Maximum send or receive data rate for multicast transports such as pgm.
Readonlyreadable
Whether any messages are currently available. If true, the next call to Readable.receive() will immediately read a message from the socket. For sockets that cannot receive messsages this is always false.
receiveBufferSize
ZMQ_RCVBUF
Underlying kernel receive buffer size in bytes. A value of -1 means leave the OS default unchanged.
receiveHighWaterMark
ZMQ_RCVHWM
The high water mark is a hard limit on the maximum number of incoming messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
receiveTimeout
ZMQ_RCVTIMEO
Sets the timeout receiving messages on the socket. If the value is 0, receive() will return a rejected promise immediately if there is no message to receive. If the value is -1, it will wait asynchronously until a message is available. For all other values, it will wait for a message for that amount of time before rejecting.
reconnectInterval
ZMQ_RECONNECT_IVL
Period ØMQ shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. The value -1 means no reconnection.
reconnectMaxInterval
ZMQ_RECONNECT_IVL_MAX
Maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled until reconnectMaxInterval is reached. This allows for exponential backoff strategy. Zero (the default) means no exponential backoff is performed and reconnect interval calculations are only based on reconnectInterval.
recoveryInterval
ZMQ_RECOVERY_IVL
Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
ReadonlysecurityMechanism
ZMQ_MECHANISM
Returns the current security mechanism for the socket, if any. The security mechanism is set implictly by using any of the relevant security options. The returned value is one of:
null- No security mechanism is used."plain"- The PLAIN mechanism defines a simple username/password mechanism that lets a server authenticate a client. PLAIN makes no attempt at security or confidentiality."curve"- The CURVE mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server. CURVE is intended for use on public networks."gssapi"- The GSSAPI mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server using the Generic Security Service Application Program Interface (GSSAPI). The GSSAPI mechanism can be used on both public and private networks.
socksProxy
ZMQ_SOCKS_PROXY
The SOCKS5 proxy address that shall be used by the socket for the TCP connection(s). Does not support SOCKS5 authentication. If the endpoints are domain names instead of addresses they shall not be resolved and they shall be forwarded unchanged to the SOCKS proxy service in the client connection request message (address type 0x03 domain name).
tcpAcceptFilter
ZMQ_TCP_ACCEPT_FILTER
Assign a filter that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one filter is applied then new connection source IP should be matched. To clear all filters set to null. Filter is a string with IPv6 or IPv4 CIDR.
tcpKeepalive
ZMQ_TCP_KEEPALIVE
Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveCount
ZMQ_TCP_KEEPALIVE_CNT
Overrides TCP_KEEPCNT socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveIdle
ZMQ_TCP_KEEPALIVE_IDLE
Overrides TCP_KEEPIDLE / TCP_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveInterval
ZMQ_TCP_KEEPALIVE_INTVL
Overrides TCP_KEEPINTVL socket option (if supported by the OS). The default value of -1 leaves it to the OS default.
tcpMaxRetransmitTimeout
ZMQ_TCP_MAXRT
Sets how long before an unacknowledged TCP retransmit times out (if supported by the OS). The system normally attempts many TCP retransmits following an exponential backoff strategy. This means that after a network outage, it may take a long time before the session can be re-established. Setting this option allows the timeout to happen at a shorter interval.
ReadonlythreadSafe
ZMQ_THREAD_SAFE
Whether or not the socket is threadsafe. Currently only DRAFT sockets is thread-safe.
Readonlytype
ZMQ_TYPE
Retrieve the socket type. This is fairly useless because you can test the socket class with e.g. socket instanceof Dealer.
typeOfService
ZMQ_TOS
Sets the ToS fields (the Differentiated Services (DS) and Explicit Congestion Notification (ECN) field) of the IP header. The ToS field is typically used to specify a packet's priority. The availability of this option is dependent on intermediate network equipment that inspect the ToS field and provide a path for low-delay, high-throughput, highly-reliable service, etc.
vmciBufferMaxSize
ZMQ_VMCI_BUFFER_MAX_SIZE
Maximum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferMinSize
ZMQ_VMCI_BUFFER_MIN_SIZE
Minimum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferSize
ZMQ_VMCI_BUFFER_SIZE
The size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciConnectTimeout
ZMQ_VMCI_CONNECT_TIMEOUT
Connection timeout for the socket. For vmci:// transports only.
Readonlywritable
Whether any messages can be queued for sending. If true, the next call to Writable.send() will immediately queue a message on the socket. For sockets that cannot send messsages this is always false.
zapDomain
ZMQ_ZAP_DOMAIN
Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the default on all tcp:// connections), ZAP authentication only happens if you set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 for more details.
zapEnforceDomain
ZMQ_ZAP_ENFORCE_DOMAIN
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.
Methods
[asyncIterator]
- "[asyncIterator]"(): AsyncIterator<Buffer[]>
Asynchronously iterate over messages becoming available on the socket. When the socket is closed with Socket.close(), the iterator will return. Returning early from the iterator will not close the socket unless it also goes out of scope.
for await (const [msg] of socket) {
// handle messages
} +Returns AsyncIterator<Buffer[]>
bind
- bind(address: string): Promise<void>
Binds the socket to the given address. During bind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.You can use
*in place of a hostname to bind on all interfaces/addresses, and you can use*in place of a port to bind to a random port (which can be retrieved with lastEndpoint later).await socket.bind("tcp://127.0.0.1:3456")
await socket.bind("tcp://*:3456") // binds on all interfaces
await socket.bind("tcp://127.0.0.1:*") // binds on random port +Parameters
- address: string
Address to bind this socket to.
Returns Promise<void>
Resolved when the socket was successfully bound.
- address: string
bindSync
- bindSync(address: string): void
Binds the socket to the given address. During bind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.You can use
*in place of a hostname to bind on all interfaces/addresses, and you can use*in place of a port to bind to a random port (which can be retrieved with lastEndpoint later).socket.bindSync("tcp://127.0.0.1:3456")
socket.bindSync("tcp://*:3456") // binds on all interfaces
socket.bindSync("tcp://127.0.0.1:*") // binds on random port +Parameters
- address: string
Address to bind this socket to.
Returns void
Resolved when the socket was successfully bound.
- address: string
close
- close(): void
Closes the socket and disposes of all resources. Any messages that are queued may be discarded or sent in the background depending on the linger setting.
After this method is called, it is no longer possible to call any other methods on this socket.
Sockets that go out of scope and have no Readable.receive() or Writable.send() operations in progress will automatically be closed. Therefore it is not necessary in most applications to call close() manually.
Calling this method on a socket that is already closed is a no-op.
Returns void
connect
disconnect
- disconnect(address: string): void
Disconnects a previously connected socket from the given address and returns immediately. Disonnection will happen asynchronously in the background.
socket.disconnect("tcp://127.0.0.1:3456") +Parameters
- address: string
The previously connected address to disconnect from.
Returns void
- address: string
ProtectedgetBoolOption
ProtectedgetInt32Option
ProtectedgetInt64Option
ProtectedgetStringOption
ProtectedgetUint32Option
ProtectedgetUint64Option
receive
- receive(): Promise<Buffer[]>
Waits for the next single or multipart message to become availeble on the socket. Reads a message immediately if possible. If no messages can be read, it will wait asynchonously. The promise will be resolved with an array containing the parts of the next message when available.
const [msg] = await socket.receive()
const [part1, part2] = await socket.receive() +Reading may fail (eventually) if the socket has been configured with a receiveTimeout.
A call to receive() is guaranteed to return with a resolved promise immediately if a message could be read from the socket directly.
Only one asynchronously blocking call to receive() can be in progress simultaneously. If you call receive() again on the same socket it will return a rejected promise with an
EBUSYerror. For example, if no messages can be read and noawaitis used:socket.receive() // -> pending promise until read is possible
socket.receive() // -> promise rejection with `EBUSY` error +Note: Due to the nature of Node.js and to avoid blocking the main thread, this method always attempts to read messages with the
ZMQ_DONTWAITflag. It polls asynchronously if reading is not currently possible. This means that all functionality related to timeouts and blocking behaviour is reimplemented in the Node.js bindings. Any differences in behaviour with the native ZMQ library is considered a bug.Returns Promise<Buffer[]>
Resolved with message parts that were successfully read.
ProtectedsetBoolOption
ProtectedsetInt32Option
ProtectedsetInt64Option
ProtectedsetStringOption
ProtectedsetUint32Option
ProtectedsetUint64Option
unbind
- unbind(address: string): Promise<void>
Unbinds the socket to the given address. During unbind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.Parameters
- address: string
Address to unbind this socket from.
Returns Promise<void>
Resolved when the socket was successfully unbound.
- address: string
unbindSync
- unbindSync(address: string): void
Unbinds the socket to the given address. During unbind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.Parameters
- address: string
Address to unbind this socket from.
Returns void
Resolved when the socket was successfully unbound.
- address: string
Class Push
A Push socket is used by a pipeline node to send messages to downstream pipeline nodes. Messages are round-robined to all connected downstream nodes. This socket cannot receive messages.
When a Push socket enters the mute state due to having reached the high water mark for all downstream nodes, or if there are no downstream nodes at all, then Writable.send() will block until the mute state ends or at least one downstream node becomes available for sending; messages are not discarded.
Hierarchy (view full)
Index
Constructors
Properties
Methods
Constructors
constructor
- new
Push (options?): Push Parameters
Optionaloptions: {
affinity?: number;
backlog?: number;
conflate?: boolean;
connectTimeout?: number;
context?: Context;
curvePublicKey?: null | string;
curveSecretKey?: null | string;
curveServer?: boolean;
curveServerKey?: null | string;
gssapiPlainText?: boolean;
gssapiPrincipal?: null | string;
gssapiPrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
gssapiServer?: boolean;
gssapiServicePrincipal?: null | string;
gssapiServicePrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
handshakeInterval?: number;
heartbeatInterval?: number;
heartbeatTimeout?: number;
heartbeatTimeToLive?: number;
immediate?: boolean;
interface?: null | string;
ipv6?: boolean;
linger?: number;
loopbackFastPath?: boolean;
maxMessageSize?: number;
multicastHops?: number;
multicastMaxTransportDataUnit?: number;
plainPassword?: null | string;
plainServer?: boolean;
plainUsername?: null | string;
rate?: number;
reconnectInterval?: number;
reconnectMaxInterval?: number;
recoveryInterval?: number;
sendBufferSize?: number;
sendHighWaterMark?: number;
sendTimeout?: number;
socksProxy?: null | string;
tcpAcceptFilter?: null | string;
tcpKeepalive?: number;
tcpKeepaliveCount?: number;
tcpKeepaliveIdle?: number;
tcpKeepaliveInterval?: number;
tcpMaxRetransmitTimeout?: number;
typeOfService?: number;
vmciBufferMaxSize?: number;
vmciBufferMinSize?: number;
vmciBufferSize?: number;
vmciConnectTimeout?: number;
zapDomain?: null | string;
zapEnforceDomain?: boolean;
}Optionalaffinity?: numberZMQ_AFFINITY
I/O thread affinity, which determines which threads from the ØMQ I/O thread pool associated with the socket's context shall handle newly created connections.
Note: This value is a bit mask, but values higher than
Number.MAX_SAFE_INTEGERmay not be represented accurately! This currently means that configurations beyond 52 threads are unreliable.Optionalbacklog?: numberZMQ_BACKLOG
Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.
Optionalconflate?: booleanZMQ_CONFLATE
If set to
true, a socket shall keep only one message in its inbound/outbound queue: the last message to be received/sent. Ignores any high water mark options. Does not support multi-part messages - in particular, only one part of it is kept in the socket internal queue.OptionalconnectTimeout ?: numberZMQ_CONNECT_TIMEOUT
Sets how long to wait before timing-out a connect() system call. The connect() system call normally takes a long time before it returns a time out error. Setting this option allows the library to time out the call at an earlier interval.
Optionalcontext?: ContextOptionalcurvePublic ?: null | stringKey ZMQ_CURVE_PUBLICKEY
Sets the socket's long term public key. You must set this on CURVE client sockets. A server socket does not need to know its own public key. You can create a new keypair with curveKeyPair().
OptionalcurveSecret ?: null | stringKey ZMQ_CURVE_SECRETKEY
Sets the socket's long term secret key. You must set this on both CURVE client and server sockets. You can create a new keypair with curveKeyPair().
OptionalcurveServer ?: booleanZMQ_CURVE_SERVER
Defines whether the socket will act as server for CURVE security. A value of
truemeans the socket will act as CURVE server. A value offalsemeans the socket will not act as CURVE server, and its security role then depends on other option settings.OptionalcurveServer ?: null | stringKey ZMQ_CURVE_SERVERKEY
Sets the socket's long term server key. This is the public key of the CURVE server socket. You must set this on CURVE client sockets. This key must have been generated together with the server's secret key. You can create a new keypair with curveKeyPair().
OptionalgssapiPlain ?: booleanText OptionalgssapiPrincipal ?: null | stringOptionalgssapiPrincipal ?: "hostBased" | "userName" | "krb5Principal"Name Type OptionalgssapiServer ?: booleanOptionalgssapiService ?: null | stringPrincipal OptionalgssapiService ?: "hostBased" | "userName" | "krb5Principal"Principal Name Type OptionalhandshakeInterval ?: numberZMQ_HANDSHAKE_IVL
Handshaking is the exchange of socket configuration information (socket type, identity, security) that occurs when a connection is first opened (only for connection-oriented transports). If handshaking does not complete within the configured time, the connection shall be closed. The value 0 means no handshake time limit.
OptionalheartbeatInterval ?: numberZMQ_HEARTBEAT_IVL
Interval in milliseconds between sending ZMTP heartbeats for the specified socket. If this option is greater than 0, then a PING ZMTP command will be sent after every interval.
OptionalheartbeatTimeout ?: numberZMQ_HEARTBEAT_TIMEOUT
How long (in milliseconds) to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic. This option is only valid if heartbeatInterval is greater than 0. The connection will time out if there is no traffic received after sending the PING command. The received traffic does not have to be a PONG command - any received traffic will cancel the timeout.
OptionalheartbeatTime ?: numberTo Live ZMQ_HEARTBEAT_TTL
The timeout in milliseconds on the remote peer for ZMTP heartbeats. If this option is greater than 0, the remote side shall time out the connection if it does not receive any more traffic within the TTL period. This option does not have any effect if heartbeatInterval is 0. Internally, this value is rounded down to the nearest decisecond, any value less than 100 will have no effect.
Optionalimmediate?: booleanZMQ_IMMEDIATE
By default queues will fill on outgoing connections even if the connection has not completed. This can lead to "lost" messages on sockets with round-robin routing (Request, Push, Dealer). If this option is set to
true, messages shall be queued only to completed connections. This will cause the socket to block if there are no other connections, but will prevent queues from filling on pipes awaiting connection.Optionalinterface?: null | stringZMQ_BINDTODEVICE
Binds the socket to the given network interface (Linux only). Allows to use Linux VRF, see: https://www.kernel.org/doc/Documentation/networking/vrf.txt. Requires the program to be ran as root or with
CAP_NET_RAW.Optionalipv6?: booleanZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
Optionallinger?: numberZMQ_LINGER
Determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with close().
OptionalloopbackFast ?: booleanPath ZMQ_LOOPBACK_FASTPATH
Enable faster TCP connections on loopback devices. An application can enable this option to reduce the latency and improve the performance of loopback operations on a TCP socket on Windows.
OptionalmaxMessage ?: numberSize ZMQ_MAXMSGSIZE
Limits the size of the inbound message. If a peer sends a message larger than the limit it is disconnected. Value of -1 means no limit.
OptionalmulticastHops ?: numberZMQ_MULTICAST_HOPS
Sets the time-to-live field in every multicast packet sent from this socket. The default is 1 which means that the multicast packets don't leave the local network.
OptionalmulticastMax ?: numberTransport Data Unit ZMQ_MULTICAST_MAXTPDU
Sets the maximum transport data unit size used for outbound multicast packets. This must be set at or below the minimum Maximum Transmission Unit (MTU) for all network paths over which multicast reception is required.
OptionalplainPassword ?: null | stringZMQ_PLAIN_PASSWORD
Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
OptionalplainServer ?: booleanZMQ_PLAIN_SERVER
Defines whether the socket will act as server for PLAIN security. A value of
truemeans the socket will act as PLAIN server. A value offalsemeans the socket will not act as PLAIN server, and its security role then depends on other option settings.OptionalplainUsername ?: null | stringZMQ_PLAIN_USERNAME
Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
Optionalrate?: numberZMQ_RATE
Maximum send or receive data rate for multicast transports such as
pgm.OptionalreconnectInterval ?: numberZMQ_RECONNECT_IVL
Period ØMQ shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. The value -1 means no reconnection.
OptionalreconnectMax ?: numberInterval ZMQ_RECONNECT_IVL_MAX
Maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled until reconnectMaxInterval is reached. This allows for exponential backoff strategy. Zero (the default) means no exponential backoff is performed and reconnect interval calculations are only based on reconnectInterval.
OptionalrecoveryInterval ?: numberZMQ_RECOVERY_IVL
Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
OptionalsendBuffer ?: numberSize ZMQ_SNDBUF
Underlying kernel transmit buffer size in bytes. A value of -1 means leave the OS default unchanged.
OptionalsendHigh ?: numberWater Mark ZMQ_SNDHWM
The high water mark is a hard limit on the maximum number of outgoing messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
OptionalsendTimeout ?: numberZMQ_SNDTIMEO
Sets the timeout for sending messages on the socket. If the value is 0, send() will return a rejected promise immediately if the message cannot be sent. If the value is -1, it will wait asynchronously until the message is sent. For all other values, it will try to send the message for that amount of time before rejecting.
OptionalsocksProxy ?: null | stringZMQ_SOCKS_PROXY
The SOCKS5 proxy address that shall be used by the socket for the TCP connection(s). Does not support SOCKS5 authentication. If the endpoints are domain names instead of addresses they shall not be resolved and they shall be forwarded unchanged to the SOCKS proxy service in the client connection request message (address type 0x03 domain name).
OptionaltcpAccept ?: null | stringFilter ZMQ_TCP_ACCEPT_FILTER
Assign a filter that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one filter is applied then new connection source IP should be matched. To clear all filters set to
null. Filter is a string with IPv6 or IPv4 CIDR.OptionaltcpKeepalive ?: numberZMQ_TCP_KEEPALIVE
Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepalive ?: numberCount ZMQ_TCP_KEEPALIVE_CNT
Overrides TCP_KEEPCNT socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepalive ?: numberIdle ZMQ_TCP_KEEPALIVE_IDLE
Overrides TCP_KEEPIDLE / TCP_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepalive ?: numberInterval ZMQ_TCP_KEEPALIVE_INTVL
Overrides TCP_KEEPINTVL socket option (if supported by the OS). The default value of -1 leaves it to the OS default.
OptionaltcpMax ?: numberRetransmit Timeout ZMQ_TCP_MAXRT
Sets how long before an unacknowledged TCP retransmit times out (if supported by the OS). The system normally attempts many TCP retransmits following an exponential backoff strategy. This means that after a network outage, it may take a long time before the session can be re-established. Setting this option allows the timeout to happen at a shorter interval.
OptionaltypeOf ?: numberService ZMQ_TOS
Sets the ToS fields (the Differentiated Services (DS) and Explicit Congestion Notification (ECN) field) of the IP header. The ToS field is typically used to specify a packet's priority. The availability of this option is dependent on intermediate network equipment that inspect the ToS field and provide a path for low-delay, high-throughput, highly-reliable service, etc.
OptionalvmciBuffer ?: numberMax Size ZMQ_VMCI_BUFFER_MAX_SIZE
Maximum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciBuffer ?: numberMin Size ZMQ_VMCI_BUFFER_MIN_SIZE
Minimum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciBuffer ?: numberSize ZMQ_VMCI_BUFFER_SIZE
The size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciConnect ?: numberTimeout ZMQ_VMCI_CONNECT_TIMEOUT
Connection timeout for the socket. For
vmci://transports only.OptionalzapDomain ?: null | stringZMQ_ZAP_DOMAIN
Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the default on all
tcp://connections), ZAP authentication only happens if you set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 for more details.OptionalzapEnforce ?: booleanDomain ZMQ_ZAP_ENFORCE_DOMAIN
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.
Returns Push
Properties
affinity
ZMQ_AFFINITY
I/O thread affinity, which determines which threads from the ØMQ I/O thread pool associated with the socket's context shall handle newly created connections.
Note: This value is a bit mask, but values higher than Number.MAX_SAFE_INTEGER may not be represented accurately! This currently means that configurations beyond 52 threads are unreliable.
backlog
ZMQ_BACKLOG
Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.
Readonlyclosed
Whether this socket was previously closed with close().
conflate
ZMQ_CONFLATE
If set to true, a socket shall keep only one message in its inbound/outbound queue: the last message to be received/sent. Ignores any high water mark options. Does not support multi-part messages - in particular, only one part of it is kept in the socket internal queue.
connectTimeout
ZMQ_CONNECT_TIMEOUT
Sets how long to wait before timing-out a connect() system call. The connect() system call normally takes a long time before it returns a time out error. Setting this option allows the library to time out the call at an earlier interval.
Readonlycontext
Context that this socket belongs to.
curvePublicKey
ZMQ_CURVE_PUBLICKEY
Sets the socket's long term public key. You must set this on CURVE client sockets. A server socket does not need to know its own public key. You can create a new keypair with curveKeyPair().
curveSecretKey
ZMQ_CURVE_SECRETKEY
Sets the socket's long term secret key. You must set this on both CURVE client and server sockets. You can create a new keypair with curveKeyPair().
curveServer
ZMQ_CURVE_SERVER
Defines whether the socket will act as server for CURVE security. A value of true means the socket will act as CURVE server. A value of false means the socket will not act as CURVE server, and its security role then depends on other option settings.
curveServerKey
ZMQ_CURVE_SERVERKEY
Sets the socket's long term server key. This is the public key of the CURVE server socket. You must set this on CURVE client sockets. This key must have been generated together with the server's secret key. You can create a new keypair with curveKeyPair().
Readonlyevents
Event Observer for this socket. This starts up a ØMQ monitoring socket internally that receives all socket events.
gssapiPlainText
gssapiPrincipal
gssapiPrincipalNameType
gssapiServer
gssapiServicePrincipal
gssapiServicePrincipalNameType
handshakeInterval
ZMQ_HANDSHAKE_IVL
Handshaking is the exchange of socket configuration information (socket type, identity, security) that occurs when a connection is first opened (only for connection-oriented transports). If handshaking does not complete within the configured time, the connection shall be closed. The value 0 means no handshake time limit.
heartbeatInterval
ZMQ_HEARTBEAT_IVL
Interval in milliseconds between sending ZMTP heartbeats for the specified socket. If this option is greater than 0, then a PING ZMTP command will be sent after every interval.
heartbeatTimeout
ZMQ_HEARTBEAT_TIMEOUT
How long (in milliseconds) to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic. This option is only valid if heartbeatInterval is greater than 0. The connection will time out if there is no traffic received after sending the PING command. The received traffic does not have to be a PONG command - any received traffic will cancel the timeout.
heartbeatTimeToLive
ZMQ_HEARTBEAT_TTL
The timeout in milliseconds on the remote peer for ZMTP heartbeats. If this option is greater than 0, the remote side shall time out the connection if it does not receive any more traffic within the TTL period. This option does not have any effect if heartbeatInterval is 0. Internally, this value is rounded down to the nearest decisecond, any value less than 100 will have no effect.
immediate
ZMQ_IMMEDIATE
By default queues will fill on outgoing connections even if the connection has not completed. This can lead to "lost" messages on sockets with round-robin routing (Request, Push, Dealer). If this option is set to true, messages shall be queued only to completed connections. This will cause the socket to block if there are no other connections, but will prevent queues from filling on pipes awaiting connection.
interface
ZMQ_BINDTODEVICE
Binds the socket to the given network interface (Linux only). Allows to use Linux VRF, see: https://www.kernel.org/doc/Documentation/networking/vrf.txt. Requires the program to be ran as root or with CAP_NET_RAW.
ipv6
ZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
ReadonlylastEndpoint
ZMQ_LAST_ENDPOINT
The last endpoint bound for TCP and IPC transports.
linger
ZMQ_LINGER
Determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with close().
loopbackFastPath
ZMQ_LOOPBACK_FASTPATH
Enable faster TCP connections on loopback devices. An application can enable this option to reduce the latency and improve the performance of loopback operations on a TCP socket on Windows.
maxMessageSize
ZMQ_MAXMSGSIZE
Limits the size of the inbound message. If a peer sends a message larger than the limit it is disconnected. Value of -1 means no limit.
multicastHops
ZMQ_MULTICAST_HOPS
Sets the time-to-live field in every multicast packet sent from this socket. The default is 1 which means that the multicast packets don't leave the local network.
multicastMaxTransportDataUnit
ZMQ_MULTICAST_MAXTPDU
Sets the maximum transport data unit size used for outbound multicast packets. This must be set at or below the minimum Maximum Transmission Unit (MTU) for all network paths over which multicast reception is required.
plainPassword
ZMQ_PLAIN_PASSWORD
Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
plainServer
ZMQ_PLAIN_SERVER
Defines whether the socket will act as server for PLAIN security. A value of true means the socket will act as PLAIN server. A value of false means the socket will not act as PLAIN server, and its security role then depends on other option settings.
plainUsername
ZMQ_PLAIN_USERNAME
Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
rate
ZMQ_RATE
Maximum send or receive data rate for multicast transports such as pgm.
Readonlyreadable
Whether any messages are currently available. If true, the next call to Readable.receive() will immediately read a message from the socket. For sockets that cannot receive messsages this is always false.
reconnectInterval
ZMQ_RECONNECT_IVL
Period ØMQ shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. The value -1 means no reconnection.
reconnectMaxInterval
ZMQ_RECONNECT_IVL_MAX
Maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled until reconnectMaxInterval is reached. This allows for exponential backoff strategy. Zero (the default) means no exponential backoff is performed and reconnect interval calculations are only based on reconnectInterval.
recoveryInterval
ZMQ_RECOVERY_IVL
Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
ReadonlysecurityMechanism
| null
| "plain"
| "curve"
| "gssapi"
ZMQ_MECHANISM
Returns the current security mechanism for the socket, if any. The security mechanism is set implictly by using any of the relevant security options. The returned value is one of:
null- No security mechanism is used."plain"- The PLAIN mechanism defines a simple username/password mechanism that lets a server authenticate a client. PLAIN makes no attempt at security or confidentiality."curve"- The CURVE mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server. CURVE is intended for use on public networks."gssapi"- The GSSAPI mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server using the Generic Security Service Application Program Interface (GSSAPI). The GSSAPI mechanism can be used on both public and private networks.
sendBufferSize
ZMQ_SNDBUF
Underlying kernel transmit buffer size in bytes. A value of -1 means leave the OS default unchanged.
sendHighWaterMark
ZMQ_SNDHWM
The high water mark is a hard limit on the maximum number of outgoing messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
sendTimeout
ZMQ_SNDTIMEO
Sets the timeout for sending messages on the socket. If the value is 0, send() will return a rejected promise immediately if the message cannot be sent. If the value is -1, it will wait asynchronously until the message is sent. For all other values, it will try to send the message for that amount of time before rejecting.
socksProxy
ZMQ_SOCKS_PROXY
The SOCKS5 proxy address that shall be used by the socket for the TCP connection(s). Does not support SOCKS5 authentication. If the endpoints are domain names instead of addresses they shall not be resolved and they shall be forwarded unchanged to the SOCKS proxy service in the client connection request message (address type 0x03 domain name).
tcpAcceptFilter
ZMQ_TCP_ACCEPT_FILTER
Assign a filter that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one filter is applied then new connection source IP should be matched. To clear all filters set to null. Filter is a string with IPv6 or IPv4 CIDR.
tcpKeepalive
ZMQ_TCP_KEEPALIVE
Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveCount
ZMQ_TCP_KEEPALIVE_CNT
Overrides TCP_KEEPCNT socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveIdle
ZMQ_TCP_KEEPALIVE_IDLE
Overrides TCP_KEEPIDLE / TCP_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveInterval
ZMQ_TCP_KEEPALIVE_INTVL
Overrides TCP_KEEPINTVL socket option (if supported by the OS). The default value of -1 leaves it to the OS default.
tcpMaxRetransmitTimeout
ZMQ_TCP_MAXRT
Sets how long before an unacknowledged TCP retransmit times out (if supported by the OS). The system normally attempts many TCP retransmits following an exponential backoff strategy. This means that after a network outage, it may take a long time before the session can be re-established. Setting this option allows the timeout to happen at a shorter interval.
ReadonlythreadSafe
ZMQ_THREAD_SAFE
Whether or not the socket is threadsafe. Currently only DRAFT sockets is thread-safe.
Readonlytype
ZMQ_TYPE
Retrieve the socket type. This is fairly useless because you can test the socket class with e.g. socket instanceof Dealer.
typeOfService
ZMQ_TOS
Sets the ToS fields (the Differentiated Services (DS) and Explicit Congestion Notification (ECN) field) of the IP header. The ToS field is typically used to specify a packet's priority. The availability of this option is dependent on intermediate network equipment that inspect the ToS field and provide a path for low-delay, high-throughput, highly-reliable service, etc.
vmciBufferMaxSize
ZMQ_VMCI_BUFFER_MAX_SIZE
Maximum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferMinSize
ZMQ_VMCI_BUFFER_MIN_SIZE
Minimum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferSize
ZMQ_VMCI_BUFFER_SIZE
The size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciConnectTimeout
ZMQ_VMCI_CONNECT_TIMEOUT
Connection timeout for the socket. For vmci:// transports only.
Readonlywritable
Whether any messages can be queued for sending. If true, the next call to Writable.send() will immediately queue a message on the socket. For sockets that cannot send messsages this is always false.
zapDomain
ZMQ_ZAP_DOMAIN
Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the default on all tcp:// connections), ZAP authentication only happens if you set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 for more details.
zapEnforceDomain
ZMQ_ZAP_ENFORCE_DOMAIN
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.
Methods
bind
- bind(address): Promise<void>
Binds the socket to the given address. During bind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.You can use
*in place of a hostname to bind on all interfaces/addresses, and you can use*in place of a port to bind to a random port (which can be retrieved with lastEndpoint later).await socket.bind("tcp://127.0.0.1:3456")
await socket.bind("tcp://*:3456") // binds on all interfaces
await socket.bind("tcp://127.0.0.1:*") // binds on random port -Parameters
- address: string
Address to bind this socket to.
Returns Promise<void>
Resolved when the socket was successfully bound.
- address: string
close
- close(): void
Closes the socket and disposes of all resources. Any messages that are queued may be discarded or sent in the background depending on the linger setting.
After this method is called, it is no longer possible to call any other methods on this socket.
Sockets that go out of scope and have no Readable.receive() or Writable.send() operations in progress will automatically be closed. Therefore it is not necessary in most applications to call close() manually.
Calling this method on a socket that is already closed is a no-op.
Returns void
connect
disconnect
- disconnect(address): void
Disconnects a previously connected socket from the given address and returns immediately. Disonnection will happen asynchronously in the background.
socket.disconnect("tcp://127.0.0.1:3456") -Parameters
- address: string
The previously connected address to disconnect from.
Returns void
- address: string
ProtectedgetBoolOption
ProtectedgetInt32Option
ProtectedgetInt64Option
ProtectedgetStringOption
ProtectedgetUint32Option
ProtectedgetUint64Option
send
- send(message, ...options): Promise<void>
Sends a single message or a multipart message on the socket. Queues the message immediately if possible, and returns a resolved promise. If the message cannot be queued because the high water mark has been reached, it will wait asynchronously. The promise will be resolved when the message was queued successfully.
await socket.send("hello world")
await socket.send(["hello", "world"]) -Queueing may fail eventually if the socket has been configured with a sendTimeout.
A call to send() is guaranteed to return with a resolved promise immediately if the message could be queued directly.
Only one asynchronously blocking call to send() may be executed simultaneously. If you call send() again on a socket that is in the mute state it will return a rejected promise with an
EBUSYerror.The reason for disallowing multiple send() calls simultaneously is that it could create an implicit queue of unsendable outgoing messages. This would circumvent the socket's sendHighWaterMark. Such an implementation could even exhaust all system memory and cause the Node.js process to abort.
For most application you should not notice this implementation detail. Only in rare occasions will a call to send() that does not resolve immediately be undesired. Here are some common scenarios:
If you wish to send a message, use
await send(...). ZeroMQ socket types have been carefully designed to give you the correct blocking behaviour on the chosen socket type in almost all cases:If sending is not possible, it is often better to wait than to continue as if nothing happened. For example, on a Request socket, you can only receive a reply once a message has been sent; so waiting until a message could be queued before continuing with the rest of the program (likely to read from the socket) is required.
Certain socket types (such as Router) will always allow queueing messages and
await send(...)won't delay any code that comes after. This makes sense for routers, since typically you don't want a single send operation to stop the handling of other incoming or outgoing messages.
If you wish to send on an occasionally blocking socket (for example on a Router with the Router.mandatory option set, or on a Dealer) and you're 100% certain that dropping a message is better than blocking, then you can set the sendTimeout option to
0to effectively force send() to always resolve immediately. Be prepared to catch exceptions if sending a message is not immediately possible.If you wish to send on a socket and messages should be queued before they are dropped, you should implement a simple queue in JavaScript. Such a queue is not provided by this library because most real world applications need to deal with undeliverable messages in more complex ways - for example, they might need to reply with a status message; or first retry delivery a certain number of times before giving up.
Parameters
- message: MessageLike | MessageLike[]
Single message or multipart message to queue for sending.
Rest...options: []Any options, if applicable to the socket type (DRAFT only).
Returns Promise<void>
Resolved when the message was successfully queued.
ProtectedsetBoolOption
ProtectedsetInt32Option
ProtectedsetInt64Option
ProtectedsetStringOption
ProtectedsetUint32Option
ProtectedsetUint64Option
unbind
- unbind(address): Promise<void>
Unbinds the socket to the given address. During unbind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.Parameters
- address: string
Address to unbind this socket from.
Returns Promise<void>
Resolved when the socket was successfully unbound.
- address: string
Class Push
A Push socket is used by a pipeline node to send messages to downstream pipeline nodes. Messages are round-robined to all connected downstream nodes. This socket cannot receive messages.
When a Push socket enters the mute state due to having reached the high water mark for all downstream nodes, or if there are no downstream nodes at all, then Writable.send() will block until the mute state ends or at least one downstream node becomes available for sending; messages are not discarded.
Hierarchy (View Summary)
Index
Constructors
Properties
Methods
Constructors
constructor
- new Push(
options?: {
affinity?: number;
backlog?: number;
conflate?: boolean;
connectTimeout?: number;
context?: Context;
curvePublicKey?: null | string;
curveSecretKey?: null | string;
curveServer?: boolean;
curveServerKey?: null | string;
gssapiPlainText?: boolean;
gssapiPrincipal?: null | string;
gssapiPrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
gssapiServer?: boolean;
gssapiServicePrincipal?: null | string;
gssapiServicePrincipalNameType?:
| "hostBased"
| "userName"
| "krb5Principal";
handshakeInterval?: number;
heartbeatInterval?: number;
heartbeatTimeout?: number;
heartbeatTimeToLive?: number;
immediate?: boolean;
interface?: null
| string;
ipv6?: boolean;
linger?: number;
loopbackFastPath?: boolean;
maxMessageSize?: number;
multicastHops?: number;
multicastMaxTransportDataUnit?: number;
plainPassword?: null | string;
plainServer?: boolean;
plainUsername?: null | string;
rate?: number;
reconnectInterval?: number;
reconnectMaxInterval?: number;
recoveryInterval?: number;
sendBufferSize?: number;
sendHighWaterMark?: number;
sendTimeout?: number;
socksProxy?: null | string;
tcpAcceptFilter?: null | string;
tcpKeepalive?: number;
tcpKeepaliveCount?: number;
tcpKeepaliveIdle?: number;
tcpKeepaliveInterval?: number;
tcpMaxRetransmitTimeout?: number;
typeOfService?: number;
vmciBufferMaxSize?: number;
vmciBufferMinSize?: number;
vmciBufferSize?: number;
vmciConnectTimeout?: number;
zapDomain?: null | string;
zapEnforceDomain?: boolean;
},
): Push Parameters
Optionaloptions: {
affinity?: number;
backlog?: number;
conflate?: boolean;
connectTimeout?: number;
context?: Context;
curvePublicKey?: null | string;
curveSecretKey?: null | string;
curveServer?: boolean;
curveServerKey?: null | string;
gssapiPlainText?: boolean;
gssapiPrincipal?: null | string;
gssapiPrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
gssapiServer?: boolean;
gssapiServicePrincipal?: null | string;
gssapiServicePrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
handshakeInterval?: number;
heartbeatInterval?: number;
heartbeatTimeout?: number;
heartbeatTimeToLive?: number;
immediate?: boolean;
interface?: null | string;
ipv6?: boolean;
linger?: number;
loopbackFastPath?: boolean;
maxMessageSize?: number;
multicastHops?: number;
multicastMaxTransportDataUnit?: number;
plainPassword?: null | string;
plainServer?: boolean;
plainUsername?: null | string;
rate?: number;
reconnectInterval?: number;
reconnectMaxInterval?: number;
recoveryInterval?: number;
sendBufferSize?: number;
sendHighWaterMark?: number;
sendTimeout?: number;
socksProxy?: null | string;
tcpAcceptFilter?: null | string;
tcpKeepalive?: number;
tcpKeepaliveCount?: number;
tcpKeepaliveIdle?: number;
tcpKeepaliveInterval?: number;
tcpMaxRetransmitTimeout?: number;
typeOfService?: number;
vmciBufferMaxSize?: number;
vmciBufferMinSize?: number;
vmciBufferSize?: number;
vmciConnectTimeout?: number;
zapDomain?: null | string;
zapEnforceDomain?: boolean;
}Optionalaffinity?: numberZMQ_AFFINITY
I/O thread affinity, which determines which threads from the ØMQ I/O thread pool associated with the socket's context shall handle newly created connections.
Note: This value is a bit mask, but values higher than
Number.MAX_SAFE_INTEGERmay not be represented accurately! This currently means that configurations beyond 52 threads are unreliable.Optionalbacklog?: numberZMQ_BACKLOG
Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.
Optionalconflate?: booleanZMQ_CONFLATE
If set to
true, a socket shall keep only one message in its inbound/outbound queue: the last message to be received/sent. Ignores any high water mark options. Does not support multi-part messages - in particular, only one part of it is kept in the socket internal queue.OptionalconnectTimeout?: numberZMQ_CONNECT_TIMEOUT
Sets how long to wait before timing-out a connect() system call. The connect() system call normally takes a long time before it returns a time out error. Setting this option allows the library to time out the call at an earlier interval.
Optionalcontext?: ContextOptionalcurvePublicKey?: null | stringZMQ_CURVE_PUBLICKEY
Sets the socket's long term public key. You must set this on CURVE client sockets. A server socket does not need to know its own public key. You can create a new keypair with curveKeyPair().
OptionalcurveSecretKey?: null | stringZMQ_CURVE_SECRETKEY
Sets the socket's long term secret key. You must set this on both CURVE client and server sockets. You can create a new keypair with curveKeyPair().
OptionalcurveServer?: booleanZMQ_CURVE_SERVER
Defines whether the socket will act as server for CURVE security. A value of
truemeans the socket will act as CURVE server. A value offalsemeans the socket will not act as CURVE server, and its security role then depends on other option settings.OptionalcurveServerKey?: null | stringZMQ_CURVE_SERVERKEY
Sets the socket's long term server key. This is the public key of the CURVE server socket. You must set this on CURVE client sockets. This key must have been generated together with the server's secret key. You can create a new keypair with curveKeyPair().
OptionalgssapiPlainText?: booleanOptionalgssapiPrincipal?: null | stringOptionalgssapiPrincipalNameType?: "hostBased" | "userName" | "krb5Principal"OptionalgssapiServer?: booleanOptionalgssapiServicePrincipal?: null | stringOptionalgssapiServicePrincipalNameType?: "hostBased" | "userName" | "krb5Principal"OptionalhandshakeInterval?: numberZMQ_HANDSHAKE_IVL
Handshaking is the exchange of socket configuration information (socket type, identity, security) that occurs when a connection is first opened (only for connection-oriented transports). If handshaking does not complete within the configured time, the connection shall be closed. The value 0 means no handshake time limit.
OptionalheartbeatInterval?: numberZMQ_HEARTBEAT_IVL
Interval in milliseconds between sending ZMTP heartbeats for the specified socket. If this option is greater than 0, then a PING ZMTP command will be sent after every interval.
OptionalheartbeatTimeout?: numberZMQ_HEARTBEAT_TIMEOUT
How long (in milliseconds) to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic. This option is only valid if heartbeatInterval is greater than 0. The connection will time out if there is no traffic received after sending the PING command. The received traffic does not have to be a PONG command - any received traffic will cancel the timeout.
OptionalheartbeatTimeToLive?: numberZMQ_HEARTBEAT_TTL
The timeout in milliseconds on the remote peer for ZMTP heartbeats. If this option is greater than 0, the remote side shall time out the connection if it does not receive any more traffic within the TTL period. This option does not have any effect if heartbeatInterval is 0. Internally, this value is rounded down to the nearest decisecond, any value less than 100 will have no effect.
Optionalimmediate?: booleanZMQ_IMMEDIATE
By default queues will fill on outgoing connections even if the connection has not completed. This can lead to "lost" messages on sockets with round-robin routing (Request, Push, Dealer). If this option is set to
true, messages shall be queued only to completed connections. This will cause the socket to block if there are no other connections, but will prevent queues from filling on pipes awaiting connection.Optionalinterface?: null | stringZMQ_BINDTODEVICE
Binds the socket to the given network interface (Linux only). Allows to use Linux VRF, see: https://www.kernel.org/doc/Documentation/networking/vrf.txt. Requires the program to be ran as root or with
CAP_NET_RAW.Optionalipv6?: booleanZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
Optionallinger?: numberZMQ_LINGER
Determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with close().
OptionalloopbackFastPath?: booleanZMQ_LOOPBACK_FASTPATH
Enable faster TCP connections on loopback devices. An application can enable this option to reduce the latency and improve the performance of loopback operations on a TCP socket on Windows.
OptionalmaxMessageSize?: numberZMQ_MAXMSGSIZE
Limits the size of the inbound message. If a peer sends a message larger than the limit it is disconnected. Value of -1 means no limit.
OptionalmulticastHops?: numberZMQ_MULTICAST_HOPS
Sets the time-to-live field in every multicast packet sent from this socket. The default is 1 which means that the multicast packets don't leave the local network.
OptionalmulticastMaxTransportDataUnit?: numberZMQ_MULTICAST_MAXTPDU
Sets the maximum transport data unit size used for outbound multicast packets. This must be set at or below the minimum Maximum Transmission Unit (MTU) for all network paths over which multicast reception is required.
OptionalplainPassword?: null | stringZMQ_PLAIN_PASSWORD
Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
OptionalplainServer?: booleanZMQ_PLAIN_SERVER
Defines whether the socket will act as server for PLAIN security. A value of
truemeans the socket will act as PLAIN server. A value offalsemeans the socket will not act as PLAIN server, and its security role then depends on other option settings.OptionalplainUsername?: null | stringZMQ_PLAIN_USERNAME
Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
Optionalrate?: numberZMQ_RATE
Maximum send or receive data rate for multicast transports such as
pgm.OptionalreconnectInterval?: numberZMQ_RECONNECT_IVL
Period ØMQ shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. The value -1 means no reconnection.
OptionalreconnectMaxInterval?: numberZMQ_RECONNECT_IVL_MAX
Maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled until reconnectMaxInterval is reached. This allows for exponential backoff strategy. Zero (the default) means no exponential backoff is performed and reconnect interval calculations are only based on reconnectInterval.
OptionalrecoveryInterval?: numberZMQ_RECOVERY_IVL
Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
OptionalsendBufferSize?: numberZMQ_SNDBUF
Underlying kernel transmit buffer size in bytes. A value of -1 means leave the OS default unchanged.
OptionalsendHighWaterMark?: numberZMQ_SNDHWM
The high water mark is a hard limit on the maximum number of outgoing messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
OptionalsendTimeout?: numberZMQ_SNDTIMEO
Sets the timeout for sending messages on the socket. If the value is 0, send() will return a rejected promise immediately if the message cannot be sent. If the value is -1, it will wait asynchronously until the message is sent. For all other values, it will try to send the message for that amount of time before rejecting.
OptionalsocksProxy?: null | stringZMQ_SOCKS_PROXY
The SOCKS5 proxy address that shall be used by the socket for the TCP connection(s). Does not support SOCKS5 authentication. If the endpoints are domain names instead of addresses they shall not be resolved and they shall be forwarded unchanged to the SOCKS proxy service in the client connection request message (address type 0x03 domain name).
OptionaltcpAcceptFilter?: null | stringZMQ_TCP_ACCEPT_FILTER
Assign a filter that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one filter is applied then new connection source IP should be matched. To clear all filters set to
null. Filter is a string with IPv6 or IPv4 CIDR.OptionaltcpKeepalive?: numberZMQ_TCP_KEEPALIVE
Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepaliveCount?: numberZMQ_TCP_KEEPALIVE_CNT
Overrides TCP_KEEPCNT socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepaliveIdle?: numberZMQ_TCP_KEEPALIVE_IDLE
Overrides TCP_KEEPIDLE / TCP_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepaliveInterval?: numberZMQ_TCP_KEEPALIVE_INTVL
Overrides TCP_KEEPINTVL socket option (if supported by the OS). The default value of -1 leaves it to the OS default.
OptionaltcpMaxRetransmitTimeout?: numberZMQ_TCP_MAXRT
Sets how long before an unacknowledged TCP retransmit times out (if supported by the OS). The system normally attempts many TCP retransmits following an exponential backoff strategy. This means that after a network outage, it may take a long time before the session can be re-established. Setting this option allows the timeout to happen at a shorter interval.
OptionaltypeOfService?: numberZMQ_TOS
Sets the ToS fields (the Differentiated Services (DS) and Explicit Congestion Notification (ECN) field) of the IP header. The ToS field is typically used to specify a packet's priority. The availability of this option is dependent on intermediate network equipment that inspect the ToS field and provide a path for low-delay, high-throughput, highly-reliable service, etc.
OptionalvmciBufferMaxSize?: numberZMQ_VMCI_BUFFER_MAX_SIZE
Maximum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciBufferMinSize?: numberZMQ_VMCI_BUFFER_MIN_SIZE
Minimum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciBufferSize?: numberZMQ_VMCI_BUFFER_SIZE
The size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciConnectTimeout?: numberZMQ_VMCI_CONNECT_TIMEOUT
Connection timeout for the socket. For
vmci://transports only.OptionalzapDomain?: null | stringZMQ_ZAP_DOMAIN
Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the default on all
tcp://connections), ZAP authentication only happens if you set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 for more details.OptionalzapEnforceDomain?: booleanZMQ_ZAP_ENFORCE_DOMAIN
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.
Returns Push
Properties
affinity
ZMQ_AFFINITY
I/O thread affinity, which determines which threads from the ØMQ I/O thread pool associated with the socket's context shall handle newly created connections.
Note: This value is a bit mask, but values higher than Number.MAX_SAFE_INTEGER may not be represented accurately! This currently means that configurations beyond 52 threads are unreliable.
backlog
ZMQ_BACKLOG
Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.
Readonlyclosed
Whether this socket was previously closed with close().
conflate
ZMQ_CONFLATE
If set to true, a socket shall keep only one message in its inbound/outbound queue: the last message to be received/sent. Ignores any high water mark options. Does not support multi-part messages - in particular, only one part of it is kept in the socket internal queue.
connectTimeout
ZMQ_CONNECT_TIMEOUT
Sets how long to wait before timing-out a connect() system call. The connect() system call normally takes a long time before it returns a time out error. Setting this option allows the library to time out the call at an earlier interval.
Readonlycontext
Context that this socket belongs to.
curvePublicKey
ZMQ_CURVE_PUBLICKEY
Sets the socket's long term public key. You must set this on CURVE client sockets. A server socket does not need to know its own public key. You can create a new keypair with curveKeyPair().
curveSecretKey
ZMQ_CURVE_SECRETKEY
Sets the socket's long term secret key. You must set this on both CURVE client and server sockets. You can create a new keypair with curveKeyPair().
curveServer
ZMQ_CURVE_SERVER
Defines whether the socket will act as server for CURVE security. A value of true means the socket will act as CURVE server. A value of false means the socket will not act as CURVE server, and its security role then depends on other option settings.
curveServerKey
ZMQ_CURVE_SERVERKEY
Sets the socket's long term server key. This is the public key of the CURVE server socket. You must set this on CURVE client sockets. This key must have been generated together with the server's secret key. You can create a new keypair with curveKeyPair().
Readonlyevents
Event Observer for this socket. This starts up a ØMQ monitoring socket internally that receives all socket events.
gssapiPlainText
gssapiPrincipal
gssapiPrincipalNameType
gssapiServer
gssapiServicePrincipal
gssapiServicePrincipalNameType
handshakeInterval
ZMQ_HANDSHAKE_IVL
Handshaking is the exchange of socket configuration information (socket type, identity, security) that occurs when a connection is first opened (only for connection-oriented transports). If handshaking does not complete within the configured time, the connection shall be closed. The value 0 means no handshake time limit.
heartbeatInterval
ZMQ_HEARTBEAT_IVL
Interval in milliseconds between sending ZMTP heartbeats for the specified socket. If this option is greater than 0, then a PING ZMTP command will be sent after every interval.
heartbeatTimeout
ZMQ_HEARTBEAT_TIMEOUT
How long (in milliseconds) to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic. This option is only valid if heartbeatInterval is greater than 0. The connection will time out if there is no traffic received after sending the PING command. The received traffic does not have to be a PONG command - any received traffic will cancel the timeout.
heartbeatTimeToLive
ZMQ_HEARTBEAT_TTL
The timeout in milliseconds on the remote peer for ZMTP heartbeats. If this option is greater than 0, the remote side shall time out the connection if it does not receive any more traffic within the TTL period. This option does not have any effect if heartbeatInterval is 0. Internally, this value is rounded down to the nearest decisecond, any value less than 100 will have no effect.
immediate
ZMQ_IMMEDIATE
By default queues will fill on outgoing connections even if the connection has not completed. This can lead to "lost" messages on sockets with round-robin routing (Request, Push, Dealer). If this option is set to true, messages shall be queued only to completed connections. This will cause the socket to block if there are no other connections, but will prevent queues from filling on pipes awaiting connection.
interface
ZMQ_BINDTODEVICE
Binds the socket to the given network interface (Linux only). Allows to use Linux VRF, see: https://www.kernel.org/doc/Documentation/networking/vrf.txt. Requires the program to be ran as root or with CAP_NET_RAW.
ipv6
ZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
ReadonlylastEndpoint
ZMQ_LAST_ENDPOINT
The last endpoint bound for TCP and IPC transports.
linger
ZMQ_LINGER
Determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with close().
loopbackFastPath
ZMQ_LOOPBACK_FASTPATH
Enable faster TCP connections on loopback devices. An application can enable this option to reduce the latency and improve the performance of loopback operations on a TCP socket on Windows.
maxMessageSize
ZMQ_MAXMSGSIZE
Limits the size of the inbound message. If a peer sends a message larger than the limit it is disconnected. Value of -1 means no limit.
multicastHops
ZMQ_MULTICAST_HOPS
Sets the time-to-live field in every multicast packet sent from this socket. The default is 1 which means that the multicast packets don't leave the local network.
multicastMaxTransportDataUnit
ZMQ_MULTICAST_MAXTPDU
Sets the maximum transport data unit size used for outbound multicast packets. This must be set at or below the minimum Maximum Transmission Unit (MTU) for all network paths over which multicast reception is required.
plainPassword
ZMQ_PLAIN_PASSWORD
Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
plainServer
ZMQ_PLAIN_SERVER
Defines whether the socket will act as server for PLAIN security. A value of true means the socket will act as PLAIN server. A value of false means the socket will not act as PLAIN server, and its security role then depends on other option settings.
plainUsername
ZMQ_PLAIN_USERNAME
Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
rate
ZMQ_RATE
Maximum send or receive data rate for multicast transports such as pgm.
Readonlyreadable
Whether any messages are currently available. If true, the next call to Readable.receive() will immediately read a message from the socket. For sockets that cannot receive messsages this is always false.
reconnectInterval
ZMQ_RECONNECT_IVL
Period ØMQ shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. The value -1 means no reconnection.
reconnectMaxInterval
ZMQ_RECONNECT_IVL_MAX
Maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled until reconnectMaxInterval is reached. This allows for exponential backoff strategy. Zero (the default) means no exponential backoff is performed and reconnect interval calculations are only based on reconnectInterval.
recoveryInterval
ZMQ_RECOVERY_IVL
Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
ReadonlysecurityMechanism
ZMQ_MECHANISM
Returns the current security mechanism for the socket, if any. The security mechanism is set implictly by using any of the relevant security options. The returned value is one of:
null- No security mechanism is used."plain"- The PLAIN mechanism defines a simple username/password mechanism that lets a server authenticate a client. PLAIN makes no attempt at security or confidentiality."curve"- The CURVE mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server. CURVE is intended for use on public networks."gssapi"- The GSSAPI mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server using the Generic Security Service Application Program Interface (GSSAPI). The GSSAPI mechanism can be used on both public and private networks.
sendBufferSize
ZMQ_SNDBUF
Underlying kernel transmit buffer size in bytes. A value of -1 means leave the OS default unchanged.
sendHighWaterMark
ZMQ_SNDHWM
The high water mark is a hard limit on the maximum number of outgoing messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
sendTimeout
ZMQ_SNDTIMEO
Sets the timeout for sending messages on the socket. If the value is 0, send() will return a rejected promise immediately if the message cannot be sent. If the value is -1, it will wait asynchronously until the message is sent. For all other values, it will try to send the message for that amount of time before rejecting.
socksProxy
ZMQ_SOCKS_PROXY
The SOCKS5 proxy address that shall be used by the socket for the TCP connection(s). Does not support SOCKS5 authentication. If the endpoints are domain names instead of addresses they shall not be resolved and they shall be forwarded unchanged to the SOCKS proxy service in the client connection request message (address type 0x03 domain name).
tcpAcceptFilter
ZMQ_TCP_ACCEPT_FILTER
Assign a filter that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one filter is applied then new connection source IP should be matched. To clear all filters set to null. Filter is a string with IPv6 or IPv4 CIDR.
tcpKeepalive
ZMQ_TCP_KEEPALIVE
Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveCount
ZMQ_TCP_KEEPALIVE_CNT
Overrides TCP_KEEPCNT socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveIdle
ZMQ_TCP_KEEPALIVE_IDLE
Overrides TCP_KEEPIDLE / TCP_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveInterval
ZMQ_TCP_KEEPALIVE_INTVL
Overrides TCP_KEEPINTVL socket option (if supported by the OS). The default value of -1 leaves it to the OS default.
tcpMaxRetransmitTimeout
ZMQ_TCP_MAXRT
Sets how long before an unacknowledged TCP retransmit times out (if supported by the OS). The system normally attempts many TCP retransmits following an exponential backoff strategy. This means that after a network outage, it may take a long time before the session can be re-established. Setting this option allows the timeout to happen at a shorter interval.
ReadonlythreadSafe
ZMQ_THREAD_SAFE
Whether or not the socket is threadsafe. Currently only DRAFT sockets is thread-safe.
Readonlytype
ZMQ_TYPE
Retrieve the socket type. This is fairly useless because you can test the socket class with e.g. socket instanceof Dealer.
typeOfService
ZMQ_TOS
Sets the ToS fields (the Differentiated Services (DS) and Explicit Congestion Notification (ECN) field) of the IP header. The ToS field is typically used to specify a packet's priority. The availability of this option is dependent on intermediate network equipment that inspect the ToS field and provide a path for low-delay, high-throughput, highly-reliable service, etc.
vmciBufferMaxSize
ZMQ_VMCI_BUFFER_MAX_SIZE
Maximum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferMinSize
ZMQ_VMCI_BUFFER_MIN_SIZE
Minimum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferSize
ZMQ_VMCI_BUFFER_SIZE
The size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciConnectTimeout
ZMQ_VMCI_CONNECT_TIMEOUT
Connection timeout for the socket. For vmci:// transports only.
Readonlywritable
Whether any messages can be queued for sending. If true, the next call to Writable.send() will immediately queue a message on the socket. For sockets that cannot send messsages this is always false.
zapDomain
ZMQ_ZAP_DOMAIN
Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the default on all tcp:// connections), ZAP authentication only happens if you set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 for more details.
zapEnforceDomain
ZMQ_ZAP_ENFORCE_DOMAIN
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.
Methods
bind
- bind(address: string): Promise<void>
Binds the socket to the given address. During bind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.You can use
*in place of a hostname to bind on all interfaces/addresses, and you can use*in place of a port to bind to a random port (which can be retrieved with lastEndpoint later).await socket.bind("tcp://127.0.0.1:3456")
await socket.bind("tcp://*:3456") // binds on all interfaces
await socket.bind("tcp://127.0.0.1:*") // binds on random port +Parameters
- address: string
Address to bind this socket to.
Returns Promise<void>
Resolved when the socket was successfully bound.
- address: string
bindSync
- bindSync(address: string): void
Binds the socket to the given address. During bind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.You can use
*in place of a hostname to bind on all interfaces/addresses, and you can use*in place of a port to bind to a random port (which can be retrieved with lastEndpoint later).socket.bindSync("tcp://127.0.0.1:3456")
socket.bindSync("tcp://*:3456") // binds on all interfaces
socket.bindSync("tcp://127.0.0.1:*") // binds on random port +Parameters
- address: string
Address to bind this socket to.
Returns void
Resolved when the socket was successfully bound.
- address: string
close
- close(): void
Closes the socket and disposes of all resources. Any messages that are queued may be discarded or sent in the background depending on the linger setting.
After this method is called, it is no longer possible to call any other methods on this socket.
Sockets that go out of scope and have no Readable.receive() or Writable.send() operations in progress will automatically be closed. Therefore it is not necessary in most applications to call close() manually.
Calling this method on a socket that is already closed is a no-op.
Returns void
connect
disconnect
- disconnect(address: string): void
Disconnects a previously connected socket from the given address and returns immediately. Disonnection will happen asynchronously in the background.
socket.disconnect("tcp://127.0.0.1:3456") +Parameters
- address: string
The previously connected address to disconnect from.
Returns void
- address: string
ProtectedgetBoolOption
ProtectedgetInt32Option
ProtectedgetInt64Option
ProtectedgetStringOption
ProtectedgetUint32Option
ProtectedgetUint64Option
send
- send(message: MessageLike | MessageLike[], ...options: []): Promise<void>
Sends a single message or a multipart message on the socket. Queues the message immediately if possible, and returns a resolved promise. If the message cannot be queued because the high water mark has been reached, it will wait asynchronously. The promise will be resolved when the message was queued successfully.
await socket.send("hello world")
await socket.send(["hello", "world"]) +Queueing may fail eventually if the socket has been configured with a sendTimeout.
A call to send() is guaranteed to return with a resolved promise immediately if the message could be queued directly.
Only one asynchronously blocking call to send() may be executed simultaneously. If you call send() again on a socket that is in the mute state it will return a rejected promise with an
EBUSYerror.The reason for disallowing multiple send() calls simultaneously is that it could create an implicit queue of unsendable outgoing messages. This would circumvent the socket's sendHighWaterMark. Such an implementation could even exhaust all system memory and cause the Node.js process to abort.
For most application you should not notice this implementation detail. Only in rare occasions will a call to send() that does not resolve immediately be undesired. Here are some common scenarios:
If you wish to send a message, use
await send(...). ZeroMQ socket types have been carefully designed to give you the correct blocking behaviour on the chosen socket type in almost all cases:If sending is not possible, it is often better to wait than to continue as if nothing happened. For example, on a Request socket, you can only receive a reply once a message has been sent; so waiting until a message could be queued before continuing with the rest of the program (likely to read from the socket) is required.
Certain socket types (such as Router) will always allow queueing messages and
await send(...)won't delay any code that comes after. This makes sense for routers, since typically you don't want a single send operation to stop the handling of other incoming or outgoing messages.
If you wish to send on an occasionally blocking socket (for example on a Router with the Router.mandatory option set, or on a Dealer) and you're 100% certain that dropping a message is better than blocking, then you can set the sendTimeout option to
0to effectively force send() to always resolve immediately. Be prepared to catch exceptions if sending a message is not immediately possible.If you wish to send on a socket and messages should be queued before they are dropped, you should implement a simple queue in JavaScript. Such a queue is not provided by this library because most real world applications need to deal with undeliverable messages in more complex ways - for example, they might need to reply with a status message; or first retry delivery a certain number of times before giving up.
Parameters
- message: MessageLike | MessageLike[]
Single message or multipart message to queue for sending.
- ...options: []
Any options, if applicable to the socket type (DRAFT only).
Returns Promise<void>
Resolved when the message was successfully queued.
ProtectedsetBoolOption
ProtectedsetInt32Option
ProtectedsetInt64Option
ProtectedsetStringOption
ProtectedsetUint32Option
ProtectedsetUint64Option
unbind
- unbind(address: string): Promise<void>
Unbinds the socket to the given address. During unbind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.Parameters
- address: string
Address to unbind this socket from.
Returns Promise<void>
Resolved when the socket was successfully unbound.
- address: string
unbindSync
- unbindSync(address: string): void
Unbinds the socket to the given address. During unbind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.Parameters
- address: string
Address to unbind this socket from.
Returns void
Resolved when the socket was successfully unbound.
- address: string
Class Reply
A Reply socket can act as a server which receives requests from and sends replies to a Request socket. This socket type allows only an alternating sequence of Readable.receive() and subsequent Writable.send() calls. Each request received is fair-queued from among all clients, and each reply sent is routed to the client that issued the last request. If the original requester does not exist any more the reply is silently discarded.
Hierarchy (view full)
Index
Constructors
Properties
Methods
Constructors
constructor
- new
Reply (options?): Reply Parameters
Optionaloptions: {
affinity?: number;
backlog?: number;
connectTimeout?: number;
context?: Context;
curvePublicKey?: null | string;
curveSecretKey?: null | string;
curveServer?: boolean;
curveServerKey?: null | string;
gssapiPlainText?: boolean;
gssapiPrincipal?: null | string;
gssapiPrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
gssapiServer?: boolean;
gssapiServicePrincipal?: null | string;
gssapiServicePrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
handshakeInterval?: number;
heartbeatInterval?: number;
heartbeatTimeout?: number;
heartbeatTimeToLive?: number;
immediate?: boolean;
interface?: null | string;
ipv6?: boolean;
linger?: number;
loopbackFastPath?: boolean;
maxMessageSize?: number;
multicastHops?: number;
multicastMaxTransportDataUnit?: number;
plainPassword?: null | string;
plainServer?: boolean;
plainUsername?: null | string;
rate?: number;
receiveBufferSize?: number;
receiveHighWaterMark?: number;
receiveTimeout?: number;
reconnectInterval?: number;
reconnectMaxInterval?: number;
recoveryInterval?: number;
routingId?: null | string;
sendBufferSize?: number;
sendHighWaterMark?: number;
sendTimeout?: number;
socksProxy?: null | string;
tcpAcceptFilter?: null | string;
tcpKeepalive?: number;
tcpKeepaliveCount?: number;
tcpKeepaliveIdle?: number;
tcpKeepaliveInterval?: number;
tcpMaxRetransmitTimeout?: number;
typeOfService?: number;
vmciBufferMaxSize?: number;
vmciBufferMinSize?: number;
vmciBufferSize?: number;
vmciConnectTimeout?: number;
zapDomain?: null | string;
zapEnforceDomain?: boolean;
}Optionalaffinity?: numberZMQ_AFFINITY
I/O thread affinity, which determines which threads from the ØMQ I/O thread pool associated with the socket's context shall handle newly created connections.
Note: This value is a bit mask, but values higher than
Number.MAX_SAFE_INTEGERmay not be represented accurately! This currently means that configurations beyond 52 threads are unreliable.Optionalbacklog?: numberZMQ_BACKLOG
Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.
OptionalconnectTimeout ?: numberZMQ_CONNECT_TIMEOUT
Sets how long to wait before timing-out a connect() system call. The connect() system call normally takes a long time before it returns a time out error. Setting this option allows the library to time out the call at an earlier interval.
Optionalcontext?: ContextOptionalcurvePublic ?: null | stringKey ZMQ_CURVE_PUBLICKEY
Sets the socket's long term public key. You must set this on CURVE client sockets. A server socket does not need to know its own public key. You can create a new keypair with curveKeyPair().
OptionalcurveSecret ?: null | stringKey ZMQ_CURVE_SECRETKEY
Sets the socket's long term secret key. You must set this on both CURVE client and server sockets. You can create a new keypair with curveKeyPair().
OptionalcurveServer ?: booleanZMQ_CURVE_SERVER
Defines whether the socket will act as server for CURVE security. A value of
truemeans the socket will act as CURVE server. A value offalsemeans the socket will not act as CURVE server, and its security role then depends on other option settings.OptionalcurveServer ?: null | stringKey ZMQ_CURVE_SERVERKEY
Sets the socket's long term server key. This is the public key of the CURVE server socket. You must set this on CURVE client sockets. This key must have been generated together with the server's secret key. You can create a new keypair with curveKeyPair().
OptionalgssapiPlain ?: booleanText OptionalgssapiPrincipal ?: null | stringOptionalgssapiPrincipal ?: "hostBased" | "userName" | "krb5Principal"Name Type OptionalgssapiServer ?: booleanOptionalgssapiService ?: null | stringPrincipal OptionalgssapiService ?: "hostBased" | "userName" | "krb5Principal"Principal Name Type OptionalhandshakeInterval ?: numberZMQ_HANDSHAKE_IVL
Handshaking is the exchange of socket configuration information (socket type, identity, security) that occurs when a connection is first opened (only for connection-oriented transports). If handshaking does not complete within the configured time, the connection shall be closed. The value 0 means no handshake time limit.
OptionalheartbeatInterval ?: numberZMQ_HEARTBEAT_IVL
Interval in milliseconds between sending ZMTP heartbeats for the specified socket. If this option is greater than 0, then a PING ZMTP command will be sent after every interval.
OptionalheartbeatTimeout ?: numberZMQ_HEARTBEAT_TIMEOUT
How long (in milliseconds) to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic. This option is only valid if heartbeatInterval is greater than 0. The connection will time out if there is no traffic received after sending the PING command. The received traffic does not have to be a PONG command - any received traffic will cancel the timeout.
OptionalheartbeatTime ?: numberTo Live ZMQ_HEARTBEAT_TTL
The timeout in milliseconds on the remote peer for ZMTP heartbeats. If this option is greater than 0, the remote side shall time out the connection if it does not receive any more traffic within the TTL period. This option does not have any effect if heartbeatInterval is 0. Internally, this value is rounded down to the nearest decisecond, any value less than 100 will have no effect.
Optionalimmediate?: booleanZMQ_IMMEDIATE
By default queues will fill on outgoing connections even if the connection has not completed. This can lead to "lost" messages on sockets with round-robin routing (Request, Push, Dealer). If this option is set to
true, messages shall be queued only to completed connections. This will cause the socket to block if there are no other connections, but will prevent queues from filling on pipes awaiting connection.Optionalinterface?: null | stringZMQ_BINDTODEVICE
Binds the socket to the given network interface (Linux only). Allows to use Linux VRF, see: https://www.kernel.org/doc/Documentation/networking/vrf.txt. Requires the program to be ran as root or with
CAP_NET_RAW.Optionalipv6?: booleanZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
Optionallinger?: numberZMQ_LINGER
Determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with close().
OptionalloopbackFast ?: booleanPath ZMQ_LOOPBACK_FASTPATH
Enable faster TCP connections on loopback devices. An application can enable this option to reduce the latency and improve the performance of loopback operations on a TCP socket on Windows.
OptionalmaxMessage ?: numberSize ZMQ_MAXMSGSIZE
Limits the size of the inbound message. If a peer sends a message larger than the limit it is disconnected. Value of -1 means no limit.
OptionalmulticastHops ?: numberZMQ_MULTICAST_HOPS
Sets the time-to-live field in every multicast packet sent from this socket. The default is 1 which means that the multicast packets don't leave the local network.
OptionalmulticastMax ?: numberTransport Data Unit ZMQ_MULTICAST_MAXTPDU
Sets the maximum transport data unit size used for outbound multicast packets. This must be set at or below the minimum Maximum Transmission Unit (MTU) for all network paths over which multicast reception is required.
OptionalplainPassword ?: null | stringZMQ_PLAIN_PASSWORD
Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
OptionalplainServer ?: booleanZMQ_PLAIN_SERVER
Defines whether the socket will act as server for PLAIN security. A value of
truemeans the socket will act as PLAIN server. A value offalsemeans the socket will not act as PLAIN server, and its security role then depends on other option settings.OptionalplainUsername ?: null | stringZMQ_PLAIN_USERNAME
Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
Optionalrate?: numberZMQ_RATE
Maximum send or receive data rate for multicast transports such as
pgm.OptionalreceiveBuffer ?: numberSize ZMQ_RCVBUF
Underlying kernel receive buffer size in bytes. A value of -1 means leave the OS default unchanged.
OptionalreceiveHigh ?: numberWater Mark ZMQ_RCVHWM
The high water mark is a hard limit on the maximum number of incoming messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
OptionalreceiveTimeout ?: numberZMQ_RCVTIMEO
Sets the timeout receiving messages on the socket. If the value is 0, receive() will return a rejected promise immediately if there is no message to receive. If the value is -1, it will wait asynchronously until a message is available. For all other values, it will wait for a message for that amount of time before rejecting.
OptionalreconnectInterval ?: numberZMQ_RECONNECT_IVL
Period ØMQ shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. The value -1 means no reconnection.
OptionalreconnectMax ?: numberInterval ZMQ_RECONNECT_IVL_MAX
Maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled until reconnectMaxInterval is reached. This allows for exponential backoff strategy. Zero (the default) means no exponential backoff is performed and reconnect interval calculations are only based on reconnectInterval.
OptionalrecoveryInterval ?: numberZMQ_RECOVERY_IVL
Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
OptionalroutingId ?: null | stringZMQ_ROUTING_ID
The identity of the specified socket when connecting to a
Routersocket.OptionalsendBuffer ?: numberSize ZMQ_SNDBUF
Underlying kernel transmit buffer size in bytes. A value of -1 means leave the OS default unchanged.
OptionalsendHigh ?: numberWater Mark ZMQ_SNDHWM
The high water mark is a hard limit on the maximum number of outgoing messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
OptionalsendTimeout ?: numberZMQ_SNDTIMEO
Sets the timeout for sending messages on the socket. If the value is 0, send() will return a rejected promise immediately if the message cannot be sent. If the value is -1, it will wait asynchronously until the message is sent. For all other values, it will try to send the message for that amount of time before rejecting.
OptionalsocksProxy ?: null | stringZMQ_SOCKS_PROXY
The SOCKS5 proxy address that shall be used by the socket for the TCP connection(s). Does not support SOCKS5 authentication. If the endpoints are domain names instead of addresses they shall not be resolved and they shall be forwarded unchanged to the SOCKS proxy service in the client connection request message (address type 0x03 domain name).
OptionaltcpAccept ?: null | stringFilter ZMQ_TCP_ACCEPT_FILTER
Assign a filter that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one filter is applied then new connection source IP should be matched. To clear all filters set to
null. Filter is a string with IPv6 or IPv4 CIDR.OptionaltcpKeepalive ?: numberZMQ_TCP_KEEPALIVE
Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepalive ?: numberCount ZMQ_TCP_KEEPALIVE_CNT
Overrides TCP_KEEPCNT socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepalive ?: numberIdle ZMQ_TCP_KEEPALIVE_IDLE
Overrides TCP_KEEPIDLE / TCP_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepalive ?: numberInterval ZMQ_TCP_KEEPALIVE_INTVL
Overrides TCP_KEEPINTVL socket option (if supported by the OS). The default value of -1 leaves it to the OS default.
OptionaltcpMax ?: numberRetransmit Timeout ZMQ_TCP_MAXRT
Sets how long before an unacknowledged TCP retransmit times out (if supported by the OS). The system normally attempts many TCP retransmits following an exponential backoff strategy. This means that after a network outage, it may take a long time before the session can be re-established. Setting this option allows the timeout to happen at a shorter interval.
OptionaltypeOf ?: numberService ZMQ_TOS
Sets the ToS fields (the Differentiated Services (DS) and Explicit Congestion Notification (ECN) field) of the IP header. The ToS field is typically used to specify a packet's priority. The availability of this option is dependent on intermediate network equipment that inspect the ToS field and provide a path for low-delay, high-throughput, highly-reliable service, etc.
OptionalvmciBuffer ?: numberMax Size ZMQ_VMCI_BUFFER_MAX_SIZE
Maximum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciBuffer ?: numberMin Size ZMQ_VMCI_BUFFER_MIN_SIZE
Minimum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciBuffer ?: numberSize ZMQ_VMCI_BUFFER_SIZE
The size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciConnect ?: numberTimeout ZMQ_VMCI_CONNECT_TIMEOUT
Connection timeout for the socket. For
vmci://transports only.OptionalzapDomain ?: null | stringZMQ_ZAP_DOMAIN
Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the default on all
tcp://connections), ZAP authentication only happens if you set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 for more details.OptionalzapEnforce ?: booleanDomain ZMQ_ZAP_ENFORCE_DOMAIN
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.
Returns Reply
Properties
affinity
ZMQ_AFFINITY
I/O thread affinity, which determines which threads from the ØMQ I/O thread pool associated with the socket's context shall handle newly created connections.
Note: This value is a bit mask, but values higher than Number.MAX_SAFE_INTEGER may not be represented accurately! This currently means that configurations beyond 52 threads are unreliable.
backlog
ZMQ_BACKLOG
Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.
Readonlyclosed
Whether this socket was previously closed with close().
connectTimeout
ZMQ_CONNECT_TIMEOUT
Sets how long to wait before timing-out a connect() system call. The connect() system call normally takes a long time before it returns a time out error. Setting this option allows the library to time out the call at an earlier interval.
Readonlycontext
Context that this socket belongs to.
curvePublicKey
ZMQ_CURVE_PUBLICKEY
Sets the socket's long term public key. You must set this on CURVE client sockets. A server socket does not need to know its own public key. You can create a new keypair with curveKeyPair().
curveSecretKey
ZMQ_CURVE_SECRETKEY
Sets the socket's long term secret key. You must set this on both CURVE client and server sockets. You can create a new keypair with curveKeyPair().
curveServer
ZMQ_CURVE_SERVER
Defines whether the socket will act as server for CURVE security. A value of true means the socket will act as CURVE server. A value of false means the socket will not act as CURVE server, and its security role then depends on other option settings.
curveServerKey
ZMQ_CURVE_SERVERKEY
Sets the socket's long term server key. This is the public key of the CURVE server socket. You must set this on CURVE client sockets. This key must have been generated together with the server's secret key. You can create a new keypair with curveKeyPair().
Readonlyevents
Event Observer for this socket. This starts up a ØMQ monitoring socket internally that receives all socket events.
gssapiPlainText
gssapiPrincipal
gssapiPrincipalNameType
gssapiServer
gssapiServicePrincipal
gssapiServicePrincipalNameType
handshakeInterval
ZMQ_HANDSHAKE_IVL
Handshaking is the exchange of socket configuration information (socket type, identity, security) that occurs when a connection is first opened (only for connection-oriented transports). If handshaking does not complete within the configured time, the connection shall be closed. The value 0 means no handshake time limit.
heartbeatInterval
ZMQ_HEARTBEAT_IVL
Interval in milliseconds between sending ZMTP heartbeats for the specified socket. If this option is greater than 0, then a PING ZMTP command will be sent after every interval.
heartbeatTimeout
ZMQ_HEARTBEAT_TIMEOUT
How long (in milliseconds) to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic. This option is only valid if heartbeatInterval is greater than 0. The connection will time out if there is no traffic received after sending the PING command. The received traffic does not have to be a PONG command - any received traffic will cancel the timeout.
heartbeatTimeToLive
ZMQ_HEARTBEAT_TTL
The timeout in milliseconds on the remote peer for ZMTP heartbeats. If this option is greater than 0, the remote side shall time out the connection if it does not receive any more traffic within the TTL period. This option does not have any effect if heartbeatInterval is 0. Internally, this value is rounded down to the nearest decisecond, any value less than 100 will have no effect.
immediate
ZMQ_IMMEDIATE
By default queues will fill on outgoing connections even if the connection has not completed. This can lead to "lost" messages on sockets with round-robin routing (Request, Push, Dealer). If this option is set to true, messages shall be queued only to completed connections. This will cause the socket to block if there are no other connections, but will prevent queues from filling on pipes awaiting connection.
interface
ZMQ_BINDTODEVICE
Binds the socket to the given network interface (Linux only). Allows to use Linux VRF, see: https://www.kernel.org/doc/Documentation/networking/vrf.txt. Requires the program to be ran as root or with CAP_NET_RAW.
ipv6
ZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
ReadonlylastEndpoint
ZMQ_LAST_ENDPOINT
The last endpoint bound for TCP and IPC transports.
linger
ZMQ_LINGER
Determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with close().
loopbackFastPath
ZMQ_LOOPBACK_FASTPATH
Enable faster TCP connections on loopback devices. An application can enable this option to reduce the latency and improve the performance of loopback operations on a TCP socket on Windows.
maxMessageSize
ZMQ_MAXMSGSIZE
Limits the size of the inbound message. If a peer sends a message larger than the limit it is disconnected. Value of -1 means no limit.
multicastHops
ZMQ_MULTICAST_HOPS
Sets the time-to-live field in every multicast packet sent from this socket. The default is 1 which means that the multicast packets don't leave the local network.
multicastMaxTransportDataUnit
ZMQ_MULTICAST_MAXTPDU
Sets the maximum transport data unit size used for outbound multicast packets. This must be set at or below the minimum Maximum Transmission Unit (MTU) for all network paths over which multicast reception is required.
plainPassword
ZMQ_PLAIN_PASSWORD
Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
plainServer
ZMQ_PLAIN_SERVER
Defines whether the socket will act as server for PLAIN security. A value of true means the socket will act as PLAIN server. A value of false means the socket will not act as PLAIN server, and its security role then depends on other option settings.
plainUsername
ZMQ_PLAIN_USERNAME
Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
rate
ZMQ_RATE
Maximum send or receive data rate for multicast transports such as pgm.
Readonlyreadable
Whether any messages are currently available. If true, the next call to Readable.receive() will immediately read a message from the socket. For sockets that cannot receive messsages this is always false.
receiveBufferSize
ZMQ_RCVBUF
Underlying kernel receive buffer size in bytes. A value of -1 means leave the OS default unchanged.
receiveHighWaterMark
ZMQ_RCVHWM
The high water mark is a hard limit on the maximum number of incoming messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
receiveTimeout
ZMQ_RCVTIMEO
Sets the timeout receiving messages on the socket. If the value is 0, receive() will return a rejected promise immediately if there is no message to receive. If the value is -1, it will wait asynchronously until a message is available. For all other values, it will wait for a message for that amount of time before rejecting.
reconnectInterval
ZMQ_RECONNECT_IVL
Period ØMQ shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. The value -1 means no reconnection.
reconnectMaxInterval
ZMQ_RECONNECT_IVL_MAX
Maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled until reconnectMaxInterval is reached. This allows for exponential backoff strategy. Zero (the default) means no exponential backoff is performed and reconnect interval calculations are only based on reconnectInterval.
recoveryInterval
ZMQ_RECOVERY_IVL
Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
routingId
ZMQ_ROUTING_ID
The identity of the specified socket when connecting to a Router socket.
ReadonlysecurityMechanism
| null
| "plain"
| "curve"
| "gssapi"
ZMQ_MECHANISM
Returns the current security mechanism for the socket, if any. The security mechanism is set implictly by using any of the relevant security options. The returned value is one of:
null- No security mechanism is used."plain"- The PLAIN mechanism defines a simple username/password mechanism that lets a server authenticate a client. PLAIN makes no attempt at security or confidentiality."curve"- The CURVE mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server. CURVE is intended for use on public networks."gssapi"- The GSSAPI mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server using the Generic Security Service Application Program Interface (GSSAPI). The GSSAPI mechanism can be used on both public and private networks.
sendBufferSize
ZMQ_SNDBUF
Underlying kernel transmit buffer size in bytes. A value of -1 means leave the OS default unchanged.
sendHighWaterMark
ZMQ_SNDHWM
The high water mark is a hard limit on the maximum number of outgoing messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
sendTimeout
ZMQ_SNDTIMEO
Sets the timeout for sending messages on the socket. If the value is 0, send() will return a rejected promise immediately if the message cannot be sent. If the value is -1, it will wait asynchronously until the message is sent. For all other values, it will try to send the message for that amount of time before rejecting.
socksProxy
ZMQ_SOCKS_PROXY
The SOCKS5 proxy address that shall be used by the socket for the TCP connection(s). Does not support SOCKS5 authentication. If the endpoints are domain names instead of addresses they shall not be resolved and they shall be forwarded unchanged to the SOCKS proxy service in the client connection request message (address type 0x03 domain name).
tcpAcceptFilter
ZMQ_TCP_ACCEPT_FILTER
Assign a filter that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one filter is applied then new connection source IP should be matched. To clear all filters set to null. Filter is a string with IPv6 or IPv4 CIDR.
tcpKeepalive
ZMQ_TCP_KEEPALIVE
Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveCount
ZMQ_TCP_KEEPALIVE_CNT
Overrides TCP_KEEPCNT socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveIdle
ZMQ_TCP_KEEPALIVE_IDLE
Overrides TCP_KEEPIDLE / TCP_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveInterval
ZMQ_TCP_KEEPALIVE_INTVL
Overrides TCP_KEEPINTVL socket option (if supported by the OS). The default value of -1 leaves it to the OS default.
tcpMaxRetransmitTimeout
ZMQ_TCP_MAXRT
Sets how long before an unacknowledged TCP retransmit times out (if supported by the OS). The system normally attempts many TCP retransmits following an exponential backoff strategy. This means that after a network outage, it may take a long time before the session can be re-established. Setting this option allows the timeout to happen at a shorter interval.
ReadonlythreadSafe
ZMQ_THREAD_SAFE
Whether or not the socket is threadsafe. Currently only DRAFT sockets is thread-safe.
Readonlytype
ZMQ_TYPE
Retrieve the socket type. This is fairly useless because you can test the socket class with e.g. socket instanceof Dealer.
typeOfService
ZMQ_TOS
Sets the ToS fields (the Differentiated Services (DS) and Explicit Congestion Notification (ECN) field) of the IP header. The ToS field is typically used to specify a packet's priority. The availability of this option is dependent on intermediate network equipment that inspect the ToS field and provide a path for low-delay, high-throughput, highly-reliable service, etc.
vmciBufferMaxSize
ZMQ_VMCI_BUFFER_MAX_SIZE
Maximum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferMinSize
ZMQ_VMCI_BUFFER_MIN_SIZE
Minimum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferSize
ZMQ_VMCI_BUFFER_SIZE
The size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciConnectTimeout
ZMQ_VMCI_CONNECT_TIMEOUT
Connection timeout for the socket. For vmci:// transports only.
Readonlywritable
Whether any messages can be queued for sending. If true, the next call to Writable.send() will immediately queue a message on the socket. For sockets that cannot send messsages this is always false.
zapDomain
ZMQ_ZAP_DOMAIN
Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the default on all tcp:// connections), ZAP authentication only happens if you set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 for more details.
zapEnforceDomain
ZMQ_ZAP_ENFORCE_DOMAIN
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.
Methods
[asyncIterator]
- [async
Iterator] (): AsyncIterator<Buffer[], undefined, undefined> Asynchronously iterate over messages becoming available on the socket. When the socket is closed with Socket.close(), the iterator will return. Returning early from the iterator will not close the socket unless it also goes out of scope.
for await (const [msg] of socket) {
// handle messages
} -Returns AsyncIterator<Buffer[], undefined, undefined>
bind
- bind(address): Promise<void>
Binds the socket to the given address. During bind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.You can use
*in place of a hostname to bind on all interfaces/addresses, and you can use*in place of a port to bind to a random port (which can be retrieved with lastEndpoint later).await socket.bind("tcp://127.0.0.1:3456")
await socket.bind("tcp://*:3456") // binds on all interfaces
await socket.bind("tcp://127.0.0.1:*") // binds on random port -Parameters
- address: string
Address to bind this socket to.
Returns Promise<void>
Resolved when the socket was successfully bound.
- address: string
close
- close(): void
Closes the socket and disposes of all resources. Any messages that are queued may be discarded or sent in the background depending on the linger setting.
After this method is called, it is no longer possible to call any other methods on this socket.
Sockets that go out of scope and have no Readable.receive() or Writable.send() operations in progress will automatically be closed. Therefore it is not necessary in most applications to call close() manually.
Calling this method on a socket that is already closed is a no-op.
Returns void
connect
disconnect
- disconnect(address): void
Disconnects a previously connected socket from the given address and returns immediately. Disonnection will happen asynchronously in the background.
socket.disconnect("tcp://127.0.0.1:3456") -Parameters
- address: string
The previously connected address to disconnect from.
Returns void
- address: string
ProtectedgetBoolOption
ProtectedgetInt32Option
ProtectedgetInt64Option
ProtectedgetStringOption
ProtectedgetUint32Option
ProtectedgetUint64Option
receive
- receive(): Promise<Buffer[]>
Waits for the next single or multipart message to become availeble on the socket. Reads a message immediately if possible. If no messages can be read, it will wait asynchonously. The promise will be resolved with an array containing the parts of the next message when available.
const [msg] = await socket.receive()
const [part1, part2] = await socket.receive() -Reading may fail (eventually) if the socket has been configured with a receiveTimeout.
A call to receive() is guaranteed to return with a resolved promise immediately if a message could be read from the socket directly.
Only one asynchronously blocking call to receive() can be in progress simultaneously. If you call receive() again on the same socket it will return a rejected promise with an
EBUSYerror. For example, if no messages can be read and noawaitis used:socket.receive() // -> pending promise until read is possible
socket.receive() // -> promise rejection with `EBUSY` error -Note: Due to the nature of Node.js and to avoid blocking the main thread, this method always attempts to read messages with the
ZMQ_DONTWAITflag. It polls asynchronously if reading is not currently possible. This means that all functionality related to timeouts and blocking behaviour is reimplemented in the Node.js bindings. Any differences in behaviour with the native ZMQ library is considered a bug.Returns Promise<Buffer[]>
Resolved with message parts that were successfully read.
send
- send(message, ...options): Promise<void>
Sends a single message or a multipart message on the socket. Queues the message immediately if possible, and returns a resolved promise. If the message cannot be queued because the high water mark has been reached, it will wait asynchronously. The promise will be resolved when the message was queued successfully.
await socket.send("hello world")
await socket.send(["hello", "world"]) -Queueing may fail eventually if the socket has been configured with a sendTimeout.
A call to send() is guaranteed to return with a resolved promise immediately if the message could be queued directly.
Only one asynchronously blocking call to send() may be executed simultaneously. If you call send() again on a socket that is in the mute state it will return a rejected promise with an
EBUSYerror.The reason for disallowing multiple send() calls simultaneously is that it could create an implicit queue of unsendable outgoing messages. This would circumvent the socket's sendHighWaterMark. Such an implementation could even exhaust all system memory and cause the Node.js process to abort.
For most application you should not notice this implementation detail. Only in rare occasions will a call to send() that does not resolve immediately be undesired. Here are some common scenarios:
If you wish to send a message, use
await send(...). ZeroMQ socket types have been carefully designed to give you the correct blocking behaviour on the chosen socket type in almost all cases:If sending is not possible, it is often better to wait than to continue as if nothing happened. For example, on a Request socket, you can only receive a reply once a message has been sent; so waiting until a message could be queued before continuing with the rest of the program (likely to read from the socket) is required.
Certain socket types (such as Router) will always allow queueing messages and
await send(...)won't delay any code that comes after. This makes sense for routers, since typically you don't want a single send operation to stop the handling of other incoming or outgoing messages.
If you wish to send on an occasionally blocking socket (for example on a Router with the Router.mandatory option set, or on a Dealer) and you're 100% certain that dropping a message is better than blocking, then you can set the sendTimeout option to
0to effectively force send() to always resolve immediately. Be prepared to catch exceptions if sending a message is not immediately possible.If you wish to send on a socket and messages should be queued before they are dropped, you should implement a simple queue in JavaScript. Such a queue is not provided by this library because most real world applications need to deal with undeliverable messages in more complex ways - for example, they might need to reply with a status message; or first retry delivery a certain number of times before giving up.
Parameters
- message: MessageLike | MessageLike[]
Single message or multipart message to queue for sending.
Rest...options: []Any options, if applicable to the socket type (DRAFT only).
Returns Promise<void>
Resolved when the message was successfully queued.
ProtectedsetBoolOption
ProtectedsetInt32Option
ProtectedsetInt64Option
ProtectedsetStringOption
ProtectedsetUint32Option
ProtectedsetUint64Option
unbind
- unbind(address): Promise<void>
Unbinds the socket to the given address. During unbind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.Parameters
- address: string
Address to unbind this socket from.
Returns Promise<void>
Resolved when the socket was successfully unbound.
- address: string
Class Reply
A Reply socket can act as a server which receives requests from and sends replies to a Request socket. This socket type allows only an alternating sequence of Readable.receive() and subsequent Writable.send() calls. Each request received is fair-queued from among all clients, and each reply sent is routed to the client that issued the last request. If the original requester does not exist any more the reply is silently discarded.
Hierarchy (View Summary)
Index
Constructors
Properties
Methods
Constructors
constructor
- new Reply(
options?: {
affinity?: number;
backlog?: number;
connectTimeout?: number;
context?: Context;
curvePublicKey?: null | string;
curveSecretKey?: null | string;
curveServer?: boolean;
curveServerKey?: null | string;
gssapiPlainText?: boolean;
gssapiPrincipal?: null | string;
gssapiPrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
gssapiServer?: boolean;
gssapiServicePrincipal?: null | string;
gssapiServicePrincipalNameType?:
| "hostBased"
| "userName"
| "krb5Principal";
handshakeInterval?: number;
heartbeatInterval?: number;
heartbeatTimeout?: number;
heartbeatTimeToLive?: number;
immediate?: boolean;
interface?: null
| string;
ipv6?: boolean;
linger?: number;
loopbackFastPath?: boolean;
maxMessageSize?: number;
multicastHops?: number;
multicastMaxTransportDataUnit?: number;
plainPassword?: null | string;
plainServer?: boolean;
plainUsername?: null | string;
rate?: number;
receiveBufferSize?: number;
receiveHighWaterMark?: number;
receiveTimeout?: number;
reconnectInterval?: number;
reconnectMaxInterval?: number;
recoveryInterval?: number;
routingId?: null | string;
sendBufferSize?: number;
sendHighWaterMark?: number;
sendTimeout?: number;
socksProxy?: null | string;
tcpAcceptFilter?: null | string;
tcpKeepalive?: number;
tcpKeepaliveCount?: number;
tcpKeepaliveIdle?: number;
tcpKeepaliveInterval?: number;
tcpMaxRetransmitTimeout?: number;
typeOfService?: number;
vmciBufferMaxSize?: number;
vmciBufferMinSize?: number;
vmciBufferSize?: number;
vmciConnectTimeout?: number;
zapDomain?: null | string;
zapEnforceDomain?: boolean;
},
): Reply Parameters
Optionaloptions: {
affinity?: number;
backlog?: number;
connectTimeout?: number;
context?: Context;
curvePublicKey?: null | string;
curveSecretKey?: null | string;
curveServer?: boolean;
curveServerKey?: null | string;
gssapiPlainText?: boolean;
gssapiPrincipal?: null | string;
gssapiPrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
gssapiServer?: boolean;
gssapiServicePrincipal?: null | string;
gssapiServicePrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
handshakeInterval?: number;
heartbeatInterval?: number;
heartbeatTimeout?: number;
heartbeatTimeToLive?: number;
immediate?: boolean;
interface?: null | string;
ipv6?: boolean;
linger?: number;
loopbackFastPath?: boolean;
maxMessageSize?: number;
multicastHops?: number;
multicastMaxTransportDataUnit?: number;
plainPassword?: null | string;
plainServer?: boolean;
plainUsername?: null | string;
rate?: number;
receiveBufferSize?: number;
receiveHighWaterMark?: number;
receiveTimeout?: number;
reconnectInterval?: number;
reconnectMaxInterval?: number;
recoveryInterval?: number;
routingId?: null | string;
sendBufferSize?: number;
sendHighWaterMark?: number;
sendTimeout?: number;
socksProxy?: null | string;
tcpAcceptFilter?: null | string;
tcpKeepalive?: number;
tcpKeepaliveCount?: number;
tcpKeepaliveIdle?: number;
tcpKeepaliveInterval?: number;
tcpMaxRetransmitTimeout?: number;
typeOfService?: number;
vmciBufferMaxSize?: number;
vmciBufferMinSize?: number;
vmciBufferSize?: number;
vmciConnectTimeout?: number;
zapDomain?: null | string;
zapEnforceDomain?: boolean;
}Optionalaffinity?: numberZMQ_AFFINITY
I/O thread affinity, which determines which threads from the ØMQ I/O thread pool associated with the socket's context shall handle newly created connections.
Note: This value is a bit mask, but values higher than
Number.MAX_SAFE_INTEGERmay not be represented accurately! This currently means that configurations beyond 52 threads are unreliable.Optionalbacklog?: numberZMQ_BACKLOG
Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.
OptionalconnectTimeout?: numberZMQ_CONNECT_TIMEOUT
Sets how long to wait before timing-out a connect() system call. The connect() system call normally takes a long time before it returns a time out error. Setting this option allows the library to time out the call at an earlier interval.
Optionalcontext?: ContextOptionalcurvePublicKey?: null | stringZMQ_CURVE_PUBLICKEY
Sets the socket's long term public key. You must set this on CURVE client sockets. A server socket does not need to know its own public key. You can create a new keypair with curveKeyPair().
OptionalcurveSecretKey?: null | stringZMQ_CURVE_SECRETKEY
Sets the socket's long term secret key. You must set this on both CURVE client and server sockets. You can create a new keypair with curveKeyPair().
OptionalcurveServer?: booleanZMQ_CURVE_SERVER
Defines whether the socket will act as server for CURVE security. A value of
truemeans the socket will act as CURVE server. A value offalsemeans the socket will not act as CURVE server, and its security role then depends on other option settings.OptionalcurveServerKey?: null | stringZMQ_CURVE_SERVERKEY
Sets the socket's long term server key. This is the public key of the CURVE server socket. You must set this on CURVE client sockets. This key must have been generated together with the server's secret key. You can create a new keypair with curveKeyPair().
OptionalgssapiPlainText?: booleanOptionalgssapiPrincipal?: null | stringOptionalgssapiPrincipalNameType?: "hostBased" | "userName" | "krb5Principal"OptionalgssapiServer?: booleanOptionalgssapiServicePrincipal?: null | stringOptionalgssapiServicePrincipalNameType?: "hostBased" | "userName" | "krb5Principal"OptionalhandshakeInterval?: numberZMQ_HANDSHAKE_IVL
Handshaking is the exchange of socket configuration information (socket type, identity, security) that occurs when a connection is first opened (only for connection-oriented transports). If handshaking does not complete within the configured time, the connection shall be closed. The value 0 means no handshake time limit.
OptionalheartbeatInterval?: numberZMQ_HEARTBEAT_IVL
Interval in milliseconds between sending ZMTP heartbeats for the specified socket. If this option is greater than 0, then a PING ZMTP command will be sent after every interval.
OptionalheartbeatTimeout?: numberZMQ_HEARTBEAT_TIMEOUT
How long (in milliseconds) to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic. This option is only valid if heartbeatInterval is greater than 0. The connection will time out if there is no traffic received after sending the PING command. The received traffic does not have to be a PONG command - any received traffic will cancel the timeout.
OptionalheartbeatTimeToLive?: numberZMQ_HEARTBEAT_TTL
The timeout in milliseconds on the remote peer for ZMTP heartbeats. If this option is greater than 0, the remote side shall time out the connection if it does not receive any more traffic within the TTL period. This option does not have any effect if heartbeatInterval is 0. Internally, this value is rounded down to the nearest decisecond, any value less than 100 will have no effect.
Optionalimmediate?: booleanZMQ_IMMEDIATE
By default queues will fill on outgoing connections even if the connection has not completed. This can lead to "lost" messages on sockets with round-robin routing (Request, Push, Dealer). If this option is set to
true, messages shall be queued only to completed connections. This will cause the socket to block if there are no other connections, but will prevent queues from filling on pipes awaiting connection.Optionalinterface?: null | stringZMQ_BINDTODEVICE
Binds the socket to the given network interface (Linux only). Allows to use Linux VRF, see: https://www.kernel.org/doc/Documentation/networking/vrf.txt. Requires the program to be ran as root or with
CAP_NET_RAW.Optionalipv6?: booleanZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
Optionallinger?: numberZMQ_LINGER
Determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with close().
OptionalloopbackFastPath?: booleanZMQ_LOOPBACK_FASTPATH
Enable faster TCP connections on loopback devices. An application can enable this option to reduce the latency and improve the performance of loopback operations on a TCP socket on Windows.
OptionalmaxMessageSize?: numberZMQ_MAXMSGSIZE
Limits the size of the inbound message. If a peer sends a message larger than the limit it is disconnected. Value of -1 means no limit.
OptionalmulticastHops?: numberZMQ_MULTICAST_HOPS
Sets the time-to-live field in every multicast packet sent from this socket. The default is 1 which means that the multicast packets don't leave the local network.
OptionalmulticastMaxTransportDataUnit?: numberZMQ_MULTICAST_MAXTPDU
Sets the maximum transport data unit size used for outbound multicast packets. This must be set at or below the minimum Maximum Transmission Unit (MTU) for all network paths over which multicast reception is required.
OptionalplainPassword?: null | stringZMQ_PLAIN_PASSWORD
Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
OptionalplainServer?: booleanZMQ_PLAIN_SERVER
Defines whether the socket will act as server for PLAIN security. A value of
truemeans the socket will act as PLAIN server. A value offalsemeans the socket will not act as PLAIN server, and its security role then depends on other option settings.OptionalplainUsername?: null | stringZMQ_PLAIN_USERNAME
Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
Optionalrate?: numberZMQ_RATE
Maximum send or receive data rate for multicast transports such as
pgm.OptionalreceiveBufferSize?: numberZMQ_RCVBUF
Underlying kernel receive buffer size in bytes. A value of -1 means leave the OS default unchanged.
OptionalreceiveHighWaterMark?: numberZMQ_RCVHWM
The high water mark is a hard limit on the maximum number of incoming messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
OptionalreceiveTimeout?: numberZMQ_RCVTIMEO
Sets the timeout receiving messages on the socket. If the value is 0, receive() will return a rejected promise immediately if there is no message to receive. If the value is -1, it will wait asynchronously until a message is available. For all other values, it will wait for a message for that amount of time before rejecting.
OptionalreconnectInterval?: numberZMQ_RECONNECT_IVL
Period ØMQ shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. The value -1 means no reconnection.
OptionalreconnectMaxInterval?: numberZMQ_RECONNECT_IVL_MAX
Maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled until reconnectMaxInterval is reached. This allows for exponential backoff strategy. Zero (the default) means no exponential backoff is performed and reconnect interval calculations are only based on reconnectInterval.
OptionalrecoveryInterval?: numberZMQ_RECOVERY_IVL
Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
OptionalroutingId?: null | stringZMQ_ROUTING_ID
The identity of the specified socket when connecting to a
Routersocket.OptionalsendBufferSize?: numberZMQ_SNDBUF
Underlying kernel transmit buffer size in bytes. A value of -1 means leave the OS default unchanged.
OptionalsendHighWaterMark?: numberZMQ_SNDHWM
The high water mark is a hard limit on the maximum number of outgoing messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
OptionalsendTimeout?: numberZMQ_SNDTIMEO
Sets the timeout for sending messages on the socket. If the value is 0, send() will return a rejected promise immediately if the message cannot be sent. If the value is -1, it will wait asynchronously until the message is sent. For all other values, it will try to send the message for that amount of time before rejecting.
OptionalsocksProxy?: null | stringZMQ_SOCKS_PROXY
The SOCKS5 proxy address that shall be used by the socket for the TCP connection(s). Does not support SOCKS5 authentication. If the endpoints are domain names instead of addresses they shall not be resolved and they shall be forwarded unchanged to the SOCKS proxy service in the client connection request message (address type 0x03 domain name).
OptionaltcpAcceptFilter?: null | stringZMQ_TCP_ACCEPT_FILTER
Assign a filter that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one filter is applied then new connection source IP should be matched. To clear all filters set to
null. Filter is a string with IPv6 or IPv4 CIDR.OptionaltcpKeepalive?: numberZMQ_TCP_KEEPALIVE
Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepaliveCount?: numberZMQ_TCP_KEEPALIVE_CNT
Overrides TCP_KEEPCNT socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepaliveIdle?: numberZMQ_TCP_KEEPALIVE_IDLE
Overrides TCP_KEEPIDLE / TCP_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepaliveInterval?: numberZMQ_TCP_KEEPALIVE_INTVL
Overrides TCP_KEEPINTVL socket option (if supported by the OS). The default value of -1 leaves it to the OS default.
OptionaltcpMaxRetransmitTimeout?: numberZMQ_TCP_MAXRT
Sets how long before an unacknowledged TCP retransmit times out (if supported by the OS). The system normally attempts many TCP retransmits following an exponential backoff strategy. This means that after a network outage, it may take a long time before the session can be re-established. Setting this option allows the timeout to happen at a shorter interval.
OptionaltypeOfService?: numberZMQ_TOS
Sets the ToS fields (the Differentiated Services (DS) and Explicit Congestion Notification (ECN) field) of the IP header. The ToS field is typically used to specify a packet's priority. The availability of this option is dependent on intermediate network equipment that inspect the ToS field and provide a path for low-delay, high-throughput, highly-reliable service, etc.
OptionalvmciBufferMaxSize?: numberZMQ_VMCI_BUFFER_MAX_SIZE
Maximum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciBufferMinSize?: numberZMQ_VMCI_BUFFER_MIN_SIZE
Minimum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciBufferSize?: numberZMQ_VMCI_BUFFER_SIZE
The size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciConnectTimeout?: numberZMQ_VMCI_CONNECT_TIMEOUT
Connection timeout for the socket. For
vmci://transports only.OptionalzapDomain?: null | stringZMQ_ZAP_DOMAIN
Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the default on all
tcp://connections), ZAP authentication only happens if you set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 for more details.OptionalzapEnforceDomain?: booleanZMQ_ZAP_ENFORCE_DOMAIN
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.
Returns Reply
Properties
affinity
ZMQ_AFFINITY
I/O thread affinity, which determines which threads from the ØMQ I/O thread pool associated with the socket's context shall handle newly created connections.
Note: This value is a bit mask, but values higher than Number.MAX_SAFE_INTEGER may not be represented accurately! This currently means that configurations beyond 52 threads are unreliable.
backlog
ZMQ_BACKLOG
Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.
Readonlyclosed
Whether this socket was previously closed with close().
connectTimeout
ZMQ_CONNECT_TIMEOUT
Sets how long to wait before timing-out a connect() system call. The connect() system call normally takes a long time before it returns a time out error. Setting this option allows the library to time out the call at an earlier interval.
Readonlycontext
Context that this socket belongs to.
curvePublicKey
ZMQ_CURVE_PUBLICKEY
Sets the socket's long term public key. You must set this on CURVE client sockets. A server socket does not need to know its own public key. You can create a new keypair with curveKeyPair().
curveSecretKey
ZMQ_CURVE_SECRETKEY
Sets the socket's long term secret key. You must set this on both CURVE client and server sockets. You can create a new keypair with curveKeyPair().
curveServer
ZMQ_CURVE_SERVER
Defines whether the socket will act as server for CURVE security. A value of true means the socket will act as CURVE server. A value of false means the socket will not act as CURVE server, and its security role then depends on other option settings.
curveServerKey
ZMQ_CURVE_SERVERKEY
Sets the socket's long term server key. This is the public key of the CURVE server socket. You must set this on CURVE client sockets. This key must have been generated together with the server's secret key. You can create a new keypair with curveKeyPair().
Readonlyevents
Event Observer for this socket. This starts up a ØMQ monitoring socket internally that receives all socket events.
gssapiPlainText
gssapiPrincipal
gssapiPrincipalNameType
gssapiServer
gssapiServicePrincipal
gssapiServicePrincipalNameType
handshakeInterval
ZMQ_HANDSHAKE_IVL
Handshaking is the exchange of socket configuration information (socket type, identity, security) that occurs when a connection is first opened (only for connection-oriented transports). If handshaking does not complete within the configured time, the connection shall be closed. The value 0 means no handshake time limit.
heartbeatInterval
ZMQ_HEARTBEAT_IVL
Interval in milliseconds between sending ZMTP heartbeats for the specified socket. If this option is greater than 0, then a PING ZMTP command will be sent after every interval.
heartbeatTimeout
ZMQ_HEARTBEAT_TIMEOUT
How long (in milliseconds) to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic. This option is only valid if heartbeatInterval is greater than 0. The connection will time out if there is no traffic received after sending the PING command. The received traffic does not have to be a PONG command - any received traffic will cancel the timeout.
heartbeatTimeToLive
ZMQ_HEARTBEAT_TTL
The timeout in milliseconds on the remote peer for ZMTP heartbeats. If this option is greater than 0, the remote side shall time out the connection if it does not receive any more traffic within the TTL period. This option does not have any effect if heartbeatInterval is 0. Internally, this value is rounded down to the nearest decisecond, any value less than 100 will have no effect.
immediate
ZMQ_IMMEDIATE
By default queues will fill on outgoing connections even if the connection has not completed. This can lead to "lost" messages on sockets with round-robin routing (Request, Push, Dealer). If this option is set to true, messages shall be queued only to completed connections. This will cause the socket to block if there are no other connections, but will prevent queues from filling on pipes awaiting connection.
interface
ZMQ_BINDTODEVICE
Binds the socket to the given network interface (Linux only). Allows to use Linux VRF, see: https://www.kernel.org/doc/Documentation/networking/vrf.txt. Requires the program to be ran as root or with CAP_NET_RAW.
ipv6
ZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
ReadonlylastEndpoint
ZMQ_LAST_ENDPOINT
The last endpoint bound for TCP and IPC transports.
linger
ZMQ_LINGER
Determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with close().
loopbackFastPath
ZMQ_LOOPBACK_FASTPATH
Enable faster TCP connections on loopback devices. An application can enable this option to reduce the latency and improve the performance of loopback operations on a TCP socket on Windows.
maxMessageSize
ZMQ_MAXMSGSIZE
Limits the size of the inbound message. If a peer sends a message larger than the limit it is disconnected. Value of -1 means no limit.
multicastHops
ZMQ_MULTICAST_HOPS
Sets the time-to-live field in every multicast packet sent from this socket. The default is 1 which means that the multicast packets don't leave the local network.
multicastMaxTransportDataUnit
ZMQ_MULTICAST_MAXTPDU
Sets the maximum transport data unit size used for outbound multicast packets. This must be set at or below the minimum Maximum Transmission Unit (MTU) for all network paths over which multicast reception is required.
plainPassword
ZMQ_PLAIN_PASSWORD
Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
plainServer
ZMQ_PLAIN_SERVER
Defines whether the socket will act as server for PLAIN security. A value of true means the socket will act as PLAIN server. A value of false means the socket will not act as PLAIN server, and its security role then depends on other option settings.
plainUsername
ZMQ_PLAIN_USERNAME
Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
rate
ZMQ_RATE
Maximum send or receive data rate for multicast transports such as pgm.
Readonlyreadable
Whether any messages are currently available. If true, the next call to Readable.receive() will immediately read a message from the socket. For sockets that cannot receive messsages this is always false.
receiveBufferSize
ZMQ_RCVBUF
Underlying kernel receive buffer size in bytes. A value of -1 means leave the OS default unchanged.
receiveHighWaterMark
ZMQ_RCVHWM
The high water mark is a hard limit on the maximum number of incoming messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
receiveTimeout
ZMQ_RCVTIMEO
Sets the timeout receiving messages on the socket. If the value is 0, receive() will return a rejected promise immediately if there is no message to receive. If the value is -1, it will wait asynchronously until a message is available. For all other values, it will wait for a message for that amount of time before rejecting.
reconnectInterval
ZMQ_RECONNECT_IVL
Period ØMQ shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. The value -1 means no reconnection.
reconnectMaxInterval
ZMQ_RECONNECT_IVL_MAX
Maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled until reconnectMaxInterval is reached. This allows for exponential backoff strategy. Zero (the default) means no exponential backoff is performed and reconnect interval calculations are only based on reconnectInterval.
recoveryInterval
ZMQ_RECOVERY_IVL
Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
routingId
ZMQ_ROUTING_ID
The identity of the specified socket when connecting to a Router socket.
ReadonlysecurityMechanism
ZMQ_MECHANISM
Returns the current security mechanism for the socket, if any. The security mechanism is set implictly by using any of the relevant security options. The returned value is one of:
null- No security mechanism is used."plain"- The PLAIN mechanism defines a simple username/password mechanism that lets a server authenticate a client. PLAIN makes no attempt at security or confidentiality."curve"- The CURVE mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server. CURVE is intended for use on public networks."gssapi"- The GSSAPI mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server using the Generic Security Service Application Program Interface (GSSAPI). The GSSAPI mechanism can be used on both public and private networks.
sendBufferSize
ZMQ_SNDBUF
Underlying kernel transmit buffer size in bytes. A value of -1 means leave the OS default unchanged.
sendHighWaterMark
ZMQ_SNDHWM
The high water mark is a hard limit on the maximum number of outgoing messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
sendTimeout
ZMQ_SNDTIMEO
Sets the timeout for sending messages on the socket. If the value is 0, send() will return a rejected promise immediately if the message cannot be sent. If the value is -1, it will wait asynchronously until the message is sent. For all other values, it will try to send the message for that amount of time before rejecting.
socksProxy
ZMQ_SOCKS_PROXY
The SOCKS5 proxy address that shall be used by the socket for the TCP connection(s). Does not support SOCKS5 authentication. If the endpoints are domain names instead of addresses they shall not be resolved and they shall be forwarded unchanged to the SOCKS proxy service in the client connection request message (address type 0x03 domain name).
tcpAcceptFilter
ZMQ_TCP_ACCEPT_FILTER
Assign a filter that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one filter is applied then new connection source IP should be matched. To clear all filters set to null. Filter is a string with IPv6 or IPv4 CIDR.
tcpKeepalive
ZMQ_TCP_KEEPALIVE
Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveCount
ZMQ_TCP_KEEPALIVE_CNT
Overrides TCP_KEEPCNT socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveIdle
ZMQ_TCP_KEEPALIVE_IDLE
Overrides TCP_KEEPIDLE / TCP_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveInterval
ZMQ_TCP_KEEPALIVE_INTVL
Overrides TCP_KEEPINTVL socket option (if supported by the OS). The default value of -1 leaves it to the OS default.
tcpMaxRetransmitTimeout
ZMQ_TCP_MAXRT
Sets how long before an unacknowledged TCP retransmit times out (if supported by the OS). The system normally attempts many TCP retransmits following an exponential backoff strategy. This means that after a network outage, it may take a long time before the session can be re-established. Setting this option allows the timeout to happen at a shorter interval.
ReadonlythreadSafe
ZMQ_THREAD_SAFE
Whether or not the socket is threadsafe. Currently only DRAFT sockets is thread-safe.
Readonlytype
ZMQ_TYPE
Retrieve the socket type. This is fairly useless because you can test the socket class with e.g. socket instanceof Dealer.
typeOfService
ZMQ_TOS
Sets the ToS fields (the Differentiated Services (DS) and Explicit Congestion Notification (ECN) field) of the IP header. The ToS field is typically used to specify a packet's priority. The availability of this option is dependent on intermediate network equipment that inspect the ToS field and provide a path for low-delay, high-throughput, highly-reliable service, etc.
vmciBufferMaxSize
ZMQ_VMCI_BUFFER_MAX_SIZE
Maximum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferMinSize
ZMQ_VMCI_BUFFER_MIN_SIZE
Minimum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferSize
ZMQ_VMCI_BUFFER_SIZE
The size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciConnectTimeout
ZMQ_VMCI_CONNECT_TIMEOUT
Connection timeout for the socket. For vmci:// transports only.
Readonlywritable
Whether any messages can be queued for sending. If true, the next call to Writable.send() will immediately queue a message on the socket. For sockets that cannot send messsages this is always false.
zapDomain
ZMQ_ZAP_DOMAIN
Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the default on all tcp:// connections), ZAP authentication only happens if you set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 for more details.
zapEnforceDomain
ZMQ_ZAP_ENFORCE_DOMAIN
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.
Methods
[asyncIterator]
- "[asyncIterator]"(): AsyncIterator<Buffer[]>
Asynchronously iterate over messages becoming available on the socket. When the socket is closed with Socket.close(), the iterator will return. Returning early from the iterator will not close the socket unless it also goes out of scope.
for await (const [msg] of socket) {
// handle messages
} +Returns AsyncIterator<Buffer[]>
bind
- bind(address: string): Promise<void>
Binds the socket to the given address. During bind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.You can use
*in place of a hostname to bind on all interfaces/addresses, and you can use*in place of a port to bind to a random port (which can be retrieved with lastEndpoint later).await socket.bind("tcp://127.0.0.1:3456")
await socket.bind("tcp://*:3456") // binds on all interfaces
await socket.bind("tcp://127.0.0.1:*") // binds on random port +Parameters
- address: string
Address to bind this socket to.
Returns Promise<void>
Resolved when the socket was successfully bound.
- address: string
bindSync
- bindSync(address: string): void
Binds the socket to the given address. During bind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.You can use
*in place of a hostname to bind on all interfaces/addresses, and you can use*in place of a port to bind to a random port (which can be retrieved with lastEndpoint later).socket.bindSync("tcp://127.0.0.1:3456")
socket.bindSync("tcp://*:3456") // binds on all interfaces
socket.bindSync("tcp://127.0.0.1:*") // binds on random port +Parameters
- address: string
Address to bind this socket to.
Returns void
Resolved when the socket was successfully bound.
- address: string
close
- close(): void
Closes the socket and disposes of all resources. Any messages that are queued may be discarded or sent in the background depending on the linger setting.
After this method is called, it is no longer possible to call any other methods on this socket.
Sockets that go out of scope and have no Readable.receive() or Writable.send() operations in progress will automatically be closed. Therefore it is not necessary in most applications to call close() manually.
Calling this method on a socket that is already closed is a no-op.
Returns void
connect
disconnect
- disconnect(address: string): void
Disconnects a previously connected socket from the given address and returns immediately. Disonnection will happen asynchronously in the background.
socket.disconnect("tcp://127.0.0.1:3456") +Parameters
- address: string
The previously connected address to disconnect from.
Returns void
- address: string
ProtectedgetBoolOption
ProtectedgetInt32Option
ProtectedgetInt64Option
ProtectedgetStringOption
ProtectedgetUint32Option
ProtectedgetUint64Option
receive
- receive(): Promise<Buffer[]>
Waits for the next single or multipart message to become availeble on the socket. Reads a message immediately if possible. If no messages can be read, it will wait asynchonously. The promise will be resolved with an array containing the parts of the next message when available.
const [msg] = await socket.receive()
const [part1, part2] = await socket.receive() +Reading may fail (eventually) if the socket has been configured with a receiveTimeout.
A call to receive() is guaranteed to return with a resolved promise immediately if a message could be read from the socket directly.
Only one asynchronously blocking call to receive() can be in progress simultaneously. If you call receive() again on the same socket it will return a rejected promise with an
EBUSYerror. For example, if no messages can be read and noawaitis used:socket.receive() // -> pending promise until read is possible
socket.receive() // -> promise rejection with `EBUSY` error +Note: Due to the nature of Node.js and to avoid blocking the main thread, this method always attempts to read messages with the
ZMQ_DONTWAITflag. It polls asynchronously if reading is not currently possible. This means that all functionality related to timeouts and blocking behaviour is reimplemented in the Node.js bindings. Any differences in behaviour with the native ZMQ library is considered a bug.Returns Promise<Buffer[]>
Resolved with message parts that were successfully read.
send
- send(message: MessageLike | MessageLike[], ...options: []): Promise<void>
Sends a single message or a multipart message on the socket. Queues the message immediately if possible, and returns a resolved promise. If the message cannot be queued because the high water mark has been reached, it will wait asynchronously. The promise will be resolved when the message was queued successfully.
await socket.send("hello world")
await socket.send(["hello", "world"]) +Queueing may fail eventually if the socket has been configured with a sendTimeout.
A call to send() is guaranteed to return with a resolved promise immediately if the message could be queued directly.
Only one asynchronously blocking call to send() may be executed simultaneously. If you call send() again on a socket that is in the mute state it will return a rejected promise with an
EBUSYerror.The reason for disallowing multiple send() calls simultaneously is that it could create an implicit queue of unsendable outgoing messages. This would circumvent the socket's sendHighWaterMark. Such an implementation could even exhaust all system memory and cause the Node.js process to abort.
For most application you should not notice this implementation detail. Only in rare occasions will a call to send() that does not resolve immediately be undesired. Here are some common scenarios:
If you wish to send a message, use
await send(...). ZeroMQ socket types have been carefully designed to give you the correct blocking behaviour on the chosen socket type in almost all cases:If sending is not possible, it is often better to wait than to continue as if nothing happened. For example, on a Request socket, you can only receive a reply once a message has been sent; so waiting until a message could be queued before continuing with the rest of the program (likely to read from the socket) is required.
Certain socket types (such as Router) will always allow queueing messages and
await send(...)won't delay any code that comes after. This makes sense for routers, since typically you don't want a single send operation to stop the handling of other incoming or outgoing messages.
If you wish to send on an occasionally blocking socket (for example on a Router with the Router.mandatory option set, or on a Dealer) and you're 100% certain that dropping a message is better than blocking, then you can set the sendTimeout option to
0to effectively force send() to always resolve immediately. Be prepared to catch exceptions if sending a message is not immediately possible.If you wish to send on a socket and messages should be queued before they are dropped, you should implement a simple queue in JavaScript. Such a queue is not provided by this library because most real world applications need to deal with undeliverable messages in more complex ways - for example, they might need to reply with a status message; or first retry delivery a certain number of times before giving up.
Parameters
- message: MessageLike | MessageLike[]
Single message or multipart message to queue for sending.
- ...options: []
Any options, if applicable to the socket type (DRAFT only).
Returns Promise<void>
Resolved when the message was successfully queued.
ProtectedsetBoolOption
ProtectedsetInt32Option
ProtectedsetInt64Option
ProtectedsetStringOption
ProtectedsetUint32Option
ProtectedsetUint64Option
unbind
- unbind(address: string): Promise<void>
Unbinds the socket to the given address. During unbind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.Parameters
- address: string
Address to unbind this socket from.
Returns Promise<void>
Resolved when the socket was successfully unbound.
- address: string
unbindSync
- unbindSync(address: string): void
Unbinds the socket to the given address. During unbind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.Parameters
- address: string
Address to unbind this socket from.
Returns void
Resolved when the socket was successfully unbound.
- address: string
Class Request
A Request socket acts as a client to send requests to and receive replies from a Reply socket. This socket allows only an alternating sequence of Writable.send() and subsequent Readable.receive() calls. Each request sent is round-robined among all services, and each reply received is matched with the last issued request.
If no services are available, then any send operation on the socket shall block until at least one service becomes available. The REQ socket shall not discard messages.
Hierarchy (view full)
Index
Constructors
Properties
Methods
Constructors
constructor
- new
Request (options?): Request Parameters
Optionaloptions: {
affinity?: number;
backlog?: number;
connectTimeout?: number;
context?: Context;
correlate?: boolean;
curvePublicKey?: null | string;
curveSecretKey?: null | string;
curveServer?: boolean;
curveServerKey?: null | string;
gssapiPlainText?: boolean;
gssapiPrincipal?: null | string;
gssapiPrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
gssapiServer?: boolean;
gssapiServicePrincipal?: null | string;
gssapiServicePrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
handshakeInterval?: number;
heartbeatInterval?: number;
heartbeatTimeout?: number;
heartbeatTimeToLive?: number;
immediate?: boolean;
interface?: null | string;
ipv6?: boolean;
linger?: number;
loopbackFastPath?: boolean;
maxMessageSize?: number;
multicastHops?: number;
multicastMaxTransportDataUnit?: number;
plainPassword?: null | string;
plainServer?: boolean;
plainUsername?: null | string;
probeRouter?: boolean;
rate?: number;
receiveBufferSize?: number;
receiveHighWaterMark?: number;
receiveTimeout?: number;
reconnectInterval?: number;
reconnectMaxInterval?: number;
recoveryInterval?: number;
relaxed?: boolean;
routingId?: null | string;
sendBufferSize?: number;
sendHighWaterMark?: number;
sendTimeout?: number;
socksProxy?: null | string;
tcpAcceptFilter?: null | string;
tcpKeepalive?: number;
tcpKeepaliveCount?: number;
tcpKeepaliveIdle?: number;
tcpKeepaliveInterval?: number;
tcpMaxRetransmitTimeout?: number;
typeOfService?: number;
vmciBufferMaxSize?: number;
vmciBufferMinSize?: number;
vmciBufferSize?: number;
vmciConnectTimeout?: number;
zapDomain?: null | string;
zapEnforceDomain?: boolean;
}Optionalaffinity?: numberZMQ_AFFINITY
I/O thread affinity, which determines which threads from the ØMQ I/O thread pool associated with the socket's context shall handle newly created connections.
Note: This value is a bit mask, but values higher than
Number.MAX_SAFE_INTEGERmay not be represented accurately! This currently means that configurations beyond 52 threads are unreliable.Optionalbacklog?: numberZMQ_BACKLOG
Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.
OptionalconnectTimeout ?: numberZMQ_CONNECT_TIMEOUT
Sets how long to wait before timing-out a connect() system call. The connect() system call normally takes a long time before it returns a time out error. Setting this option allows the library to time out the call at an earlier interval.
Optionalcontext?: ContextOptionalcorrelate?: booleanZMQ_REQ_CORRELATE
The default behaviour of Request sockets is to rely on the ordering of messages to match requests and responses and that is usually sufficient. When this option is set to
truethe socket will prefix outgoing messages with an extra frame containing a request id. That means the full message is[<request id>,null, user frames…]. The Request socket will discard all incoming messages that don't begin with these two frames.OptionalcurvePublic ?: null | stringKey ZMQ_CURVE_PUBLICKEY
Sets the socket's long term public key. You must set this on CURVE client sockets. A server socket does not need to know its own public key. You can create a new keypair with curveKeyPair().
OptionalcurveSecret ?: null | stringKey ZMQ_CURVE_SECRETKEY
Sets the socket's long term secret key. You must set this on both CURVE client and server sockets. You can create a new keypair with curveKeyPair().
OptionalcurveServer ?: booleanZMQ_CURVE_SERVER
Defines whether the socket will act as server for CURVE security. A value of
truemeans the socket will act as CURVE server. A value offalsemeans the socket will not act as CURVE server, and its security role then depends on other option settings.OptionalcurveServer ?: null | stringKey ZMQ_CURVE_SERVERKEY
Sets the socket's long term server key. This is the public key of the CURVE server socket. You must set this on CURVE client sockets. This key must have been generated together with the server's secret key. You can create a new keypair with curveKeyPair().
OptionalgssapiPlain ?: booleanText OptionalgssapiPrincipal ?: null | stringOptionalgssapiPrincipal ?: "hostBased" | "userName" | "krb5Principal"Name Type OptionalgssapiServer ?: booleanOptionalgssapiService ?: null | stringPrincipal OptionalgssapiService ?: "hostBased" | "userName" | "krb5Principal"Principal Name Type OptionalhandshakeInterval ?: numberZMQ_HANDSHAKE_IVL
Handshaking is the exchange of socket configuration information (socket type, identity, security) that occurs when a connection is first opened (only for connection-oriented transports). If handshaking does not complete within the configured time, the connection shall be closed. The value 0 means no handshake time limit.
OptionalheartbeatInterval ?: numberZMQ_HEARTBEAT_IVL
Interval in milliseconds between sending ZMTP heartbeats for the specified socket. If this option is greater than 0, then a PING ZMTP command will be sent after every interval.
OptionalheartbeatTimeout ?: numberZMQ_HEARTBEAT_TIMEOUT
How long (in milliseconds) to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic. This option is only valid if heartbeatInterval is greater than 0. The connection will time out if there is no traffic received after sending the PING command. The received traffic does not have to be a PONG command - any received traffic will cancel the timeout.
OptionalheartbeatTime ?: numberTo Live ZMQ_HEARTBEAT_TTL
The timeout in milliseconds on the remote peer for ZMTP heartbeats. If this option is greater than 0, the remote side shall time out the connection if it does not receive any more traffic within the TTL period. This option does not have any effect if heartbeatInterval is 0. Internally, this value is rounded down to the nearest decisecond, any value less than 100 will have no effect.
Optionalimmediate?: booleanZMQ_IMMEDIATE
By default queues will fill on outgoing connections even if the connection has not completed. This can lead to "lost" messages on sockets with round-robin routing (Request, Push, Dealer). If this option is set to
true, messages shall be queued only to completed connections. This will cause the socket to block if there are no other connections, but will prevent queues from filling on pipes awaiting connection.Optionalinterface?: null | stringZMQ_BINDTODEVICE
Binds the socket to the given network interface (Linux only). Allows to use Linux VRF, see: https://www.kernel.org/doc/Documentation/networking/vrf.txt. Requires the program to be ran as root or with
CAP_NET_RAW.Optionalipv6?: booleanZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
Optionallinger?: numberZMQ_LINGER
Determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with close().
OptionalloopbackFast ?: booleanPath ZMQ_LOOPBACK_FASTPATH
Enable faster TCP connections on loopback devices. An application can enable this option to reduce the latency and improve the performance of loopback operations on a TCP socket on Windows.
OptionalmaxMessage ?: numberSize ZMQ_MAXMSGSIZE
Limits the size of the inbound message. If a peer sends a message larger than the limit it is disconnected. Value of -1 means no limit.
OptionalmulticastHops ?: numberZMQ_MULTICAST_HOPS
Sets the time-to-live field in every multicast packet sent from this socket. The default is 1 which means that the multicast packets don't leave the local network.
OptionalmulticastMax ?: numberTransport Data Unit ZMQ_MULTICAST_MAXTPDU
Sets the maximum transport data unit size used for outbound multicast packets. This must be set at or below the minimum Maximum Transmission Unit (MTU) for all network paths over which multicast reception is required.
OptionalplainPassword ?: null | stringZMQ_PLAIN_PASSWORD
Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
OptionalplainServer ?: booleanZMQ_PLAIN_SERVER
Defines whether the socket will act as server for PLAIN security. A value of
truemeans the socket will act as PLAIN server. A value offalsemeans the socket will not act as PLAIN server, and its security role then depends on other option settings.OptionalplainUsername ?: null | stringZMQ_PLAIN_USERNAME
Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
OptionalprobeRouter ?: booleanZMQ_PROBE_ROUTER
When set to
true, the socket will automatically send an empty message when a new connection is made or accepted. You may set this on sockets connected to a Router socket. The application must filter such empty messages. This option provides the Router with an event signaling the arrival of a new peer.Warning:* Do not set this option on a socket that talks to any other socket type except Router: the results are undefined.
Optionalrate?: numberZMQ_RATE
Maximum send or receive data rate for multicast transports such as
pgm.OptionalreceiveBuffer ?: numberSize ZMQ_RCVBUF
Underlying kernel receive buffer size in bytes. A value of -1 means leave the OS default unchanged.
OptionalreceiveHigh ?: numberWater Mark ZMQ_RCVHWM
The high water mark is a hard limit on the maximum number of incoming messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
OptionalreceiveTimeout ?: numberZMQ_RCVTIMEO
Sets the timeout receiving messages on the socket. If the value is 0, receive() will return a rejected promise immediately if there is no message to receive. If the value is -1, it will wait asynchronously until a message is available. For all other values, it will wait for a message for that amount of time before rejecting.
OptionalreconnectInterval ?: numberZMQ_RECONNECT_IVL
Period ØMQ shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. The value -1 means no reconnection.
OptionalreconnectMax ?: numberInterval ZMQ_RECONNECT_IVL_MAX
Maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled until reconnectMaxInterval is reached. This allows for exponential backoff strategy. Zero (the default) means no exponential backoff is performed and reconnect interval calculations are only based on reconnectInterval.
OptionalrecoveryInterval ?: numberZMQ_RECOVERY_IVL
Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
Optionalrelaxed?: booleanZMQ_REQ_RELAXED
By default, a Request socket does not allow initiating a new request until the reply to the previous one has been received. When set to
true, sending another message is allowed and previous replies will be discarded. The request-reply state machine is reset and a new request is sent to the next available peer.Note: If set to
true, also enable correlate to ensure correct matching of requests and replies. Otherwise a late reply to an aborted request can be reported as the reply to the superseding request.OptionalroutingId ?: null | stringZMQ_ROUTING_ID
The identity of the specified socket when connecting to a
Routersocket.OptionalsendBuffer ?: numberSize ZMQ_SNDBUF
Underlying kernel transmit buffer size in bytes. A value of -1 means leave the OS default unchanged.
OptionalsendHigh ?: numberWater Mark ZMQ_SNDHWM
The high water mark is a hard limit on the maximum number of outgoing messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
OptionalsendTimeout ?: numberZMQ_SNDTIMEO
Sets the timeout for sending messages on the socket. If the value is 0, send() will return a rejected promise immediately if the message cannot be sent. If the value is -1, it will wait asynchronously until the message is sent. For all other values, it will try to send the message for that amount of time before rejecting.
OptionalsocksProxy ?: null | stringZMQ_SOCKS_PROXY
The SOCKS5 proxy address that shall be used by the socket for the TCP connection(s). Does not support SOCKS5 authentication. If the endpoints are domain names instead of addresses they shall not be resolved and they shall be forwarded unchanged to the SOCKS proxy service in the client connection request message (address type 0x03 domain name).
OptionaltcpAccept ?: null | stringFilter ZMQ_TCP_ACCEPT_FILTER
Assign a filter that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one filter is applied then new connection source IP should be matched. To clear all filters set to
null. Filter is a string with IPv6 or IPv4 CIDR.OptionaltcpKeepalive ?: numberZMQ_TCP_KEEPALIVE
Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepalive ?: numberCount ZMQ_TCP_KEEPALIVE_CNT
Overrides TCP_KEEPCNT socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepalive ?: numberIdle ZMQ_TCP_KEEPALIVE_IDLE
Overrides TCP_KEEPIDLE / TCP_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepalive ?: numberInterval ZMQ_TCP_KEEPALIVE_INTVL
Overrides TCP_KEEPINTVL socket option (if supported by the OS). The default value of -1 leaves it to the OS default.
OptionaltcpMax ?: numberRetransmit Timeout ZMQ_TCP_MAXRT
Sets how long before an unacknowledged TCP retransmit times out (if supported by the OS). The system normally attempts many TCP retransmits following an exponential backoff strategy. This means that after a network outage, it may take a long time before the session can be re-established. Setting this option allows the timeout to happen at a shorter interval.
OptionaltypeOf ?: numberService ZMQ_TOS
Sets the ToS fields (the Differentiated Services (DS) and Explicit Congestion Notification (ECN) field) of the IP header. The ToS field is typically used to specify a packet's priority. The availability of this option is dependent on intermediate network equipment that inspect the ToS field and provide a path for low-delay, high-throughput, highly-reliable service, etc.
OptionalvmciBuffer ?: numberMax Size ZMQ_VMCI_BUFFER_MAX_SIZE
Maximum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciBuffer ?: numberMin Size ZMQ_VMCI_BUFFER_MIN_SIZE
Minimum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciBuffer ?: numberSize ZMQ_VMCI_BUFFER_SIZE
The size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciConnect ?: numberTimeout ZMQ_VMCI_CONNECT_TIMEOUT
Connection timeout for the socket. For
vmci://transports only.OptionalzapDomain ?: null | stringZMQ_ZAP_DOMAIN
Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the default on all
tcp://connections), ZAP authentication only happens if you set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 for more details.OptionalzapEnforce ?: booleanDomain ZMQ_ZAP_ENFORCE_DOMAIN
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.
Returns Request
Properties
affinity
ZMQ_AFFINITY
I/O thread affinity, which determines which threads from the ØMQ I/O thread pool associated with the socket's context shall handle newly created connections.
Note: This value is a bit mask, but values higher than Number.MAX_SAFE_INTEGER may not be represented accurately! This currently means that configurations beyond 52 threads are unreliable.
backlog
ZMQ_BACKLOG
Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.
Readonlyclosed
Whether this socket was previously closed with close().
connectTimeout
ZMQ_CONNECT_TIMEOUT
Sets how long to wait before timing-out a connect() system call. The connect() system call normally takes a long time before it returns a time out error. Setting this option allows the library to time out the call at an earlier interval.
Readonlycontext
Context that this socket belongs to.
correlate
ZMQ_REQ_CORRELATE
The default behaviour of Request sockets is to rely on the ordering of messages to match requests and responses and that is usually sufficient. When this option is set to true the socket will prefix outgoing messages with an extra frame containing a request id. That means the full message is [<request id>,null, user frames…]. The Request socket will discard all incoming messages that don't begin with these two frames.
curvePublicKey
ZMQ_CURVE_PUBLICKEY
Sets the socket's long term public key. You must set this on CURVE client sockets. A server socket does not need to know its own public key. You can create a new keypair with curveKeyPair().
curveSecretKey
ZMQ_CURVE_SECRETKEY
Sets the socket's long term secret key. You must set this on both CURVE client and server sockets. You can create a new keypair with curveKeyPair().
curveServer
ZMQ_CURVE_SERVER
Defines whether the socket will act as server for CURVE security. A value of true means the socket will act as CURVE server. A value of false means the socket will not act as CURVE server, and its security role then depends on other option settings.
curveServerKey
ZMQ_CURVE_SERVERKEY
Sets the socket's long term server key. This is the public key of the CURVE server socket. You must set this on CURVE client sockets. This key must have been generated together with the server's secret key. You can create a new keypair with curveKeyPair().
Readonlyevents
Event Observer for this socket. This starts up a ØMQ monitoring socket internally that receives all socket events.
gssapiPlainText
gssapiPrincipal
gssapiPrincipalNameType
gssapiServer
gssapiServicePrincipal
gssapiServicePrincipalNameType
handshakeInterval
ZMQ_HANDSHAKE_IVL
Handshaking is the exchange of socket configuration information (socket type, identity, security) that occurs when a connection is first opened (only for connection-oriented transports). If handshaking does not complete within the configured time, the connection shall be closed. The value 0 means no handshake time limit.
heartbeatInterval
ZMQ_HEARTBEAT_IVL
Interval in milliseconds between sending ZMTP heartbeats for the specified socket. If this option is greater than 0, then a PING ZMTP command will be sent after every interval.
heartbeatTimeout
ZMQ_HEARTBEAT_TIMEOUT
How long (in milliseconds) to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic. This option is only valid if heartbeatInterval is greater than 0. The connection will time out if there is no traffic received after sending the PING command. The received traffic does not have to be a PONG command - any received traffic will cancel the timeout.
heartbeatTimeToLive
ZMQ_HEARTBEAT_TTL
The timeout in milliseconds on the remote peer for ZMTP heartbeats. If this option is greater than 0, the remote side shall time out the connection if it does not receive any more traffic within the TTL period. This option does not have any effect if heartbeatInterval is 0. Internally, this value is rounded down to the nearest decisecond, any value less than 100 will have no effect.
immediate
ZMQ_IMMEDIATE
By default queues will fill on outgoing connections even if the connection has not completed. This can lead to "lost" messages on sockets with round-robin routing (Request, Push, Dealer). If this option is set to true, messages shall be queued only to completed connections. This will cause the socket to block if there are no other connections, but will prevent queues from filling on pipes awaiting connection.
interface
ZMQ_BINDTODEVICE
Binds the socket to the given network interface (Linux only). Allows to use Linux VRF, see: https://www.kernel.org/doc/Documentation/networking/vrf.txt. Requires the program to be ran as root or with CAP_NET_RAW.
ipv6
ZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
ReadonlylastEndpoint
ZMQ_LAST_ENDPOINT
The last endpoint bound for TCP and IPC transports.
linger
ZMQ_LINGER
Determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with close().
loopbackFastPath
ZMQ_LOOPBACK_FASTPATH
Enable faster TCP connections on loopback devices. An application can enable this option to reduce the latency and improve the performance of loopback operations on a TCP socket on Windows.
maxMessageSize
ZMQ_MAXMSGSIZE
Limits the size of the inbound message. If a peer sends a message larger than the limit it is disconnected. Value of -1 means no limit.
multicastHops
ZMQ_MULTICAST_HOPS
Sets the time-to-live field in every multicast packet sent from this socket. The default is 1 which means that the multicast packets don't leave the local network.
multicastMaxTransportDataUnit
ZMQ_MULTICAST_MAXTPDU
Sets the maximum transport data unit size used for outbound multicast packets. This must be set at or below the minimum Maximum Transmission Unit (MTU) for all network paths over which multicast reception is required.
plainPassword
ZMQ_PLAIN_PASSWORD
Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
plainServer
ZMQ_PLAIN_SERVER
Defines whether the socket will act as server for PLAIN security. A value of true means the socket will act as PLAIN server. A value of false means the socket will not act as PLAIN server, and its security role then depends on other option settings.
plainUsername
ZMQ_PLAIN_USERNAME
Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
probeRouter
ZMQ_PROBE_ROUTER
When set to true, the socket will automatically send an empty message when a new connection is made or accepted. You may set this on sockets connected to a Router socket. The application must filter such empty messages. This option provides the Router with an event signaling the arrival of a new peer.
Warning:* Do not set this option on a socket that talks to any other socket type except Router: the results are undefined.
rate
ZMQ_RATE
Maximum send or receive data rate for multicast transports such as pgm.
Readonlyreadable
Whether any messages are currently available. If true, the next call to Readable.receive() will immediately read a message from the socket. For sockets that cannot receive messsages this is always false.
receiveBufferSize
ZMQ_RCVBUF
Underlying kernel receive buffer size in bytes. A value of -1 means leave the OS default unchanged.
receiveHighWaterMark
ZMQ_RCVHWM
The high water mark is a hard limit on the maximum number of incoming messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
receiveTimeout
ZMQ_RCVTIMEO
Sets the timeout receiving messages on the socket. If the value is 0, receive() will return a rejected promise immediately if there is no message to receive. If the value is -1, it will wait asynchronously until a message is available. For all other values, it will wait for a message for that amount of time before rejecting.
reconnectInterval
ZMQ_RECONNECT_IVL
Period ØMQ shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. The value -1 means no reconnection.
reconnectMaxInterval
ZMQ_RECONNECT_IVL_MAX
Maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled until reconnectMaxInterval is reached. This allows for exponential backoff strategy. Zero (the default) means no exponential backoff is performed and reconnect interval calculations are only based on reconnectInterval.
recoveryInterval
ZMQ_RECOVERY_IVL
Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
relaxed
ZMQ_REQ_RELAXED
By default, a Request socket does not allow initiating a new request until the reply to the previous one has been received. When set to true, sending another message is allowed and previous replies will be discarded. The request-reply state machine is reset and a new request is sent to the next available peer.
Note: If set to true, also enable correlate to ensure correct matching of requests and replies. Otherwise a late reply to an aborted request can be reported as the reply to the superseding request.
routingId
ZMQ_ROUTING_ID
The identity of the specified socket when connecting to a Router socket.
ReadonlysecurityMechanism
| null
| "plain"
| "curve"
| "gssapi"
ZMQ_MECHANISM
Returns the current security mechanism for the socket, if any. The security mechanism is set implictly by using any of the relevant security options. The returned value is one of:
null- No security mechanism is used."plain"- The PLAIN mechanism defines a simple username/password mechanism that lets a server authenticate a client. PLAIN makes no attempt at security or confidentiality."curve"- The CURVE mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server. CURVE is intended for use on public networks."gssapi"- The GSSAPI mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server using the Generic Security Service Application Program Interface (GSSAPI). The GSSAPI mechanism can be used on both public and private networks.
sendBufferSize
ZMQ_SNDBUF
Underlying kernel transmit buffer size in bytes. A value of -1 means leave the OS default unchanged.
sendHighWaterMark
ZMQ_SNDHWM
The high water mark is a hard limit on the maximum number of outgoing messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
sendTimeout
ZMQ_SNDTIMEO
Sets the timeout for sending messages on the socket. If the value is 0, send() will return a rejected promise immediately if the message cannot be sent. If the value is -1, it will wait asynchronously until the message is sent. For all other values, it will try to send the message for that amount of time before rejecting.
socksProxy
ZMQ_SOCKS_PROXY
The SOCKS5 proxy address that shall be used by the socket for the TCP connection(s). Does not support SOCKS5 authentication. If the endpoints are domain names instead of addresses they shall not be resolved and they shall be forwarded unchanged to the SOCKS proxy service in the client connection request message (address type 0x03 domain name).
tcpAcceptFilter
ZMQ_TCP_ACCEPT_FILTER
Assign a filter that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one filter is applied then new connection source IP should be matched. To clear all filters set to null. Filter is a string with IPv6 or IPv4 CIDR.
tcpKeepalive
ZMQ_TCP_KEEPALIVE
Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveCount
ZMQ_TCP_KEEPALIVE_CNT
Overrides TCP_KEEPCNT socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveIdle
ZMQ_TCP_KEEPALIVE_IDLE
Overrides TCP_KEEPIDLE / TCP_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveInterval
ZMQ_TCP_KEEPALIVE_INTVL
Overrides TCP_KEEPINTVL socket option (if supported by the OS). The default value of -1 leaves it to the OS default.
tcpMaxRetransmitTimeout
ZMQ_TCP_MAXRT
Sets how long before an unacknowledged TCP retransmit times out (if supported by the OS). The system normally attempts many TCP retransmits following an exponential backoff strategy. This means that after a network outage, it may take a long time before the session can be re-established. Setting this option allows the timeout to happen at a shorter interval.
ReadonlythreadSafe
ZMQ_THREAD_SAFE
Whether or not the socket is threadsafe. Currently only DRAFT sockets is thread-safe.
Readonlytype
ZMQ_TYPE
Retrieve the socket type. This is fairly useless because you can test the socket class with e.g. socket instanceof Dealer.
typeOfService
ZMQ_TOS
Sets the ToS fields (the Differentiated Services (DS) and Explicit Congestion Notification (ECN) field) of the IP header. The ToS field is typically used to specify a packet's priority. The availability of this option is dependent on intermediate network equipment that inspect the ToS field and provide a path for low-delay, high-throughput, highly-reliable service, etc.
vmciBufferMaxSize
ZMQ_VMCI_BUFFER_MAX_SIZE
Maximum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferMinSize
ZMQ_VMCI_BUFFER_MIN_SIZE
Minimum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferSize
ZMQ_VMCI_BUFFER_SIZE
The size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciConnectTimeout
ZMQ_VMCI_CONNECT_TIMEOUT
Connection timeout for the socket. For vmci:// transports only.
Readonlywritable
Whether any messages can be queued for sending. If true, the next call to Writable.send() will immediately queue a message on the socket. For sockets that cannot send messsages this is always false.
zapDomain
ZMQ_ZAP_DOMAIN
Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the default on all tcp:// connections), ZAP authentication only happens if you set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 for more details.
zapEnforceDomain
ZMQ_ZAP_ENFORCE_DOMAIN
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.
Methods
[asyncIterator]
- [async
Iterator] (): AsyncIterator<Buffer[], undefined, undefined> Asynchronously iterate over messages becoming available on the socket. When the socket is closed with Socket.close(), the iterator will return. Returning early from the iterator will not close the socket unless it also goes out of scope.
for await (const [msg] of socket) {
// handle messages
} -Returns AsyncIterator<Buffer[], undefined, undefined>
bind
- bind(address): Promise<void>
Binds the socket to the given address. During bind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.You can use
*in place of a hostname to bind on all interfaces/addresses, and you can use*in place of a port to bind to a random port (which can be retrieved with lastEndpoint later).await socket.bind("tcp://127.0.0.1:3456")
await socket.bind("tcp://*:3456") // binds on all interfaces
await socket.bind("tcp://127.0.0.1:*") // binds on random port -Parameters
- address: string
Address to bind this socket to.
Returns Promise<void>
Resolved when the socket was successfully bound.
- address: string
close
- close(): void
Closes the socket and disposes of all resources. Any messages that are queued may be discarded or sent in the background depending on the linger setting.
After this method is called, it is no longer possible to call any other methods on this socket.
Sockets that go out of scope and have no Readable.receive() or Writable.send() operations in progress will automatically be closed. Therefore it is not necessary in most applications to call close() manually.
Calling this method on a socket that is already closed is a no-op.
Returns void
connect
disconnect
- disconnect(address): void
Disconnects a previously connected socket from the given address and returns immediately. Disonnection will happen asynchronously in the background.
socket.disconnect("tcp://127.0.0.1:3456") -Parameters
- address: string
The previously connected address to disconnect from.
Returns void
- address: string
ProtectedgetBoolOption
ProtectedgetInt32Option
ProtectedgetInt64Option
ProtectedgetStringOption
ProtectedgetUint32Option
ProtectedgetUint64Option
receive
- receive(): Promise<Buffer[]>
Waits for the next single or multipart message to become availeble on the socket. Reads a message immediately if possible. If no messages can be read, it will wait asynchonously. The promise will be resolved with an array containing the parts of the next message when available.
const [msg] = await socket.receive()
const [part1, part2] = await socket.receive() -Reading may fail (eventually) if the socket has been configured with a receiveTimeout.
A call to receive() is guaranteed to return with a resolved promise immediately if a message could be read from the socket directly.
Only one asynchronously blocking call to receive() can be in progress simultaneously. If you call receive() again on the same socket it will return a rejected promise with an
EBUSYerror. For example, if no messages can be read and noawaitis used:socket.receive() // -> pending promise until read is possible
socket.receive() // -> promise rejection with `EBUSY` error -Note: Due to the nature of Node.js and to avoid blocking the main thread, this method always attempts to read messages with the
ZMQ_DONTWAITflag. It polls asynchronously if reading is not currently possible. This means that all functionality related to timeouts and blocking behaviour is reimplemented in the Node.js bindings. Any differences in behaviour with the native ZMQ library is considered a bug.Returns Promise<Buffer[]>
Resolved with message parts that were successfully read.
send
- send(message, ...options): Promise<void>
Sends a single message or a multipart message on the socket. Queues the message immediately if possible, and returns a resolved promise. If the message cannot be queued because the high water mark has been reached, it will wait asynchronously. The promise will be resolved when the message was queued successfully.
await socket.send("hello world")
await socket.send(["hello", "world"]) -Queueing may fail eventually if the socket has been configured with a sendTimeout.
A call to send() is guaranteed to return with a resolved promise immediately if the message could be queued directly.
Only one asynchronously blocking call to send() may be executed simultaneously. If you call send() again on a socket that is in the mute state it will return a rejected promise with an
EBUSYerror.The reason for disallowing multiple send() calls simultaneously is that it could create an implicit queue of unsendable outgoing messages. This would circumvent the socket's sendHighWaterMark. Such an implementation could even exhaust all system memory and cause the Node.js process to abort.
For most application you should not notice this implementation detail. Only in rare occasions will a call to send() that does not resolve immediately be undesired. Here are some common scenarios:
If you wish to send a message, use
await send(...). ZeroMQ socket types have been carefully designed to give you the correct blocking behaviour on the chosen socket type in almost all cases:If sending is not possible, it is often better to wait than to continue as if nothing happened. For example, on a Request socket, you can only receive a reply once a message has been sent; so waiting until a message could be queued before continuing with the rest of the program (likely to read from the socket) is required.
Certain socket types (such as Router) will always allow queueing messages and
await send(...)won't delay any code that comes after. This makes sense for routers, since typically you don't want a single send operation to stop the handling of other incoming or outgoing messages.
If you wish to send on an occasionally blocking socket (for example on a Router with the Router.mandatory option set, or on a Dealer) and you're 100% certain that dropping a message is better than blocking, then you can set the sendTimeout option to
0to effectively force send() to always resolve immediately. Be prepared to catch exceptions if sending a message is not immediately possible.If you wish to send on a socket and messages should be queued before they are dropped, you should implement a simple queue in JavaScript. Such a queue is not provided by this library because most real world applications need to deal with undeliverable messages in more complex ways - for example, they might need to reply with a status message; or first retry delivery a certain number of times before giving up.
Parameters
- message: MessageLike | MessageLike[]
Single message or multipart message to queue for sending.
Rest...options: []Any options, if applicable to the socket type (DRAFT only).
Returns Promise<void>
Resolved when the message was successfully queued.
ProtectedsetBoolOption
ProtectedsetInt32Option
ProtectedsetInt64Option
ProtectedsetStringOption
ProtectedsetUint32Option
ProtectedsetUint64Option
unbind
- unbind(address): Promise<void>
Unbinds the socket to the given address. During unbind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.Parameters
- address: string
Address to unbind this socket from.
Returns Promise<void>
Resolved when the socket was successfully unbound.
- address: string
Class Request
A Request socket acts as a client to send requests to and receive replies from a Reply socket. This socket allows only an alternating sequence of Writable.send() and subsequent Readable.receive() calls. Each request sent is round-robined among all services, and each reply received is matched with the last issued request.
If no services are available, then any send operation on the socket shall block until at least one service becomes available. The REQ socket shall not discard messages.
Hierarchy (View Summary)
Index
Constructors
Properties
Methods
Constructors
constructor
- new Request(
options?: {
affinity?: number;
backlog?: number;
connectTimeout?: number;
context?: Context;
correlate?: boolean;
curvePublicKey?: null | string;
curveSecretKey?: null | string;
curveServer?: boolean;
curveServerKey?: null | string;
gssapiPlainText?: boolean;
gssapiPrincipal?: null | string;
gssapiPrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
gssapiServer?: boolean;
gssapiServicePrincipal?: null | string;
gssapiServicePrincipalNameType?:
| "hostBased"
| "userName"
| "krb5Principal";
handshakeInterval?: number;
heartbeatInterval?: number;
heartbeatTimeout?: number;
heartbeatTimeToLive?: number;
immediate?: boolean;
interface?: null
| string;
ipv6?: boolean;
linger?: number;
loopbackFastPath?: boolean;
maxMessageSize?: number;
multicastHops?: number;
multicastMaxTransportDataUnit?: number;
plainPassword?: null | string;
plainServer?: boolean;
plainUsername?: null | string;
probeRouter?: boolean;
rate?: number;
receiveBufferSize?: number;
receiveHighWaterMark?: number;
receiveTimeout?: number;
reconnectInterval?: number;
reconnectMaxInterval?: number;
recoveryInterval?: number;
relaxed?: boolean;
routingId?: null | string;
sendBufferSize?: number;
sendHighWaterMark?: number;
sendTimeout?: number;
socksProxy?: null | string;
tcpAcceptFilter?: null | string;
tcpKeepalive?: number;
tcpKeepaliveCount?: number;
tcpKeepaliveIdle?: number;
tcpKeepaliveInterval?: number;
tcpMaxRetransmitTimeout?: number;
typeOfService?: number;
vmciBufferMaxSize?: number;
vmciBufferMinSize?: number;
vmciBufferSize?: number;
vmciConnectTimeout?: number;
zapDomain?: null | string;
zapEnforceDomain?: boolean;
},
): Request Parameters
Optionaloptions: {
affinity?: number;
backlog?: number;
connectTimeout?: number;
context?: Context;
correlate?: boolean;
curvePublicKey?: null | string;
curveSecretKey?: null | string;
curveServer?: boolean;
curveServerKey?: null | string;
gssapiPlainText?: boolean;
gssapiPrincipal?: null | string;
gssapiPrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
gssapiServer?: boolean;
gssapiServicePrincipal?: null | string;
gssapiServicePrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
handshakeInterval?: number;
heartbeatInterval?: number;
heartbeatTimeout?: number;
heartbeatTimeToLive?: number;
immediate?: boolean;
interface?: null | string;
ipv6?: boolean;
linger?: number;
loopbackFastPath?: boolean;
maxMessageSize?: number;
multicastHops?: number;
multicastMaxTransportDataUnit?: number;
plainPassword?: null | string;
plainServer?: boolean;
plainUsername?: null | string;
probeRouter?: boolean;
rate?: number;
receiveBufferSize?: number;
receiveHighWaterMark?: number;
receiveTimeout?: number;
reconnectInterval?: number;
reconnectMaxInterval?: number;
recoveryInterval?: number;
relaxed?: boolean;
routingId?: null | string;
sendBufferSize?: number;
sendHighWaterMark?: number;
sendTimeout?: number;
socksProxy?: null | string;
tcpAcceptFilter?: null | string;
tcpKeepalive?: number;
tcpKeepaliveCount?: number;
tcpKeepaliveIdle?: number;
tcpKeepaliveInterval?: number;
tcpMaxRetransmitTimeout?: number;
typeOfService?: number;
vmciBufferMaxSize?: number;
vmciBufferMinSize?: number;
vmciBufferSize?: number;
vmciConnectTimeout?: number;
zapDomain?: null | string;
zapEnforceDomain?: boolean;
}Optionalaffinity?: numberZMQ_AFFINITY
I/O thread affinity, which determines which threads from the ØMQ I/O thread pool associated with the socket's context shall handle newly created connections.
Note: This value is a bit mask, but values higher than
Number.MAX_SAFE_INTEGERmay not be represented accurately! This currently means that configurations beyond 52 threads are unreliable.Optionalbacklog?: numberZMQ_BACKLOG
Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.
OptionalconnectTimeout?: numberZMQ_CONNECT_TIMEOUT
Sets how long to wait before timing-out a connect() system call. The connect() system call normally takes a long time before it returns a time out error. Setting this option allows the library to time out the call at an earlier interval.
Optionalcontext?: ContextOptionalcorrelate?: booleanZMQ_REQ_CORRELATE
The default behaviour of Request sockets is to rely on the ordering of messages to match requests and responses and that is usually sufficient. When this option is set to
truethe socket will prefix outgoing messages with an extra frame containing a request id. That means the full message is[<request id>,null, user frames…]. The Request socket will discard all incoming messages that don't begin with these two frames.OptionalcurvePublicKey?: null | stringZMQ_CURVE_PUBLICKEY
Sets the socket's long term public key. You must set this on CURVE client sockets. A server socket does not need to know its own public key. You can create a new keypair with curveKeyPair().
OptionalcurveSecretKey?: null | stringZMQ_CURVE_SECRETKEY
Sets the socket's long term secret key. You must set this on both CURVE client and server sockets. You can create a new keypair with curveKeyPair().
OptionalcurveServer?: booleanZMQ_CURVE_SERVER
Defines whether the socket will act as server for CURVE security. A value of
truemeans the socket will act as CURVE server. A value offalsemeans the socket will not act as CURVE server, and its security role then depends on other option settings.OptionalcurveServerKey?: null | stringZMQ_CURVE_SERVERKEY
Sets the socket's long term server key. This is the public key of the CURVE server socket. You must set this on CURVE client sockets. This key must have been generated together with the server's secret key. You can create a new keypair with curveKeyPair().
OptionalgssapiPlainText?: booleanOptionalgssapiPrincipal?: null | stringOptionalgssapiPrincipalNameType?: "hostBased" | "userName" | "krb5Principal"OptionalgssapiServer?: booleanOptionalgssapiServicePrincipal?: null | stringOptionalgssapiServicePrincipalNameType?: "hostBased" | "userName" | "krb5Principal"OptionalhandshakeInterval?: numberZMQ_HANDSHAKE_IVL
Handshaking is the exchange of socket configuration information (socket type, identity, security) that occurs when a connection is first opened (only for connection-oriented transports). If handshaking does not complete within the configured time, the connection shall be closed. The value 0 means no handshake time limit.
OptionalheartbeatInterval?: numberZMQ_HEARTBEAT_IVL
Interval in milliseconds between sending ZMTP heartbeats for the specified socket. If this option is greater than 0, then a PING ZMTP command will be sent after every interval.
OptionalheartbeatTimeout?: numberZMQ_HEARTBEAT_TIMEOUT
How long (in milliseconds) to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic. This option is only valid if heartbeatInterval is greater than 0. The connection will time out if there is no traffic received after sending the PING command. The received traffic does not have to be a PONG command - any received traffic will cancel the timeout.
OptionalheartbeatTimeToLive?: numberZMQ_HEARTBEAT_TTL
The timeout in milliseconds on the remote peer for ZMTP heartbeats. If this option is greater than 0, the remote side shall time out the connection if it does not receive any more traffic within the TTL period. This option does not have any effect if heartbeatInterval is 0. Internally, this value is rounded down to the nearest decisecond, any value less than 100 will have no effect.
Optionalimmediate?: booleanZMQ_IMMEDIATE
By default queues will fill on outgoing connections even if the connection has not completed. This can lead to "lost" messages on sockets with round-robin routing (Request, Push, Dealer). If this option is set to
true, messages shall be queued only to completed connections. This will cause the socket to block if there are no other connections, but will prevent queues from filling on pipes awaiting connection.Optionalinterface?: null | stringZMQ_BINDTODEVICE
Binds the socket to the given network interface (Linux only). Allows to use Linux VRF, see: https://www.kernel.org/doc/Documentation/networking/vrf.txt. Requires the program to be ran as root or with
CAP_NET_RAW.Optionalipv6?: booleanZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
Optionallinger?: numberZMQ_LINGER
Determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with close().
OptionalloopbackFastPath?: booleanZMQ_LOOPBACK_FASTPATH
Enable faster TCP connections on loopback devices. An application can enable this option to reduce the latency and improve the performance of loopback operations on a TCP socket on Windows.
OptionalmaxMessageSize?: numberZMQ_MAXMSGSIZE
Limits the size of the inbound message. If a peer sends a message larger than the limit it is disconnected. Value of -1 means no limit.
OptionalmulticastHops?: numberZMQ_MULTICAST_HOPS
Sets the time-to-live field in every multicast packet sent from this socket. The default is 1 which means that the multicast packets don't leave the local network.
OptionalmulticastMaxTransportDataUnit?: numberZMQ_MULTICAST_MAXTPDU
Sets the maximum transport data unit size used for outbound multicast packets. This must be set at or below the minimum Maximum Transmission Unit (MTU) for all network paths over which multicast reception is required.
OptionalplainPassword?: null | stringZMQ_PLAIN_PASSWORD
Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
OptionalplainServer?: booleanZMQ_PLAIN_SERVER
Defines whether the socket will act as server for PLAIN security. A value of
truemeans the socket will act as PLAIN server. A value offalsemeans the socket will not act as PLAIN server, and its security role then depends on other option settings.OptionalplainUsername?: null | stringZMQ_PLAIN_USERNAME
Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
OptionalprobeRouter?: booleanZMQ_PROBE_ROUTER
When set to
true, the socket will automatically send an empty message when a new connection is made or accepted. You may set this on sockets connected to a Router socket. The application must filter such empty messages. This option provides the Router with an event signaling the arrival of a new peer.Warning:* Do not set this option on a socket that talks to any other socket type except Router: the results are undefined.
Optionalrate?: numberZMQ_RATE
Maximum send or receive data rate for multicast transports such as
pgm.OptionalreceiveBufferSize?: numberZMQ_RCVBUF
Underlying kernel receive buffer size in bytes. A value of -1 means leave the OS default unchanged.
OptionalreceiveHighWaterMark?: numberZMQ_RCVHWM
The high water mark is a hard limit on the maximum number of incoming messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
OptionalreceiveTimeout?: numberZMQ_RCVTIMEO
Sets the timeout receiving messages on the socket. If the value is 0, receive() will return a rejected promise immediately if there is no message to receive. If the value is -1, it will wait asynchronously until a message is available. For all other values, it will wait for a message for that amount of time before rejecting.
OptionalreconnectInterval?: numberZMQ_RECONNECT_IVL
Period ØMQ shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. The value -1 means no reconnection.
OptionalreconnectMaxInterval?: numberZMQ_RECONNECT_IVL_MAX
Maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled until reconnectMaxInterval is reached. This allows for exponential backoff strategy. Zero (the default) means no exponential backoff is performed and reconnect interval calculations are only based on reconnectInterval.
OptionalrecoveryInterval?: numberZMQ_RECOVERY_IVL
Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
Optionalrelaxed?: booleanZMQ_REQ_RELAXED
By default, a Request socket does not allow initiating a new request until the reply to the previous one has been received. When set to
true, sending another message is allowed and previous replies will be discarded. The request-reply state machine is reset and a new request is sent to the next available peer.Note: If set to
true, also enable correlate to ensure correct matching of requests and replies. Otherwise a late reply to an aborted request can be reported as the reply to the superseding request.OptionalroutingId?: null | stringZMQ_ROUTING_ID
The identity of the specified socket when connecting to a
Routersocket.OptionalsendBufferSize?: numberZMQ_SNDBUF
Underlying kernel transmit buffer size in bytes. A value of -1 means leave the OS default unchanged.
OptionalsendHighWaterMark?: numberZMQ_SNDHWM
The high water mark is a hard limit on the maximum number of outgoing messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
OptionalsendTimeout?: numberZMQ_SNDTIMEO
Sets the timeout for sending messages on the socket. If the value is 0, send() will return a rejected promise immediately if the message cannot be sent. If the value is -1, it will wait asynchronously until the message is sent. For all other values, it will try to send the message for that amount of time before rejecting.
OptionalsocksProxy?: null | stringZMQ_SOCKS_PROXY
The SOCKS5 proxy address that shall be used by the socket for the TCP connection(s). Does not support SOCKS5 authentication. If the endpoints are domain names instead of addresses they shall not be resolved and they shall be forwarded unchanged to the SOCKS proxy service in the client connection request message (address type 0x03 domain name).
OptionaltcpAcceptFilter?: null | stringZMQ_TCP_ACCEPT_FILTER
Assign a filter that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one filter is applied then new connection source IP should be matched. To clear all filters set to
null. Filter is a string with IPv6 or IPv4 CIDR.OptionaltcpKeepalive?: numberZMQ_TCP_KEEPALIVE
Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepaliveCount?: numberZMQ_TCP_KEEPALIVE_CNT
Overrides TCP_KEEPCNT socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepaliveIdle?: numberZMQ_TCP_KEEPALIVE_IDLE
Overrides TCP_KEEPIDLE / TCP_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepaliveInterval?: numberZMQ_TCP_KEEPALIVE_INTVL
Overrides TCP_KEEPINTVL socket option (if supported by the OS). The default value of -1 leaves it to the OS default.
OptionaltcpMaxRetransmitTimeout?: numberZMQ_TCP_MAXRT
Sets how long before an unacknowledged TCP retransmit times out (if supported by the OS). The system normally attempts many TCP retransmits following an exponential backoff strategy. This means that after a network outage, it may take a long time before the session can be re-established. Setting this option allows the timeout to happen at a shorter interval.
OptionaltypeOfService?: numberZMQ_TOS
Sets the ToS fields (the Differentiated Services (DS) and Explicit Congestion Notification (ECN) field) of the IP header. The ToS field is typically used to specify a packet's priority. The availability of this option is dependent on intermediate network equipment that inspect the ToS field and provide a path for low-delay, high-throughput, highly-reliable service, etc.
OptionalvmciBufferMaxSize?: numberZMQ_VMCI_BUFFER_MAX_SIZE
Maximum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciBufferMinSize?: numberZMQ_VMCI_BUFFER_MIN_SIZE
Minimum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciBufferSize?: numberZMQ_VMCI_BUFFER_SIZE
The size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciConnectTimeout?: numberZMQ_VMCI_CONNECT_TIMEOUT
Connection timeout for the socket. For
vmci://transports only.OptionalzapDomain?: null | stringZMQ_ZAP_DOMAIN
Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the default on all
tcp://connections), ZAP authentication only happens if you set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 for more details.OptionalzapEnforceDomain?: booleanZMQ_ZAP_ENFORCE_DOMAIN
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.
Returns Request
Properties
affinity
ZMQ_AFFINITY
I/O thread affinity, which determines which threads from the ØMQ I/O thread pool associated with the socket's context shall handle newly created connections.
Note: This value is a bit mask, but values higher than Number.MAX_SAFE_INTEGER may not be represented accurately! This currently means that configurations beyond 52 threads are unreliable.
backlog
ZMQ_BACKLOG
Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.
Readonlyclosed
Whether this socket was previously closed with close().
connectTimeout
ZMQ_CONNECT_TIMEOUT
Sets how long to wait before timing-out a connect() system call. The connect() system call normally takes a long time before it returns a time out error. Setting this option allows the library to time out the call at an earlier interval.
Readonlycontext
Context that this socket belongs to.
correlate
ZMQ_REQ_CORRELATE
The default behaviour of Request sockets is to rely on the ordering of messages to match requests and responses and that is usually sufficient. When this option is set to true the socket will prefix outgoing messages with an extra frame containing a request id. That means the full message is [<request id>,null, user frames…]. The Request socket will discard all incoming messages that don't begin with these two frames.
curvePublicKey
ZMQ_CURVE_PUBLICKEY
Sets the socket's long term public key. You must set this on CURVE client sockets. A server socket does not need to know its own public key. You can create a new keypair with curveKeyPair().
curveSecretKey
ZMQ_CURVE_SECRETKEY
Sets the socket's long term secret key. You must set this on both CURVE client and server sockets. You can create a new keypair with curveKeyPair().
curveServer
ZMQ_CURVE_SERVER
Defines whether the socket will act as server for CURVE security. A value of true means the socket will act as CURVE server. A value of false means the socket will not act as CURVE server, and its security role then depends on other option settings.
curveServerKey
ZMQ_CURVE_SERVERKEY
Sets the socket's long term server key. This is the public key of the CURVE server socket. You must set this on CURVE client sockets. This key must have been generated together with the server's secret key. You can create a new keypair with curveKeyPair().
Readonlyevents
Event Observer for this socket. This starts up a ØMQ monitoring socket internally that receives all socket events.
gssapiPlainText
gssapiPrincipal
gssapiPrincipalNameType
gssapiServer
gssapiServicePrincipal
gssapiServicePrincipalNameType
handshakeInterval
ZMQ_HANDSHAKE_IVL
Handshaking is the exchange of socket configuration information (socket type, identity, security) that occurs when a connection is first opened (only for connection-oriented transports). If handshaking does not complete within the configured time, the connection shall be closed. The value 0 means no handshake time limit.
heartbeatInterval
ZMQ_HEARTBEAT_IVL
Interval in milliseconds between sending ZMTP heartbeats for the specified socket. If this option is greater than 0, then a PING ZMTP command will be sent after every interval.
heartbeatTimeout
ZMQ_HEARTBEAT_TIMEOUT
How long (in milliseconds) to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic. This option is only valid if heartbeatInterval is greater than 0. The connection will time out if there is no traffic received after sending the PING command. The received traffic does not have to be a PONG command - any received traffic will cancel the timeout.
heartbeatTimeToLive
ZMQ_HEARTBEAT_TTL
The timeout in milliseconds on the remote peer for ZMTP heartbeats. If this option is greater than 0, the remote side shall time out the connection if it does not receive any more traffic within the TTL period. This option does not have any effect if heartbeatInterval is 0. Internally, this value is rounded down to the nearest decisecond, any value less than 100 will have no effect.
immediate
ZMQ_IMMEDIATE
By default queues will fill on outgoing connections even if the connection has not completed. This can lead to "lost" messages on sockets with round-robin routing (Request, Push, Dealer). If this option is set to true, messages shall be queued only to completed connections. This will cause the socket to block if there are no other connections, but will prevent queues from filling on pipes awaiting connection.
interface
ZMQ_BINDTODEVICE
Binds the socket to the given network interface (Linux only). Allows to use Linux VRF, see: https://www.kernel.org/doc/Documentation/networking/vrf.txt. Requires the program to be ran as root or with CAP_NET_RAW.
ipv6
ZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
ReadonlylastEndpoint
ZMQ_LAST_ENDPOINT
The last endpoint bound for TCP and IPC transports.
linger
ZMQ_LINGER
Determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with close().
loopbackFastPath
ZMQ_LOOPBACK_FASTPATH
Enable faster TCP connections on loopback devices. An application can enable this option to reduce the latency and improve the performance of loopback operations on a TCP socket on Windows.
maxMessageSize
ZMQ_MAXMSGSIZE
Limits the size of the inbound message. If a peer sends a message larger than the limit it is disconnected. Value of -1 means no limit.
multicastHops
ZMQ_MULTICAST_HOPS
Sets the time-to-live field in every multicast packet sent from this socket. The default is 1 which means that the multicast packets don't leave the local network.
multicastMaxTransportDataUnit
ZMQ_MULTICAST_MAXTPDU
Sets the maximum transport data unit size used for outbound multicast packets. This must be set at or below the minimum Maximum Transmission Unit (MTU) for all network paths over which multicast reception is required.
plainPassword
ZMQ_PLAIN_PASSWORD
Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
plainServer
ZMQ_PLAIN_SERVER
Defines whether the socket will act as server for PLAIN security. A value of true means the socket will act as PLAIN server. A value of false means the socket will not act as PLAIN server, and its security role then depends on other option settings.
plainUsername
ZMQ_PLAIN_USERNAME
Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
probeRouter
ZMQ_PROBE_ROUTER
When set to true, the socket will automatically send an empty message when a new connection is made or accepted. You may set this on sockets connected to a Router socket. The application must filter such empty messages. This option provides the Router with an event signaling the arrival of a new peer.
Warning:* Do not set this option on a socket that talks to any other socket type except Router: the results are undefined.
rate
ZMQ_RATE
Maximum send or receive data rate for multicast transports such as pgm.
Readonlyreadable
Whether any messages are currently available. If true, the next call to Readable.receive() will immediately read a message from the socket. For sockets that cannot receive messsages this is always false.
receiveBufferSize
ZMQ_RCVBUF
Underlying kernel receive buffer size in bytes. A value of -1 means leave the OS default unchanged.
receiveHighWaterMark
ZMQ_RCVHWM
The high water mark is a hard limit on the maximum number of incoming messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
receiveTimeout
ZMQ_RCVTIMEO
Sets the timeout receiving messages on the socket. If the value is 0, receive() will return a rejected promise immediately if there is no message to receive. If the value is -1, it will wait asynchronously until a message is available. For all other values, it will wait for a message for that amount of time before rejecting.
reconnectInterval
ZMQ_RECONNECT_IVL
Period ØMQ shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. The value -1 means no reconnection.
reconnectMaxInterval
ZMQ_RECONNECT_IVL_MAX
Maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled until reconnectMaxInterval is reached. This allows for exponential backoff strategy. Zero (the default) means no exponential backoff is performed and reconnect interval calculations are only based on reconnectInterval.
recoveryInterval
ZMQ_RECOVERY_IVL
Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
relaxed
ZMQ_REQ_RELAXED
By default, a Request socket does not allow initiating a new request until the reply to the previous one has been received. When set to true, sending another message is allowed and previous replies will be discarded. The request-reply state machine is reset and a new request is sent to the next available peer.
Note: If set to true, also enable correlate to ensure correct matching of requests and replies. Otherwise a late reply to an aborted request can be reported as the reply to the superseding request.
routingId
ZMQ_ROUTING_ID
The identity of the specified socket when connecting to a Router socket.
ReadonlysecurityMechanism
ZMQ_MECHANISM
Returns the current security mechanism for the socket, if any. The security mechanism is set implictly by using any of the relevant security options. The returned value is one of:
null- No security mechanism is used."plain"- The PLAIN mechanism defines a simple username/password mechanism that lets a server authenticate a client. PLAIN makes no attempt at security or confidentiality."curve"- The CURVE mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server. CURVE is intended for use on public networks."gssapi"- The GSSAPI mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server using the Generic Security Service Application Program Interface (GSSAPI). The GSSAPI mechanism can be used on both public and private networks.
sendBufferSize
ZMQ_SNDBUF
Underlying kernel transmit buffer size in bytes. A value of -1 means leave the OS default unchanged.
sendHighWaterMark
ZMQ_SNDHWM
The high water mark is a hard limit on the maximum number of outgoing messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
sendTimeout
ZMQ_SNDTIMEO
Sets the timeout for sending messages on the socket. If the value is 0, send() will return a rejected promise immediately if the message cannot be sent. If the value is -1, it will wait asynchronously until the message is sent. For all other values, it will try to send the message for that amount of time before rejecting.
socksProxy
ZMQ_SOCKS_PROXY
The SOCKS5 proxy address that shall be used by the socket for the TCP connection(s). Does not support SOCKS5 authentication. If the endpoints are domain names instead of addresses they shall not be resolved and they shall be forwarded unchanged to the SOCKS proxy service in the client connection request message (address type 0x03 domain name).
tcpAcceptFilter
ZMQ_TCP_ACCEPT_FILTER
Assign a filter that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one filter is applied then new connection source IP should be matched. To clear all filters set to null. Filter is a string with IPv6 or IPv4 CIDR.
tcpKeepalive
ZMQ_TCP_KEEPALIVE
Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveCount
ZMQ_TCP_KEEPALIVE_CNT
Overrides TCP_KEEPCNT socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveIdle
ZMQ_TCP_KEEPALIVE_IDLE
Overrides TCP_KEEPIDLE / TCP_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveInterval
ZMQ_TCP_KEEPALIVE_INTVL
Overrides TCP_KEEPINTVL socket option (if supported by the OS). The default value of -1 leaves it to the OS default.
tcpMaxRetransmitTimeout
ZMQ_TCP_MAXRT
Sets how long before an unacknowledged TCP retransmit times out (if supported by the OS). The system normally attempts many TCP retransmits following an exponential backoff strategy. This means that after a network outage, it may take a long time before the session can be re-established. Setting this option allows the timeout to happen at a shorter interval.
ReadonlythreadSafe
ZMQ_THREAD_SAFE
Whether or not the socket is threadsafe. Currently only DRAFT sockets is thread-safe.
Readonlytype
ZMQ_TYPE
Retrieve the socket type. This is fairly useless because you can test the socket class with e.g. socket instanceof Dealer.
typeOfService
ZMQ_TOS
Sets the ToS fields (the Differentiated Services (DS) and Explicit Congestion Notification (ECN) field) of the IP header. The ToS field is typically used to specify a packet's priority. The availability of this option is dependent on intermediate network equipment that inspect the ToS field and provide a path for low-delay, high-throughput, highly-reliable service, etc.
vmciBufferMaxSize
ZMQ_VMCI_BUFFER_MAX_SIZE
Maximum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferMinSize
ZMQ_VMCI_BUFFER_MIN_SIZE
Minimum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferSize
ZMQ_VMCI_BUFFER_SIZE
The size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciConnectTimeout
ZMQ_VMCI_CONNECT_TIMEOUT
Connection timeout for the socket. For vmci:// transports only.
Readonlywritable
Whether any messages can be queued for sending. If true, the next call to Writable.send() will immediately queue a message on the socket. For sockets that cannot send messsages this is always false.
zapDomain
ZMQ_ZAP_DOMAIN
Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the default on all tcp:// connections), ZAP authentication only happens if you set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 for more details.
zapEnforceDomain
ZMQ_ZAP_ENFORCE_DOMAIN
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.
Methods
[asyncIterator]
- "[asyncIterator]"(): AsyncIterator<Buffer[]>
Asynchronously iterate over messages becoming available on the socket. When the socket is closed with Socket.close(), the iterator will return. Returning early from the iterator will not close the socket unless it also goes out of scope.
for await (const [msg] of socket) {
// handle messages
} +Returns AsyncIterator<Buffer[]>
bind
- bind(address: string): Promise<void>
Binds the socket to the given address. During bind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.You can use
*in place of a hostname to bind on all interfaces/addresses, and you can use*in place of a port to bind to a random port (which can be retrieved with lastEndpoint later).await socket.bind("tcp://127.0.0.1:3456")
await socket.bind("tcp://*:3456") // binds on all interfaces
await socket.bind("tcp://127.0.0.1:*") // binds on random port +Parameters
- address: string
Address to bind this socket to.
Returns Promise<void>
Resolved when the socket was successfully bound.
- address: string
bindSync
- bindSync(address: string): void
Binds the socket to the given address. During bind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.You can use
*in place of a hostname to bind on all interfaces/addresses, and you can use*in place of a port to bind to a random port (which can be retrieved with lastEndpoint later).socket.bindSync("tcp://127.0.0.1:3456")
socket.bindSync("tcp://*:3456") // binds on all interfaces
socket.bindSync("tcp://127.0.0.1:*") // binds on random port +Parameters
- address: string
Address to bind this socket to.
Returns void
Resolved when the socket was successfully bound.
- address: string
close
- close(): void
Closes the socket and disposes of all resources. Any messages that are queued may be discarded or sent in the background depending on the linger setting.
After this method is called, it is no longer possible to call any other methods on this socket.
Sockets that go out of scope and have no Readable.receive() or Writable.send() operations in progress will automatically be closed. Therefore it is not necessary in most applications to call close() manually.
Calling this method on a socket that is already closed is a no-op.
Returns void
connect
disconnect
- disconnect(address: string): void
Disconnects a previously connected socket from the given address and returns immediately. Disonnection will happen asynchronously in the background.
socket.disconnect("tcp://127.0.0.1:3456") +Parameters
- address: string
The previously connected address to disconnect from.
Returns void
- address: string
ProtectedgetBoolOption
ProtectedgetInt32Option
ProtectedgetInt64Option
ProtectedgetStringOption
ProtectedgetUint32Option
ProtectedgetUint64Option
receive
- receive(): Promise<Buffer[]>
Waits for the next single or multipart message to become availeble on the socket. Reads a message immediately if possible. If no messages can be read, it will wait asynchonously. The promise will be resolved with an array containing the parts of the next message when available.
const [msg] = await socket.receive()
const [part1, part2] = await socket.receive() +Reading may fail (eventually) if the socket has been configured with a receiveTimeout.
A call to receive() is guaranteed to return with a resolved promise immediately if a message could be read from the socket directly.
Only one asynchronously blocking call to receive() can be in progress simultaneously. If you call receive() again on the same socket it will return a rejected promise with an
EBUSYerror. For example, if no messages can be read and noawaitis used:socket.receive() // -> pending promise until read is possible
socket.receive() // -> promise rejection with `EBUSY` error +Note: Due to the nature of Node.js and to avoid blocking the main thread, this method always attempts to read messages with the
ZMQ_DONTWAITflag. It polls asynchronously if reading is not currently possible. This means that all functionality related to timeouts and blocking behaviour is reimplemented in the Node.js bindings. Any differences in behaviour with the native ZMQ library is considered a bug.Returns Promise<Buffer[]>
Resolved with message parts that were successfully read.
send
- send(message: MessageLike | MessageLike[], ...options: []): Promise<void>
Sends a single message or a multipart message on the socket. Queues the message immediately if possible, and returns a resolved promise. If the message cannot be queued because the high water mark has been reached, it will wait asynchronously. The promise will be resolved when the message was queued successfully.
await socket.send("hello world")
await socket.send(["hello", "world"]) +Queueing may fail eventually if the socket has been configured with a sendTimeout.
A call to send() is guaranteed to return with a resolved promise immediately if the message could be queued directly.
Only one asynchronously blocking call to send() may be executed simultaneously. If you call send() again on a socket that is in the mute state it will return a rejected promise with an
EBUSYerror.The reason for disallowing multiple send() calls simultaneously is that it could create an implicit queue of unsendable outgoing messages. This would circumvent the socket's sendHighWaterMark. Such an implementation could even exhaust all system memory and cause the Node.js process to abort.
For most application you should not notice this implementation detail. Only in rare occasions will a call to send() that does not resolve immediately be undesired. Here are some common scenarios:
If you wish to send a message, use
await send(...). ZeroMQ socket types have been carefully designed to give you the correct blocking behaviour on the chosen socket type in almost all cases:If sending is not possible, it is often better to wait than to continue as if nothing happened. For example, on a Request socket, you can only receive a reply once a message has been sent; so waiting until a message could be queued before continuing with the rest of the program (likely to read from the socket) is required.
Certain socket types (such as Router) will always allow queueing messages and
await send(...)won't delay any code that comes after. This makes sense for routers, since typically you don't want a single send operation to stop the handling of other incoming or outgoing messages.
If you wish to send on an occasionally blocking socket (for example on a Router with the Router.mandatory option set, or on a Dealer) and you're 100% certain that dropping a message is better than blocking, then you can set the sendTimeout option to
0to effectively force send() to always resolve immediately. Be prepared to catch exceptions if sending a message is not immediately possible.If you wish to send on a socket and messages should be queued before they are dropped, you should implement a simple queue in JavaScript. Such a queue is not provided by this library because most real world applications need to deal with undeliverable messages in more complex ways - for example, they might need to reply with a status message; or first retry delivery a certain number of times before giving up.
Parameters
- message: MessageLike | MessageLike[]
Single message or multipart message to queue for sending.
- ...options: []
Any options, if applicable to the socket type (DRAFT only).
Returns Promise<void>
Resolved when the message was successfully queued.
ProtectedsetBoolOption
ProtectedsetInt32Option
ProtectedsetInt64Option
ProtectedsetStringOption
ProtectedsetUint32Option
ProtectedsetUint64Option
unbind
- unbind(address: string): Promise<void>
Unbinds the socket to the given address. During unbind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.Parameters
- address: string
Address to unbind this socket from.
Returns Promise<void>
Resolved when the socket was successfully unbound.
- address: string
unbindSync
- unbindSync(address: string): void
Unbinds the socket to the given address. During unbind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.Parameters
- address: string
Address to unbind this socket from.
Returns void
Resolved when the socket was successfully unbound.
- address: string
Class Router
A Router can be used to extend request/reply sockets. When receiving messages a Router shall prepend a message part containing the routing id of the originating peer to the message. Messages received are fair-queued from among all connected peers. When sending messages, the first part of the message is removed and used to determine the routing id of the peer the message should be routed to.
If the peer does not exist anymore, or has never existed, the message shall be silently discarded. However, if Router.mandatory is set to true, the socket shall fail with a EHOSTUNREACH error in both cases.
When a Router enters the mute state due to having reached the high water mark for all peers, then any messages sent to the socket shall be dropped until the mute state ends. Likewise, any messages routed to a peer for which the individual high water mark has been reached shall also be dropped. If Router.mandatory is set to true the socket shall block or return an EAGAIN error in both cases.
When a Request socket is connected to a Router, in addition to the routing id of the originating peer each message received shall contain an empty delimiter message part. Hence, the entire structure of each received message as seen by the application becomes: one or more routing id parts, delimiter part, one or more body parts. When sending replies to a Request the delimiter part must be included.
Hierarchy (view full)
Index
Constructors
Properties
Methods
Constructors
constructor
- new
Router (options?): Router Parameters
Optionaloptions: {
affinity?: number;
backlog?: number;
connectTimeout?: number;
context?: Context;
curvePublicKey?: null | string;
curveSecretKey?: null | string;
curveServer?: boolean;
curveServerKey?: null | string;
gssapiPlainText?: boolean;
gssapiPrincipal?: null | string;
gssapiPrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
gssapiServer?: boolean;
gssapiServicePrincipal?: null | string;
gssapiServicePrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
handover?: boolean;
handshakeInterval?: number;
heartbeatInterval?: number;
heartbeatTimeout?: number;
heartbeatTimeToLive?: number;
immediate?: boolean;
interface?: null | string;
ipv6?: boolean;
linger?: number;
loopbackFastPath?: boolean;
mandatory?: boolean;
maxMessageSize?: number;
multicastHops?: number;
multicastMaxTransportDataUnit?: number;
plainPassword?: null | string;
plainServer?: boolean;
plainUsername?: null | string;
probeRouter?: boolean;
rate?: number;
receiveBufferSize?: number;
receiveHighWaterMark?: number;
receiveTimeout?: number;
reconnectInterval?: number;
reconnectMaxInterval?: number;
recoveryInterval?: number;
routingId?: null | string;
sendBufferSize?: number;
sendHighWaterMark?: number;
sendTimeout?: number;
socksProxy?: null | string;
tcpAcceptFilter?: null | string;
tcpKeepalive?: number;
tcpKeepaliveCount?: number;
tcpKeepaliveIdle?: number;
tcpKeepaliveInterval?: number;
tcpMaxRetransmitTimeout?: number;
typeOfService?: number;
vmciBufferMaxSize?: number;
vmciBufferMinSize?: number;
vmciBufferSize?: number;
vmciConnectTimeout?: number;
zapDomain?: null | string;
zapEnforceDomain?: boolean;
}Optionalaffinity?: numberZMQ_AFFINITY
I/O thread affinity, which determines which threads from the ØMQ I/O thread pool associated with the socket's context shall handle newly created connections.
Note: This value is a bit mask, but values higher than
Number.MAX_SAFE_INTEGERmay not be represented accurately! This currently means that configurations beyond 52 threads are unreliable.Optionalbacklog?: numberZMQ_BACKLOG
Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.
OptionalconnectTimeout ?: numberZMQ_CONNECT_TIMEOUT
Sets how long to wait before timing-out a connect() system call. The connect() system call normally takes a long time before it returns a time out error. Setting this option allows the library to time out the call at an earlier interval.
Optionalcontext?: ContextOptionalcurvePublic ?: null | stringKey ZMQ_CURVE_PUBLICKEY
Sets the socket's long term public key. You must set this on CURVE client sockets. A server socket does not need to know its own public key. You can create a new keypair with curveKeyPair().
OptionalcurveSecret ?: null | stringKey ZMQ_CURVE_SECRETKEY
Sets the socket's long term secret key. You must set this on both CURVE client and server sockets. You can create a new keypair with curveKeyPair().
OptionalcurveServer ?: booleanZMQ_CURVE_SERVER
Defines whether the socket will act as server for CURVE security. A value of
truemeans the socket will act as CURVE server. A value offalsemeans the socket will not act as CURVE server, and its security role then depends on other option settings.OptionalcurveServer ?: null | stringKey ZMQ_CURVE_SERVERKEY
Sets the socket's long term server key. This is the public key of the CURVE server socket. You must set this on CURVE client sockets. This key must have been generated together with the server's secret key. You can create a new keypair with curveKeyPair().
OptionalgssapiPlain ?: booleanText OptionalgssapiPrincipal ?: null | stringOptionalgssapiPrincipal ?: "hostBased" | "userName" | "krb5Principal"Name Type OptionalgssapiServer ?: booleanOptionalgssapiService ?: null | stringPrincipal OptionalgssapiService ?: "hostBased" | "userName" | "krb5Principal"Principal Name Type Optionalhandover?: booleanZMQ_ROUTER_HANDOVER
If two clients use the same identity when connecting to a Router, the results shall depend on the this option. If it set to
false(default), the Router socket shall reject clients trying to connect with an already-used identity. If it is set totrue, the Router socket shall hand-over the connection to the new client and disconnect the existing one.OptionalhandshakeInterval ?: numberZMQ_HANDSHAKE_IVL
Handshaking is the exchange of socket configuration information (socket type, identity, security) that occurs when a connection is first opened (only for connection-oriented transports). If handshaking does not complete within the configured time, the connection shall be closed. The value 0 means no handshake time limit.
OptionalheartbeatInterval ?: numberZMQ_HEARTBEAT_IVL
Interval in milliseconds between sending ZMTP heartbeats for the specified socket. If this option is greater than 0, then a PING ZMTP command will be sent after every interval.
OptionalheartbeatTimeout ?: numberZMQ_HEARTBEAT_TIMEOUT
How long (in milliseconds) to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic. This option is only valid if heartbeatInterval is greater than 0. The connection will time out if there is no traffic received after sending the PING command. The received traffic does not have to be a PONG command - any received traffic will cancel the timeout.
OptionalheartbeatTime ?: numberTo Live ZMQ_HEARTBEAT_TTL
The timeout in milliseconds on the remote peer for ZMTP heartbeats. If this option is greater than 0, the remote side shall time out the connection if it does not receive any more traffic within the TTL period. This option does not have any effect if heartbeatInterval is 0. Internally, this value is rounded down to the nearest decisecond, any value less than 100 will have no effect.
Optionalimmediate?: booleanZMQ_IMMEDIATE
By default queues will fill on outgoing connections even if the connection has not completed. This can lead to "lost" messages on sockets with round-robin routing (Request, Push, Dealer). If this option is set to
true, messages shall be queued only to completed connections. This will cause the socket to block if there are no other connections, but will prevent queues from filling on pipes awaiting connection.Optionalinterface?: null | stringZMQ_BINDTODEVICE
Binds the socket to the given network interface (Linux only). Allows to use Linux VRF, see: https://www.kernel.org/doc/Documentation/networking/vrf.txt. Requires the program to be ran as root or with
CAP_NET_RAW.Optionalipv6?: booleanZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
Optionallinger?: numberZMQ_LINGER
Determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with close().
OptionalloopbackFast ?: booleanPath ZMQ_LOOPBACK_FASTPATH
Enable faster TCP connections on loopback devices. An application can enable this option to reduce the latency and improve the performance of loopback operations on a TCP socket on Windows.
Optionalmandatory?: booleanZMQ_ROUTER_MANDATORY
A value of
falseis the default and discards the message silently when it cannot be routed or the peer's high water mark is reached. A value oftruecauses send() to fail if it cannot be routed, or wait asynchronously if the high water mark is reached.OptionalmaxMessage ?: numberSize ZMQ_MAXMSGSIZE
Limits the size of the inbound message. If a peer sends a message larger than the limit it is disconnected. Value of -1 means no limit.
OptionalmulticastHops ?: numberZMQ_MULTICAST_HOPS
Sets the time-to-live field in every multicast packet sent from this socket. The default is 1 which means that the multicast packets don't leave the local network.
OptionalmulticastMax ?: numberTransport Data Unit ZMQ_MULTICAST_MAXTPDU
Sets the maximum transport data unit size used for outbound multicast packets. This must be set at or below the minimum Maximum Transmission Unit (MTU) for all network paths over which multicast reception is required.
OptionalplainPassword ?: null | stringZMQ_PLAIN_PASSWORD
Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
OptionalplainServer ?: booleanZMQ_PLAIN_SERVER
Defines whether the socket will act as server for PLAIN security. A value of
truemeans the socket will act as PLAIN server. A value offalsemeans the socket will not act as PLAIN server, and its security role then depends on other option settings.OptionalplainUsername ?: null | stringZMQ_PLAIN_USERNAME
Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
OptionalprobeRouter ?: booleanZMQ_PROBE_ROUTER
When set to
true, the socket will automatically send an empty message when a new connection is made or accepted. You may set this on sockets connected to a Router socket. The application must filter such empty messages. This option provides the Router with an event signaling the arrival of a new peer.Warning:* Do not set this option on a socket that talks to any other socket type except Router: the results are undefined.
Optionalrate?: numberZMQ_RATE
Maximum send or receive data rate for multicast transports such as
pgm.OptionalreceiveBuffer ?: numberSize ZMQ_RCVBUF
Underlying kernel receive buffer size in bytes. A value of -1 means leave the OS default unchanged.
OptionalreceiveHigh ?: numberWater Mark ZMQ_RCVHWM
The high water mark is a hard limit on the maximum number of incoming messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
OptionalreceiveTimeout ?: numberZMQ_RCVTIMEO
Sets the timeout receiving messages on the socket. If the value is 0, receive() will return a rejected promise immediately if there is no message to receive. If the value is -1, it will wait asynchronously until a message is available. For all other values, it will wait for a message for that amount of time before rejecting.
OptionalreconnectInterval ?: numberZMQ_RECONNECT_IVL
Period ØMQ shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. The value -1 means no reconnection.
OptionalreconnectMax ?: numberInterval ZMQ_RECONNECT_IVL_MAX
Maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled until reconnectMaxInterval is reached. This allows for exponential backoff strategy. Zero (the default) means no exponential backoff is performed and reconnect interval calculations are only based on reconnectInterval.
OptionalrecoveryInterval ?: numberZMQ_RECOVERY_IVL
Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
OptionalroutingId ?: null | stringZMQ_ROUTING_ID
The identity of the specified socket when connecting to a
Routersocket.OptionalsendBuffer ?: numberSize ZMQ_SNDBUF
Underlying kernel transmit buffer size in bytes. A value of -1 means leave the OS default unchanged.
OptionalsendHigh ?: numberWater Mark ZMQ_SNDHWM
The high water mark is a hard limit on the maximum number of outgoing messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
OptionalsendTimeout ?: numberZMQ_SNDTIMEO
Sets the timeout for sending messages on the socket. If the value is 0, send() will return a rejected promise immediately if the message cannot be sent. If the value is -1, it will wait asynchronously until the message is sent. For all other values, it will try to send the message for that amount of time before rejecting.
OptionalsocksProxy ?: null | stringZMQ_SOCKS_PROXY
The SOCKS5 proxy address that shall be used by the socket for the TCP connection(s). Does not support SOCKS5 authentication. If the endpoints are domain names instead of addresses they shall not be resolved and they shall be forwarded unchanged to the SOCKS proxy service in the client connection request message (address type 0x03 domain name).
OptionaltcpAccept ?: null | stringFilter ZMQ_TCP_ACCEPT_FILTER
Assign a filter that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one filter is applied then new connection source IP should be matched. To clear all filters set to
null. Filter is a string with IPv6 or IPv4 CIDR.OptionaltcpKeepalive ?: numberZMQ_TCP_KEEPALIVE
Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepalive ?: numberCount ZMQ_TCP_KEEPALIVE_CNT
Overrides TCP_KEEPCNT socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepalive ?: numberIdle ZMQ_TCP_KEEPALIVE_IDLE
Overrides TCP_KEEPIDLE / TCP_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepalive ?: numberInterval ZMQ_TCP_KEEPALIVE_INTVL
Overrides TCP_KEEPINTVL socket option (if supported by the OS). The default value of -1 leaves it to the OS default.
OptionaltcpMax ?: numberRetransmit Timeout ZMQ_TCP_MAXRT
Sets how long before an unacknowledged TCP retransmit times out (if supported by the OS). The system normally attempts many TCP retransmits following an exponential backoff strategy. This means that after a network outage, it may take a long time before the session can be re-established. Setting this option allows the timeout to happen at a shorter interval.
OptionaltypeOf ?: numberService ZMQ_TOS
Sets the ToS fields (the Differentiated Services (DS) and Explicit Congestion Notification (ECN) field) of the IP header. The ToS field is typically used to specify a packet's priority. The availability of this option is dependent on intermediate network equipment that inspect the ToS field and provide a path for low-delay, high-throughput, highly-reliable service, etc.
OptionalvmciBuffer ?: numberMax Size ZMQ_VMCI_BUFFER_MAX_SIZE
Maximum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciBuffer ?: numberMin Size ZMQ_VMCI_BUFFER_MIN_SIZE
Minimum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciBuffer ?: numberSize ZMQ_VMCI_BUFFER_SIZE
The size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciConnect ?: numberTimeout ZMQ_VMCI_CONNECT_TIMEOUT
Connection timeout for the socket. For
vmci://transports only.OptionalzapDomain ?: null | stringZMQ_ZAP_DOMAIN
Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the default on all
tcp://connections), ZAP authentication only happens if you set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 for more details.OptionalzapEnforce ?: booleanDomain ZMQ_ZAP_ENFORCE_DOMAIN
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.
Returns Router
Properties
affinity
ZMQ_AFFINITY
I/O thread affinity, which determines which threads from the ØMQ I/O thread pool associated with the socket's context shall handle newly created connections.
Note: This value is a bit mask, but values higher than Number.MAX_SAFE_INTEGER may not be represented accurately! This currently means that configurations beyond 52 threads are unreliable.
backlog
ZMQ_BACKLOG
Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.
Readonlyclosed
Whether this socket was previously closed with close().
connectTimeout
ZMQ_CONNECT_TIMEOUT
Sets how long to wait before timing-out a connect() system call. The connect() system call normally takes a long time before it returns a time out error. Setting this option allows the library to time out the call at an earlier interval.
Readonlycontext
Context that this socket belongs to.
curvePublicKey
ZMQ_CURVE_PUBLICKEY
Sets the socket's long term public key. You must set this on CURVE client sockets. A server socket does not need to know its own public key. You can create a new keypair with curveKeyPair().
curveSecretKey
ZMQ_CURVE_SECRETKEY
Sets the socket's long term secret key. You must set this on both CURVE client and server sockets. You can create a new keypair with curveKeyPair().
curveServer
ZMQ_CURVE_SERVER
Defines whether the socket will act as server for CURVE security. A value of true means the socket will act as CURVE server. A value of false means the socket will not act as CURVE server, and its security role then depends on other option settings.
curveServerKey
ZMQ_CURVE_SERVERKEY
Sets the socket's long term server key. This is the public key of the CURVE server socket. You must set this on CURVE client sockets. This key must have been generated together with the server's secret key. You can create a new keypair with curveKeyPair().
Readonlyevents
Event Observer for this socket. This starts up a ØMQ monitoring socket internally that receives all socket events.
gssapiPlainText
gssapiPrincipal
gssapiPrincipalNameType
gssapiServer
gssapiServicePrincipal
gssapiServicePrincipalNameType
handover
ZMQ_ROUTER_HANDOVER
If two clients use the same identity when connecting to a Router, the results shall depend on the this option. If it set to false (default), the Router socket shall reject clients trying to connect with an already-used identity. If it is set to true, the Router socket shall hand-over the connection to the new client and disconnect the existing one.
handshakeInterval
ZMQ_HANDSHAKE_IVL
Handshaking is the exchange of socket configuration information (socket type, identity, security) that occurs when a connection is first opened (only for connection-oriented transports). If handshaking does not complete within the configured time, the connection shall be closed. The value 0 means no handshake time limit.
heartbeatInterval
ZMQ_HEARTBEAT_IVL
Interval in milliseconds between sending ZMTP heartbeats for the specified socket. If this option is greater than 0, then a PING ZMTP command will be sent after every interval.
heartbeatTimeout
ZMQ_HEARTBEAT_TIMEOUT
How long (in milliseconds) to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic. This option is only valid if heartbeatInterval is greater than 0. The connection will time out if there is no traffic received after sending the PING command. The received traffic does not have to be a PONG command - any received traffic will cancel the timeout.
heartbeatTimeToLive
ZMQ_HEARTBEAT_TTL
The timeout in milliseconds on the remote peer for ZMTP heartbeats. If this option is greater than 0, the remote side shall time out the connection if it does not receive any more traffic within the TTL period. This option does not have any effect if heartbeatInterval is 0. Internally, this value is rounded down to the nearest decisecond, any value less than 100 will have no effect.
immediate
ZMQ_IMMEDIATE
By default queues will fill on outgoing connections even if the connection has not completed. This can lead to "lost" messages on sockets with round-robin routing (Request, Push, Dealer). If this option is set to true, messages shall be queued only to completed connections. This will cause the socket to block if there are no other connections, but will prevent queues from filling on pipes awaiting connection.
interface
ZMQ_BINDTODEVICE
Binds the socket to the given network interface (Linux only). Allows to use Linux VRF, see: https://www.kernel.org/doc/Documentation/networking/vrf.txt. Requires the program to be ran as root or with CAP_NET_RAW.
ipv6
ZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
ReadonlylastEndpoint
ZMQ_LAST_ENDPOINT
The last endpoint bound for TCP and IPC transports.
linger
ZMQ_LINGER
Determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with close().
loopbackFastPath
ZMQ_LOOPBACK_FASTPATH
Enable faster TCP connections on loopback devices. An application can enable this option to reduce the latency and improve the performance of loopback operations on a TCP socket on Windows.
mandatory
ZMQ_ROUTER_MANDATORY
A value of false is the default and discards the message silently when it cannot be routed or the peer's high water mark is reached. A value of true causes send() to fail if it cannot be routed, or wait asynchronously if the high water mark is reached.
maxMessageSize
ZMQ_MAXMSGSIZE
Limits the size of the inbound message. If a peer sends a message larger than the limit it is disconnected. Value of -1 means no limit.
multicastHops
ZMQ_MULTICAST_HOPS
Sets the time-to-live field in every multicast packet sent from this socket. The default is 1 which means that the multicast packets don't leave the local network.
multicastMaxTransportDataUnit
ZMQ_MULTICAST_MAXTPDU
Sets the maximum transport data unit size used for outbound multicast packets. This must be set at or below the minimum Maximum Transmission Unit (MTU) for all network paths over which multicast reception is required.
plainPassword
ZMQ_PLAIN_PASSWORD
Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
plainServer
ZMQ_PLAIN_SERVER
Defines whether the socket will act as server for PLAIN security. A value of true means the socket will act as PLAIN server. A value of false means the socket will not act as PLAIN server, and its security role then depends on other option settings.
plainUsername
ZMQ_PLAIN_USERNAME
Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
probeRouter
ZMQ_PROBE_ROUTER
When set to true, the socket will automatically send an empty message when a new connection is made or accepted. You may set this on sockets connected to a Router socket. The application must filter such empty messages. This option provides the Router with an event signaling the arrival of a new peer.
Warning:* Do not set this option on a socket that talks to any other socket type except Router: the results are undefined.
rate
ZMQ_RATE
Maximum send or receive data rate for multicast transports such as pgm.
Readonlyreadable
Whether any messages are currently available. If true, the next call to Readable.receive() will immediately read a message from the socket. For sockets that cannot receive messsages this is always false.
receiveBufferSize
ZMQ_RCVBUF
Underlying kernel receive buffer size in bytes. A value of -1 means leave the OS default unchanged.
receiveHighWaterMark
ZMQ_RCVHWM
The high water mark is a hard limit on the maximum number of incoming messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
receiveTimeout
ZMQ_RCVTIMEO
Sets the timeout receiving messages on the socket. If the value is 0, receive() will return a rejected promise immediately if there is no message to receive. If the value is -1, it will wait asynchronously until a message is available. For all other values, it will wait for a message for that amount of time before rejecting.
reconnectInterval
ZMQ_RECONNECT_IVL
Period ØMQ shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. The value -1 means no reconnection.
reconnectMaxInterval
ZMQ_RECONNECT_IVL_MAX
Maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled until reconnectMaxInterval is reached. This allows for exponential backoff strategy. Zero (the default) means no exponential backoff is performed and reconnect interval calculations are only based on reconnectInterval.
recoveryInterval
ZMQ_RECOVERY_IVL
Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
routingId
ZMQ_ROUTING_ID
The identity of the specified socket when connecting to a Router socket.
ReadonlysecurityMechanism
| null
| "plain"
| "curve"
| "gssapi"
ZMQ_MECHANISM
Returns the current security mechanism for the socket, if any. The security mechanism is set implictly by using any of the relevant security options. The returned value is one of:
null- No security mechanism is used."plain"- The PLAIN mechanism defines a simple username/password mechanism that lets a server authenticate a client. PLAIN makes no attempt at security or confidentiality."curve"- The CURVE mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server. CURVE is intended for use on public networks."gssapi"- The GSSAPI mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server using the Generic Security Service Application Program Interface (GSSAPI). The GSSAPI mechanism can be used on both public and private networks.
sendBufferSize
ZMQ_SNDBUF
Underlying kernel transmit buffer size in bytes. A value of -1 means leave the OS default unchanged.
sendHighWaterMark
ZMQ_SNDHWM
The high water mark is a hard limit on the maximum number of outgoing messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
sendTimeout
ZMQ_SNDTIMEO
Sets the timeout for sending messages on the socket. If the value is 0, send() will return a rejected promise immediately if the message cannot be sent. If the value is -1, it will wait asynchronously until the message is sent. For all other values, it will try to send the message for that amount of time before rejecting.
socksProxy
ZMQ_SOCKS_PROXY
The SOCKS5 proxy address that shall be used by the socket for the TCP connection(s). Does not support SOCKS5 authentication. If the endpoints are domain names instead of addresses they shall not be resolved and they shall be forwarded unchanged to the SOCKS proxy service in the client connection request message (address type 0x03 domain name).
tcpAcceptFilter
ZMQ_TCP_ACCEPT_FILTER
Assign a filter that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one filter is applied then new connection source IP should be matched. To clear all filters set to null. Filter is a string with IPv6 or IPv4 CIDR.
tcpKeepalive
ZMQ_TCP_KEEPALIVE
Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveCount
ZMQ_TCP_KEEPALIVE_CNT
Overrides TCP_KEEPCNT socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveIdle
ZMQ_TCP_KEEPALIVE_IDLE
Overrides TCP_KEEPIDLE / TCP_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveInterval
ZMQ_TCP_KEEPALIVE_INTVL
Overrides TCP_KEEPINTVL socket option (if supported by the OS). The default value of -1 leaves it to the OS default.
tcpMaxRetransmitTimeout
ZMQ_TCP_MAXRT
Sets how long before an unacknowledged TCP retransmit times out (if supported by the OS). The system normally attempts many TCP retransmits following an exponential backoff strategy. This means that after a network outage, it may take a long time before the session can be re-established. Setting this option allows the timeout to happen at a shorter interval.
ReadonlythreadSafe
ZMQ_THREAD_SAFE
Whether or not the socket is threadsafe. Currently only DRAFT sockets is thread-safe.
Readonlytype
ZMQ_TYPE
Retrieve the socket type. This is fairly useless because you can test the socket class with e.g. socket instanceof Dealer.
typeOfService
ZMQ_TOS
Sets the ToS fields (the Differentiated Services (DS) and Explicit Congestion Notification (ECN) field) of the IP header. The ToS field is typically used to specify a packet's priority. The availability of this option is dependent on intermediate network equipment that inspect the ToS field and provide a path for low-delay, high-throughput, highly-reliable service, etc.
vmciBufferMaxSize
ZMQ_VMCI_BUFFER_MAX_SIZE
Maximum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferMinSize
ZMQ_VMCI_BUFFER_MIN_SIZE
Minimum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferSize
ZMQ_VMCI_BUFFER_SIZE
The size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciConnectTimeout
ZMQ_VMCI_CONNECT_TIMEOUT
Connection timeout for the socket. For vmci:// transports only.
Readonlywritable
Whether any messages can be queued for sending. If true, the next call to Writable.send() will immediately queue a message on the socket. For sockets that cannot send messsages this is always false.
zapDomain
ZMQ_ZAP_DOMAIN
Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the default on all tcp:// connections), ZAP authentication only happens if you set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 for more details.
zapEnforceDomain
ZMQ_ZAP_ENFORCE_DOMAIN
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.
Methods
[asyncIterator]
- [async
Iterator] (): AsyncIterator<Buffer[], undefined, undefined> Asynchronously iterate over messages becoming available on the socket. When the socket is closed with Socket.close(), the iterator will return. Returning early from the iterator will not close the socket unless it also goes out of scope.
for await (const [msg] of socket) {
// handle messages
} -Returns AsyncIterator<Buffer[], undefined, undefined>
bind
- bind(address): Promise<void>
Binds the socket to the given address. During bind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.You can use
*in place of a hostname to bind on all interfaces/addresses, and you can use*in place of a port to bind to a random port (which can be retrieved with lastEndpoint later).await socket.bind("tcp://127.0.0.1:3456")
await socket.bind("tcp://*:3456") // binds on all interfaces
await socket.bind("tcp://127.0.0.1:*") // binds on random port -Parameters
- address: string
Address to bind this socket to.
Returns Promise<void>
Resolved when the socket was successfully bound.
- address: string
close
- close(): void
Closes the socket and disposes of all resources. Any messages that are queued may be discarded or sent in the background depending on the linger setting.
After this method is called, it is no longer possible to call any other methods on this socket.
Sockets that go out of scope and have no Readable.receive() or Writable.send() operations in progress will automatically be closed. Therefore it is not necessary in most applications to call close() manually.
Calling this method on a socket that is already closed is a no-op.
Returns void
connect
- connect(address, options?): void
Connects to the given remote address. To specificy a specific routing id, provide a
routingIdoption. The identity should be unique, from 1 to 255 bytes long and MAY NOT start with binary zero.Parameters
- address: string
The
tcp://address to connect to. - options: RouterConnectOptions = {}
Any connection options.
Returns void
- address: string
disconnect
- disconnect(address): void
Disconnects a previously connected socket from the given address and returns immediately. Disonnection will happen asynchronously in the background.
socket.disconnect("tcp://127.0.0.1:3456") -Parameters
- address: string
The previously connected address to disconnect from.
Returns void
- address: string
ProtectedgetBoolOption
ProtectedgetInt32Option
ProtectedgetInt64Option
ProtectedgetStringOption
ProtectedgetUint32Option
ProtectedgetUint64Option
receive
- receive(): Promise<Buffer[]>
Waits for the next single or multipart message to become availeble on the socket. Reads a message immediately if possible. If no messages can be read, it will wait asynchonously. The promise will be resolved with an array containing the parts of the next message when available.
const [msg] = await socket.receive()
const [part1, part2] = await socket.receive() -Reading may fail (eventually) if the socket has been configured with a receiveTimeout.
A call to receive() is guaranteed to return with a resolved promise immediately if a message could be read from the socket directly.
Only one asynchronously blocking call to receive() can be in progress simultaneously. If you call receive() again on the same socket it will return a rejected promise with an
EBUSYerror. For example, if no messages can be read and noawaitis used:socket.receive() // -> pending promise until read is possible
socket.receive() // -> promise rejection with `EBUSY` error -Note: Due to the nature of Node.js and to avoid blocking the main thread, this method always attempts to read messages with the
ZMQ_DONTWAITflag. It polls asynchronously if reading is not currently possible. This means that all functionality related to timeouts and blocking behaviour is reimplemented in the Node.js bindings. Any differences in behaviour with the native ZMQ library is considered a bug.Returns Promise<Buffer[]>
Resolved with message parts that were successfully read.
send
- send(message, ...options): Promise<void>
Sends a single message or a multipart message on the socket. Queues the message immediately if possible, and returns a resolved promise. If the message cannot be queued because the high water mark has been reached, it will wait asynchronously. The promise will be resolved when the message was queued successfully.
await socket.send("hello world")
await socket.send(["hello", "world"]) -Queueing may fail eventually if the socket has been configured with a sendTimeout.
A call to send() is guaranteed to return with a resolved promise immediately if the message could be queued directly.
Only one asynchronously blocking call to send() may be executed simultaneously. If you call send() again on a socket that is in the mute state it will return a rejected promise with an
EBUSYerror.The reason for disallowing multiple send() calls simultaneously is that it could create an implicit queue of unsendable outgoing messages. This would circumvent the socket's sendHighWaterMark. Such an implementation could even exhaust all system memory and cause the Node.js process to abort.
For most application you should not notice this implementation detail. Only in rare occasions will a call to send() that does not resolve immediately be undesired. Here are some common scenarios:
If you wish to send a message, use
await send(...). ZeroMQ socket types have been carefully designed to give you the correct blocking behaviour on the chosen socket type in almost all cases:If sending is not possible, it is often better to wait than to continue as if nothing happened. For example, on a Request socket, you can only receive a reply once a message has been sent; so waiting until a message could be queued before continuing with the rest of the program (likely to read from the socket) is required.
Certain socket types (such as Router) will always allow queueing messages and
await send(...)won't delay any code that comes after. This makes sense for routers, since typically you don't want a single send operation to stop the handling of other incoming or outgoing messages.
If you wish to send on an occasionally blocking socket (for example on a Router with the Router.mandatory option set, or on a Dealer) and you're 100% certain that dropping a message is better than blocking, then you can set the sendTimeout option to
0to effectively force send() to always resolve immediately. Be prepared to catch exceptions if sending a message is not immediately possible.If you wish to send on a socket and messages should be queued before they are dropped, you should implement a simple queue in JavaScript. Such a queue is not provided by this library because most real world applications need to deal with undeliverable messages in more complex ways - for example, they might need to reply with a status message; or first retry delivery a certain number of times before giving up.
Parameters
- message: MessageLike | MessageLike[]
Single message or multipart message to queue for sending.
Rest...options: []Any options, if applicable to the socket type (DRAFT only).
Returns Promise<void>
Resolved when the message was successfully queued.
ProtectedsetBoolOption
ProtectedsetInt32Option
ProtectedsetInt64Option
ProtectedsetStringOption
ProtectedsetUint32Option
ProtectedsetUint64Option
unbind
- unbind(address): Promise<void>
Unbinds the socket to the given address. During unbind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.Parameters
- address: string
Address to unbind this socket from.
Returns Promise<void>
Resolved when the socket was successfully unbound.
- address: string
Class Router
A Router can be used to extend request/reply sockets. When receiving messages a Router shall prepend a message part containing the routing id of the originating peer to the message. Messages received are fair-queued from among all connected peers. When sending messages, the first part of the message is removed and used to determine the routing id of the peer the message should be routed to.
If the peer does not exist anymore, or has never existed, the message shall be silently discarded. However, if Router.mandatory is set to true, the socket shall fail with a EHOSTUNREACH error in both cases.
When a Router enters the mute state due to having reached the high water mark for all peers, then any messages sent to the socket shall be dropped until the mute state ends. Likewise, any messages routed to a peer for which the individual high water mark has been reached shall also be dropped. If Router.mandatory is set to true the socket shall block or return an EAGAIN error in both cases.
When a Request socket is connected to a Router, in addition to the routing id of the originating peer each message received shall contain an empty delimiter message part. Hence, the entire structure of each received message as seen by the application becomes: one or more routing id parts, delimiter part, one or more body parts. When sending replies to a Request the delimiter part must be included.
Hierarchy (View Summary)
Index
Constructors
Properties
Methods
Constructors
constructor
- new Router(
options?: {
affinity?: number;
backlog?: number;
connectTimeout?: number;
context?: Context;
curvePublicKey?: null | string;
curveSecretKey?: null | string;
curveServer?: boolean;
curveServerKey?: null | string;
gssapiPlainText?: boolean;
gssapiPrincipal?: null | string;
gssapiPrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
gssapiServer?: boolean;
gssapiServicePrincipal?: null | string;
gssapiServicePrincipalNameType?:
| "hostBased"
| "userName"
| "krb5Principal";
handover?: boolean;
handshakeInterval?: number;
heartbeatInterval?: number;
heartbeatTimeout?: number;
heartbeatTimeToLive?: number;
immediate?: boolean;
interface?: null
| string;
ipv6?: boolean;
linger?: number;
loopbackFastPath?: boolean;
mandatory?: boolean;
maxMessageSize?: number;
multicastHops?: number;
multicastMaxTransportDataUnit?: number;
plainPassword?: null | string;
plainServer?: boolean;
plainUsername?: null | string;
probeRouter?: boolean;
rate?: number;
receiveBufferSize?: number;
receiveHighWaterMark?: number;
receiveTimeout?: number;
reconnectInterval?: number;
reconnectMaxInterval?: number;
recoveryInterval?: number;
routingId?: null | string;
sendBufferSize?: number;
sendHighWaterMark?: number;
sendTimeout?: number;
socksProxy?: null | string;
tcpAcceptFilter?: null | string;
tcpKeepalive?: number;
tcpKeepaliveCount?: number;
tcpKeepaliveIdle?: number;
tcpKeepaliveInterval?: number;
tcpMaxRetransmitTimeout?: number;
typeOfService?: number;
vmciBufferMaxSize?: number;
vmciBufferMinSize?: number;
vmciBufferSize?: number;
vmciConnectTimeout?: number;
zapDomain?: null | string;
zapEnforceDomain?: boolean;
},
): Router Parameters
Optionaloptions: {
affinity?: number;
backlog?: number;
connectTimeout?: number;
context?: Context;
curvePublicKey?: null | string;
curveSecretKey?: null | string;
curveServer?: boolean;
curveServerKey?: null | string;
gssapiPlainText?: boolean;
gssapiPrincipal?: null | string;
gssapiPrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
gssapiServer?: boolean;
gssapiServicePrincipal?: null | string;
gssapiServicePrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
handover?: boolean;
handshakeInterval?: number;
heartbeatInterval?: number;
heartbeatTimeout?: number;
heartbeatTimeToLive?: number;
immediate?: boolean;
interface?: null | string;
ipv6?: boolean;
linger?: number;
loopbackFastPath?: boolean;
mandatory?: boolean;
maxMessageSize?: number;
multicastHops?: number;
multicastMaxTransportDataUnit?: number;
plainPassword?: null | string;
plainServer?: boolean;
plainUsername?: null | string;
probeRouter?: boolean;
rate?: number;
receiveBufferSize?: number;
receiveHighWaterMark?: number;
receiveTimeout?: number;
reconnectInterval?: number;
reconnectMaxInterval?: number;
recoveryInterval?: number;
routingId?: null | string;
sendBufferSize?: number;
sendHighWaterMark?: number;
sendTimeout?: number;
socksProxy?: null | string;
tcpAcceptFilter?: null | string;
tcpKeepalive?: number;
tcpKeepaliveCount?: number;
tcpKeepaliveIdle?: number;
tcpKeepaliveInterval?: number;
tcpMaxRetransmitTimeout?: number;
typeOfService?: number;
vmciBufferMaxSize?: number;
vmciBufferMinSize?: number;
vmciBufferSize?: number;
vmciConnectTimeout?: number;
zapDomain?: null | string;
zapEnforceDomain?: boolean;
}Optionalaffinity?: numberZMQ_AFFINITY
I/O thread affinity, which determines which threads from the ØMQ I/O thread pool associated with the socket's context shall handle newly created connections.
Note: This value is a bit mask, but values higher than
Number.MAX_SAFE_INTEGERmay not be represented accurately! This currently means that configurations beyond 52 threads are unreliable.Optionalbacklog?: numberZMQ_BACKLOG
Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.
OptionalconnectTimeout?: numberZMQ_CONNECT_TIMEOUT
Sets how long to wait before timing-out a connect() system call. The connect() system call normally takes a long time before it returns a time out error. Setting this option allows the library to time out the call at an earlier interval.
Optionalcontext?: ContextOptionalcurvePublicKey?: null | stringZMQ_CURVE_PUBLICKEY
Sets the socket's long term public key. You must set this on CURVE client sockets. A server socket does not need to know its own public key. You can create a new keypair with curveKeyPair().
OptionalcurveSecretKey?: null | stringZMQ_CURVE_SECRETKEY
Sets the socket's long term secret key. You must set this on both CURVE client and server sockets. You can create a new keypair with curveKeyPair().
OptionalcurveServer?: booleanZMQ_CURVE_SERVER
Defines whether the socket will act as server for CURVE security. A value of
truemeans the socket will act as CURVE server. A value offalsemeans the socket will not act as CURVE server, and its security role then depends on other option settings.OptionalcurveServerKey?: null | stringZMQ_CURVE_SERVERKEY
Sets the socket's long term server key. This is the public key of the CURVE server socket. You must set this on CURVE client sockets. This key must have been generated together with the server's secret key. You can create a new keypair with curveKeyPair().
OptionalgssapiPlainText?: booleanOptionalgssapiPrincipal?: null | stringOptionalgssapiPrincipalNameType?: "hostBased" | "userName" | "krb5Principal"OptionalgssapiServer?: booleanOptionalgssapiServicePrincipal?: null | stringOptionalgssapiServicePrincipalNameType?: "hostBased" | "userName" | "krb5Principal"Optionalhandover?: booleanZMQ_ROUTER_HANDOVER
If two clients use the same identity when connecting to a Router, the results shall depend on the this option. If it set to
false(default), the Router socket shall reject clients trying to connect with an already-used identity. If it is set totrue, the Router socket shall hand-over the connection to the new client and disconnect the existing one.OptionalhandshakeInterval?: numberZMQ_HANDSHAKE_IVL
Handshaking is the exchange of socket configuration information (socket type, identity, security) that occurs when a connection is first opened (only for connection-oriented transports). If handshaking does not complete within the configured time, the connection shall be closed. The value 0 means no handshake time limit.
OptionalheartbeatInterval?: numberZMQ_HEARTBEAT_IVL
Interval in milliseconds between sending ZMTP heartbeats for the specified socket. If this option is greater than 0, then a PING ZMTP command will be sent after every interval.
OptionalheartbeatTimeout?: numberZMQ_HEARTBEAT_TIMEOUT
How long (in milliseconds) to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic. This option is only valid if heartbeatInterval is greater than 0. The connection will time out if there is no traffic received after sending the PING command. The received traffic does not have to be a PONG command - any received traffic will cancel the timeout.
OptionalheartbeatTimeToLive?: numberZMQ_HEARTBEAT_TTL
The timeout in milliseconds on the remote peer for ZMTP heartbeats. If this option is greater than 0, the remote side shall time out the connection if it does not receive any more traffic within the TTL period. This option does not have any effect if heartbeatInterval is 0. Internally, this value is rounded down to the nearest decisecond, any value less than 100 will have no effect.
Optionalimmediate?: booleanZMQ_IMMEDIATE
By default queues will fill on outgoing connections even if the connection has not completed. This can lead to "lost" messages on sockets with round-robin routing (Request, Push, Dealer). If this option is set to
true, messages shall be queued only to completed connections. This will cause the socket to block if there are no other connections, but will prevent queues from filling on pipes awaiting connection.Optionalinterface?: null | stringZMQ_BINDTODEVICE
Binds the socket to the given network interface (Linux only). Allows to use Linux VRF, see: https://www.kernel.org/doc/Documentation/networking/vrf.txt. Requires the program to be ran as root or with
CAP_NET_RAW.Optionalipv6?: booleanZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
Optionallinger?: numberZMQ_LINGER
Determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with close().
OptionalloopbackFastPath?: booleanZMQ_LOOPBACK_FASTPATH
Enable faster TCP connections on loopback devices. An application can enable this option to reduce the latency and improve the performance of loopback operations on a TCP socket on Windows.
Optionalmandatory?: booleanZMQ_ROUTER_MANDATORY
A value of
falseis the default and discards the message silently when it cannot be routed or the peer's high water mark is reached. A value oftruecauses send() to fail if it cannot be routed, or wait asynchronously if the high water mark is reached.OptionalmaxMessageSize?: numberZMQ_MAXMSGSIZE
Limits the size of the inbound message. If a peer sends a message larger than the limit it is disconnected. Value of -1 means no limit.
OptionalmulticastHops?: numberZMQ_MULTICAST_HOPS
Sets the time-to-live field in every multicast packet sent from this socket. The default is 1 which means that the multicast packets don't leave the local network.
OptionalmulticastMaxTransportDataUnit?: numberZMQ_MULTICAST_MAXTPDU
Sets the maximum transport data unit size used for outbound multicast packets. This must be set at or below the minimum Maximum Transmission Unit (MTU) for all network paths over which multicast reception is required.
OptionalplainPassword?: null | stringZMQ_PLAIN_PASSWORD
Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
OptionalplainServer?: booleanZMQ_PLAIN_SERVER
Defines whether the socket will act as server for PLAIN security. A value of
truemeans the socket will act as PLAIN server. A value offalsemeans the socket will not act as PLAIN server, and its security role then depends on other option settings.OptionalplainUsername?: null | stringZMQ_PLAIN_USERNAME
Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
OptionalprobeRouter?: booleanZMQ_PROBE_ROUTER
When set to
true, the socket will automatically send an empty message when a new connection is made or accepted. You may set this on sockets connected to a Router socket. The application must filter such empty messages. This option provides the Router with an event signaling the arrival of a new peer.Warning:* Do not set this option on a socket that talks to any other socket type except Router: the results are undefined.
Optionalrate?: numberZMQ_RATE
Maximum send or receive data rate for multicast transports such as
pgm.OptionalreceiveBufferSize?: numberZMQ_RCVBUF
Underlying kernel receive buffer size in bytes. A value of -1 means leave the OS default unchanged.
OptionalreceiveHighWaterMark?: numberZMQ_RCVHWM
The high water mark is a hard limit on the maximum number of incoming messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
OptionalreceiveTimeout?: numberZMQ_RCVTIMEO
Sets the timeout receiving messages on the socket. If the value is 0, receive() will return a rejected promise immediately if there is no message to receive. If the value is -1, it will wait asynchronously until a message is available. For all other values, it will wait for a message for that amount of time before rejecting.
OptionalreconnectInterval?: numberZMQ_RECONNECT_IVL
Period ØMQ shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. The value -1 means no reconnection.
OptionalreconnectMaxInterval?: numberZMQ_RECONNECT_IVL_MAX
Maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled until reconnectMaxInterval is reached. This allows for exponential backoff strategy. Zero (the default) means no exponential backoff is performed and reconnect interval calculations are only based on reconnectInterval.
OptionalrecoveryInterval?: numberZMQ_RECOVERY_IVL
Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
OptionalroutingId?: null | stringZMQ_ROUTING_ID
The identity of the specified socket when connecting to a
Routersocket.OptionalsendBufferSize?: numberZMQ_SNDBUF
Underlying kernel transmit buffer size in bytes. A value of -1 means leave the OS default unchanged.
OptionalsendHighWaterMark?: numberZMQ_SNDHWM
The high water mark is a hard limit on the maximum number of outgoing messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
OptionalsendTimeout?: numberZMQ_SNDTIMEO
Sets the timeout for sending messages on the socket. If the value is 0, send() will return a rejected promise immediately if the message cannot be sent. If the value is -1, it will wait asynchronously until the message is sent. For all other values, it will try to send the message for that amount of time before rejecting.
OptionalsocksProxy?: null | stringZMQ_SOCKS_PROXY
The SOCKS5 proxy address that shall be used by the socket for the TCP connection(s). Does not support SOCKS5 authentication. If the endpoints are domain names instead of addresses they shall not be resolved and they shall be forwarded unchanged to the SOCKS proxy service in the client connection request message (address type 0x03 domain name).
OptionaltcpAcceptFilter?: null | stringZMQ_TCP_ACCEPT_FILTER
Assign a filter that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one filter is applied then new connection source IP should be matched. To clear all filters set to
null. Filter is a string with IPv6 or IPv4 CIDR.OptionaltcpKeepalive?: numberZMQ_TCP_KEEPALIVE
Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepaliveCount?: numberZMQ_TCP_KEEPALIVE_CNT
Overrides TCP_KEEPCNT socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepaliveIdle?: numberZMQ_TCP_KEEPALIVE_IDLE
Overrides TCP_KEEPIDLE / TCP_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepaliveInterval?: numberZMQ_TCP_KEEPALIVE_INTVL
Overrides TCP_KEEPINTVL socket option (if supported by the OS). The default value of -1 leaves it to the OS default.
OptionaltcpMaxRetransmitTimeout?: numberZMQ_TCP_MAXRT
Sets how long before an unacknowledged TCP retransmit times out (if supported by the OS). The system normally attempts many TCP retransmits following an exponential backoff strategy. This means that after a network outage, it may take a long time before the session can be re-established. Setting this option allows the timeout to happen at a shorter interval.
OptionaltypeOfService?: numberZMQ_TOS
Sets the ToS fields (the Differentiated Services (DS) and Explicit Congestion Notification (ECN) field) of the IP header. The ToS field is typically used to specify a packet's priority. The availability of this option is dependent on intermediate network equipment that inspect the ToS field and provide a path for low-delay, high-throughput, highly-reliable service, etc.
OptionalvmciBufferMaxSize?: numberZMQ_VMCI_BUFFER_MAX_SIZE
Maximum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciBufferMinSize?: numberZMQ_VMCI_BUFFER_MIN_SIZE
Minimum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciBufferSize?: numberZMQ_VMCI_BUFFER_SIZE
The size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciConnectTimeout?: numberZMQ_VMCI_CONNECT_TIMEOUT
Connection timeout for the socket. For
vmci://transports only.OptionalzapDomain?: null | stringZMQ_ZAP_DOMAIN
Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the default on all
tcp://connections), ZAP authentication only happens if you set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 for more details.OptionalzapEnforceDomain?: booleanZMQ_ZAP_ENFORCE_DOMAIN
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.
Returns Router
Properties
affinity
ZMQ_AFFINITY
I/O thread affinity, which determines which threads from the ØMQ I/O thread pool associated with the socket's context shall handle newly created connections.
Note: This value is a bit mask, but values higher than Number.MAX_SAFE_INTEGER may not be represented accurately! This currently means that configurations beyond 52 threads are unreliable.
backlog
ZMQ_BACKLOG
Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.
Readonlyclosed
Whether this socket was previously closed with close().
connectTimeout
ZMQ_CONNECT_TIMEOUT
Sets how long to wait before timing-out a connect() system call. The connect() system call normally takes a long time before it returns a time out error. Setting this option allows the library to time out the call at an earlier interval.
Readonlycontext
Context that this socket belongs to.
curvePublicKey
ZMQ_CURVE_PUBLICKEY
Sets the socket's long term public key. You must set this on CURVE client sockets. A server socket does not need to know its own public key. You can create a new keypair with curveKeyPair().
curveSecretKey
ZMQ_CURVE_SECRETKEY
Sets the socket's long term secret key. You must set this on both CURVE client and server sockets. You can create a new keypair with curveKeyPair().
curveServer
ZMQ_CURVE_SERVER
Defines whether the socket will act as server for CURVE security. A value of true means the socket will act as CURVE server. A value of false means the socket will not act as CURVE server, and its security role then depends on other option settings.
curveServerKey
ZMQ_CURVE_SERVERKEY
Sets the socket's long term server key. This is the public key of the CURVE server socket. You must set this on CURVE client sockets. This key must have been generated together with the server's secret key. You can create a new keypair with curveKeyPair().
Readonlyevents
Event Observer for this socket. This starts up a ØMQ monitoring socket internally that receives all socket events.
gssapiPlainText
gssapiPrincipal
gssapiPrincipalNameType
gssapiServer
gssapiServicePrincipal
gssapiServicePrincipalNameType
handover
ZMQ_ROUTER_HANDOVER
If two clients use the same identity when connecting to a Router, the results shall depend on the this option. If it set to false (default), the Router socket shall reject clients trying to connect with an already-used identity. If it is set to true, the Router socket shall hand-over the connection to the new client and disconnect the existing one.
handshakeInterval
ZMQ_HANDSHAKE_IVL
Handshaking is the exchange of socket configuration information (socket type, identity, security) that occurs when a connection is first opened (only for connection-oriented transports). If handshaking does not complete within the configured time, the connection shall be closed. The value 0 means no handshake time limit.
heartbeatInterval
ZMQ_HEARTBEAT_IVL
Interval in milliseconds between sending ZMTP heartbeats for the specified socket. If this option is greater than 0, then a PING ZMTP command will be sent after every interval.
heartbeatTimeout
ZMQ_HEARTBEAT_TIMEOUT
How long (in milliseconds) to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic. This option is only valid if heartbeatInterval is greater than 0. The connection will time out if there is no traffic received after sending the PING command. The received traffic does not have to be a PONG command - any received traffic will cancel the timeout.
heartbeatTimeToLive
ZMQ_HEARTBEAT_TTL
The timeout in milliseconds on the remote peer for ZMTP heartbeats. If this option is greater than 0, the remote side shall time out the connection if it does not receive any more traffic within the TTL period. This option does not have any effect if heartbeatInterval is 0. Internally, this value is rounded down to the nearest decisecond, any value less than 100 will have no effect.
immediate
ZMQ_IMMEDIATE
By default queues will fill on outgoing connections even if the connection has not completed. This can lead to "lost" messages on sockets with round-robin routing (Request, Push, Dealer). If this option is set to true, messages shall be queued only to completed connections. This will cause the socket to block if there are no other connections, but will prevent queues from filling on pipes awaiting connection.
interface
ZMQ_BINDTODEVICE
Binds the socket to the given network interface (Linux only). Allows to use Linux VRF, see: https://www.kernel.org/doc/Documentation/networking/vrf.txt. Requires the program to be ran as root or with CAP_NET_RAW.
ipv6
ZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
ReadonlylastEndpoint
ZMQ_LAST_ENDPOINT
The last endpoint bound for TCP and IPC transports.
linger
ZMQ_LINGER
Determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with close().
loopbackFastPath
ZMQ_LOOPBACK_FASTPATH
Enable faster TCP connections on loopback devices. An application can enable this option to reduce the latency and improve the performance of loopback operations on a TCP socket on Windows.
mandatory
ZMQ_ROUTER_MANDATORY
A value of false is the default and discards the message silently when it cannot be routed or the peer's high water mark is reached. A value of true causes send() to fail if it cannot be routed, or wait asynchronously if the high water mark is reached.
maxMessageSize
ZMQ_MAXMSGSIZE
Limits the size of the inbound message. If a peer sends a message larger than the limit it is disconnected. Value of -1 means no limit.
multicastHops
ZMQ_MULTICAST_HOPS
Sets the time-to-live field in every multicast packet sent from this socket. The default is 1 which means that the multicast packets don't leave the local network.
multicastMaxTransportDataUnit
ZMQ_MULTICAST_MAXTPDU
Sets the maximum transport data unit size used for outbound multicast packets. This must be set at or below the minimum Maximum Transmission Unit (MTU) for all network paths over which multicast reception is required.
plainPassword
ZMQ_PLAIN_PASSWORD
Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
plainServer
ZMQ_PLAIN_SERVER
Defines whether the socket will act as server for PLAIN security. A value of true means the socket will act as PLAIN server. A value of false means the socket will not act as PLAIN server, and its security role then depends on other option settings.
plainUsername
ZMQ_PLAIN_USERNAME
Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
probeRouter
ZMQ_PROBE_ROUTER
When set to true, the socket will automatically send an empty message when a new connection is made or accepted. You may set this on sockets connected to a Router socket. The application must filter such empty messages. This option provides the Router with an event signaling the arrival of a new peer.
Warning:* Do not set this option on a socket that talks to any other socket type except Router: the results are undefined.
rate
ZMQ_RATE
Maximum send or receive data rate for multicast transports such as pgm.
Readonlyreadable
Whether any messages are currently available. If true, the next call to Readable.receive() will immediately read a message from the socket. For sockets that cannot receive messsages this is always false.
receiveBufferSize
ZMQ_RCVBUF
Underlying kernel receive buffer size in bytes. A value of -1 means leave the OS default unchanged.
receiveHighWaterMark
ZMQ_RCVHWM
The high water mark is a hard limit on the maximum number of incoming messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
receiveTimeout
ZMQ_RCVTIMEO
Sets the timeout receiving messages on the socket. If the value is 0, receive() will return a rejected promise immediately if there is no message to receive. If the value is -1, it will wait asynchronously until a message is available. For all other values, it will wait for a message for that amount of time before rejecting.
reconnectInterval
ZMQ_RECONNECT_IVL
Period ØMQ shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. The value -1 means no reconnection.
reconnectMaxInterval
ZMQ_RECONNECT_IVL_MAX
Maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled until reconnectMaxInterval is reached. This allows for exponential backoff strategy. Zero (the default) means no exponential backoff is performed and reconnect interval calculations are only based on reconnectInterval.
recoveryInterval
ZMQ_RECOVERY_IVL
Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
routingId
ZMQ_ROUTING_ID
The identity of the specified socket when connecting to a Router socket.
ReadonlysecurityMechanism
ZMQ_MECHANISM
Returns the current security mechanism for the socket, if any. The security mechanism is set implictly by using any of the relevant security options. The returned value is one of:
null- No security mechanism is used."plain"- The PLAIN mechanism defines a simple username/password mechanism that lets a server authenticate a client. PLAIN makes no attempt at security or confidentiality."curve"- The CURVE mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server. CURVE is intended for use on public networks."gssapi"- The GSSAPI mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server using the Generic Security Service Application Program Interface (GSSAPI). The GSSAPI mechanism can be used on both public and private networks.
sendBufferSize
ZMQ_SNDBUF
Underlying kernel transmit buffer size in bytes. A value of -1 means leave the OS default unchanged.
sendHighWaterMark
ZMQ_SNDHWM
The high water mark is a hard limit on the maximum number of outgoing messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
sendTimeout
ZMQ_SNDTIMEO
Sets the timeout for sending messages on the socket. If the value is 0, send() will return a rejected promise immediately if the message cannot be sent. If the value is -1, it will wait asynchronously until the message is sent. For all other values, it will try to send the message for that amount of time before rejecting.
socksProxy
ZMQ_SOCKS_PROXY
The SOCKS5 proxy address that shall be used by the socket for the TCP connection(s). Does not support SOCKS5 authentication. If the endpoints are domain names instead of addresses they shall not be resolved and they shall be forwarded unchanged to the SOCKS proxy service in the client connection request message (address type 0x03 domain name).
tcpAcceptFilter
ZMQ_TCP_ACCEPT_FILTER
Assign a filter that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one filter is applied then new connection source IP should be matched. To clear all filters set to null. Filter is a string with IPv6 or IPv4 CIDR.
tcpKeepalive
ZMQ_TCP_KEEPALIVE
Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveCount
ZMQ_TCP_KEEPALIVE_CNT
Overrides TCP_KEEPCNT socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveIdle
ZMQ_TCP_KEEPALIVE_IDLE
Overrides TCP_KEEPIDLE / TCP_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveInterval
ZMQ_TCP_KEEPALIVE_INTVL
Overrides TCP_KEEPINTVL socket option (if supported by the OS). The default value of -1 leaves it to the OS default.
tcpMaxRetransmitTimeout
ZMQ_TCP_MAXRT
Sets how long before an unacknowledged TCP retransmit times out (if supported by the OS). The system normally attempts many TCP retransmits following an exponential backoff strategy. This means that after a network outage, it may take a long time before the session can be re-established. Setting this option allows the timeout to happen at a shorter interval.
ReadonlythreadSafe
ZMQ_THREAD_SAFE
Whether or not the socket is threadsafe. Currently only DRAFT sockets is thread-safe.
Readonlytype
ZMQ_TYPE
Retrieve the socket type. This is fairly useless because you can test the socket class with e.g. socket instanceof Dealer.
typeOfService
ZMQ_TOS
Sets the ToS fields (the Differentiated Services (DS) and Explicit Congestion Notification (ECN) field) of the IP header. The ToS field is typically used to specify a packet's priority. The availability of this option is dependent on intermediate network equipment that inspect the ToS field and provide a path for low-delay, high-throughput, highly-reliable service, etc.
vmciBufferMaxSize
ZMQ_VMCI_BUFFER_MAX_SIZE
Maximum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferMinSize
ZMQ_VMCI_BUFFER_MIN_SIZE
Minimum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferSize
ZMQ_VMCI_BUFFER_SIZE
The size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciConnectTimeout
ZMQ_VMCI_CONNECT_TIMEOUT
Connection timeout for the socket. For vmci:// transports only.
Readonlywritable
Whether any messages can be queued for sending. If true, the next call to Writable.send() will immediately queue a message on the socket. For sockets that cannot send messsages this is always false.
zapDomain
ZMQ_ZAP_DOMAIN
Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the default on all tcp:// connections), ZAP authentication only happens if you set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 for more details.
zapEnforceDomain
ZMQ_ZAP_ENFORCE_DOMAIN
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.
Methods
[asyncIterator]
- "[asyncIterator]"(): AsyncIterator<Buffer[]>
Asynchronously iterate over messages becoming available on the socket. When the socket is closed with Socket.close(), the iterator will return. Returning early from the iterator will not close the socket unless it also goes out of scope.
for await (const [msg] of socket) {
// handle messages
} +Returns AsyncIterator<Buffer[]>
bind
- bind(address: string): Promise<void>
Binds the socket to the given address. During bind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.You can use
*in place of a hostname to bind on all interfaces/addresses, and you can use*in place of a port to bind to a random port (which can be retrieved with lastEndpoint later).await socket.bind("tcp://127.0.0.1:3456")
await socket.bind("tcp://*:3456") // binds on all interfaces
await socket.bind("tcp://127.0.0.1:*") // binds on random port +Parameters
- address: string
Address to bind this socket to.
Returns Promise<void>
Resolved when the socket was successfully bound.
- address: string
bindSync
- bindSync(address: string): void
Binds the socket to the given address. During bind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.You can use
*in place of a hostname to bind on all interfaces/addresses, and you can use*in place of a port to bind to a random port (which can be retrieved with lastEndpoint later).socket.bindSync("tcp://127.0.0.1:3456")
socket.bindSync("tcp://*:3456") // binds on all interfaces
socket.bindSync("tcp://127.0.0.1:*") // binds on random port +Parameters
- address: string
Address to bind this socket to.
Returns void
Resolved when the socket was successfully bound.
- address: string
close
- close(): void
Closes the socket and disposes of all resources. Any messages that are queued may be discarded or sent in the background depending on the linger setting.
After this method is called, it is no longer possible to call any other methods on this socket.
Sockets that go out of scope and have no Readable.receive() or Writable.send() operations in progress will automatically be closed. Therefore it is not necessary in most applications to call close() manually.
Calling this method on a socket that is already closed is a no-op.
Returns void
connect
- connect(address: string, options?: RouterConnectOptions): void
Connects to the given remote address. To specificy a specific routing id, provide a
routingIdoption. The identity should be unique, from 1 to 255 bytes long and MAY NOT start with binary zero.Parameters
- address: string
The
tcp://address to connect to. - options: RouterConnectOptions = {}
Any connection options.
Returns void
- address: string
disconnect
- disconnect(address: string): void
Disconnects a previously connected socket from the given address and returns immediately. Disonnection will happen asynchronously in the background.
socket.disconnect("tcp://127.0.0.1:3456") +Parameters
- address: string
The previously connected address to disconnect from.
Returns void
- address: string
ProtectedgetBoolOption
ProtectedgetInt32Option
ProtectedgetInt64Option
ProtectedgetStringOption
ProtectedgetUint32Option
ProtectedgetUint64Option
receive
- receive(): Promise<Buffer[]>
Waits for the next single or multipart message to become availeble on the socket. Reads a message immediately if possible. If no messages can be read, it will wait asynchonously. The promise will be resolved with an array containing the parts of the next message when available.
const [msg] = await socket.receive()
const [part1, part2] = await socket.receive() +Reading may fail (eventually) if the socket has been configured with a receiveTimeout.
A call to receive() is guaranteed to return with a resolved promise immediately if a message could be read from the socket directly.
Only one asynchronously blocking call to receive() can be in progress simultaneously. If you call receive() again on the same socket it will return a rejected promise with an
EBUSYerror. For example, if no messages can be read and noawaitis used:socket.receive() // -> pending promise until read is possible
socket.receive() // -> promise rejection with `EBUSY` error +Note: Due to the nature of Node.js and to avoid blocking the main thread, this method always attempts to read messages with the
ZMQ_DONTWAITflag. It polls asynchronously if reading is not currently possible. This means that all functionality related to timeouts and blocking behaviour is reimplemented in the Node.js bindings. Any differences in behaviour with the native ZMQ library is considered a bug.Returns Promise<Buffer[]>
Resolved with message parts that were successfully read.
send
- send(message: MessageLike | MessageLike[], ...options: []): Promise<void>
Sends a single message or a multipart message on the socket. Queues the message immediately if possible, and returns a resolved promise. If the message cannot be queued because the high water mark has been reached, it will wait asynchronously. The promise will be resolved when the message was queued successfully.
await socket.send("hello world")
await socket.send(["hello", "world"]) +Queueing may fail eventually if the socket has been configured with a sendTimeout.
A call to send() is guaranteed to return with a resolved promise immediately if the message could be queued directly.
Only one asynchronously blocking call to send() may be executed simultaneously. If you call send() again on a socket that is in the mute state it will return a rejected promise with an
EBUSYerror.The reason for disallowing multiple send() calls simultaneously is that it could create an implicit queue of unsendable outgoing messages. This would circumvent the socket's sendHighWaterMark. Such an implementation could even exhaust all system memory and cause the Node.js process to abort.
For most application you should not notice this implementation detail. Only in rare occasions will a call to send() that does not resolve immediately be undesired. Here are some common scenarios:
If you wish to send a message, use
await send(...). ZeroMQ socket types have been carefully designed to give you the correct blocking behaviour on the chosen socket type in almost all cases:If sending is not possible, it is often better to wait than to continue as if nothing happened. For example, on a Request socket, you can only receive a reply once a message has been sent; so waiting until a message could be queued before continuing with the rest of the program (likely to read from the socket) is required.
Certain socket types (such as Router) will always allow queueing messages and
await send(...)won't delay any code that comes after. This makes sense for routers, since typically you don't want a single send operation to stop the handling of other incoming or outgoing messages.
If you wish to send on an occasionally blocking socket (for example on a Router with the Router.mandatory option set, or on a Dealer) and you're 100% certain that dropping a message is better than blocking, then you can set the sendTimeout option to
0to effectively force send() to always resolve immediately. Be prepared to catch exceptions if sending a message is not immediately possible.If you wish to send on a socket and messages should be queued before they are dropped, you should implement a simple queue in JavaScript. Such a queue is not provided by this library because most real world applications need to deal with undeliverable messages in more complex ways - for example, they might need to reply with a status message; or first retry delivery a certain number of times before giving up.
Parameters
- message: MessageLike | MessageLike[]
Single message or multipart message to queue for sending.
- ...options: []
Any options, if applicable to the socket type (DRAFT only).
Returns Promise<void>
Resolved when the message was successfully queued.
ProtectedsetBoolOption
ProtectedsetInt32Option
ProtectedsetInt64Option
ProtectedsetStringOption
ProtectedsetUint32Option
ProtectedsetUint64Option
unbind
- unbind(address: string): Promise<void>
Unbinds the socket to the given address. During unbind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.Parameters
- address: string
Address to unbind this socket from.
Returns Promise<void>
Resolved when the socket was successfully unbound.
- address: string
unbindSync
- unbindSync(address: string): void
Unbinds the socket to the given address. During unbind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.Parameters
- address: string
Address to unbind this socket from.
Returns void
Resolved when the socket was successfully unbound.
- address: string
Class SocketAbstract
A ØMQ socket. This class should generally not be used directly. Instead, create one of its subclasses that corresponds to the socket type you want to use.
new zmq.Pair(...)
new zmq.Publisher(...)
new zmq.Subscriber(...)
new zmq.Request(...)
new zmq.Reply(...)
new zmq.Dealer(...)
new zmq.Router(...)
new zmq.Pull(...)
new zmq.Push(...)
new zmq.XPublisher(...)
new zmq.XSubscriber(...)
new zmq.Stream(...)
-Socket options can be set during construction or via a property after the socket was created. Most socket options do not take effect until the next bind() or connect() call. Setting such an option after the socket is already connected or bound will display a warning.
Hierarchy (view full)
Index
Constructors
Properties
Methods
Properties
affinity
ZMQ_AFFINITY
I/O thread affinity, which determines which threads from the ØMQ I/O thread pool associated with the socket's context shall handle newly created connections.
Note: This value is a bit mask, but values higher than Number.MAX_SAFE_INTEGER may not be represented accurately! This currently means that configurations beyond 52 threads are unreliable.
backlog
ZMQ_BACKLOG
Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.
Readonlyclosed
Whether this socket was previously closed with close().
connectTimeout
ZMQ_CONNECT_TIMEOUT
Sets how long to wait before timing-out a connect() system call. The connect() system call normally takes a long time before it returns a time out error. Setting this option allows the library to time out the call at an earlier interval.
Readonlycontext
Context that this socket belongs to.
curvePublicKey
ZMQ_CURVE_PUBLICKEY
Sets the socket's long term public key. You must set this on CURVE client sockets. A server socket does not need to know its own public key. You can create a new keypair with curveKeyPair().
curveSecretKey
ZMQ_CURVE_SECRETKEY
Sets the socket's long term secret key. You must set this on both CURVE client and server sockets. You can create a new keypair with curveKeyPair().
curveServer
ZMQ_CURVE_SERVER
Defines whether the socket will act as server for CURVE security. A value of true means the socket will act as CURVE server. A value of false means the socket will not act as CURVE server, and its security role then depends on other option settings.
curveServerKey
ZMQ_CURVE_SERVERKEY
Sets the socket's long term server key. This is the public key of the CURVE server socket. You must set this on CURVE client sockets. This key must have been generated together with the server's secret key. You can create a new keypair with curveKeyPair().
Readonlyevents
Event Observer for this socket. This starts up a ØMQ monitoring socket internally that receives all socket events.
gssapiPlainText
gssapiPrincipal
gssapiPrincipalNameType
gssapiServer
gssapiServicePrincipal
gssapiServicePrincipalNameType
handshakeInterval
ZMQ_HANDSHAKE_IVL
Handshaking is the exchange of socket configuration information (socket type, identity, security) that occurs when a connection is first opened (only for connection-oriented transports). If handshaking does not complete within the configured time, the connection shall be closed. The value 0 means no handshake time limit.
heartbeatInterval
ZMQ_HEARTBEAT_IVL
Interval in milliseconds between sending ZMTP heartbeats for the specified socket. If this option is greater than 0, then a PING ZMTP command will be sent after every interval.
heartbeatTimeout
ZMQ_HEARTBEAT_TIMEOUT
How long (in milliseconds) to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic. This option is only valid if heartbeatInterval is greater than 0. The connection will time out if there is no traffic received after sending the PING command. The received traffic does not have to be a PONG command - any received traffic will cancel the timeout.
heartbeatTimeToLive
ZMQ_HEARTBEAT_TTL
The timeout in milliseconds on the remote peer for ZMTP heartbeats. If this option is greater than 0, the remote side shall time out the connection if it does not receive any more traffic within the TTL period. This option does not have any effect if heartbeatInterval is 0. Internally, this value is rounded down to the nearest decisecond, any value less than 100 will have no effect.
immediate
ZMQ_IMMEDIATE
By default queues will fill on outgoing connections even if the connection has not completed. This can lead to "lost" messages on sockets with round-robin routing (Request, Push, Dealer). If this option is set to true, messages shall be queued only to completed connections. This will cause the socket to block if there are no other connections, but will prevent queues from filling on pipes awaiting connection.
interface
ZMQ_BINDTODEVICE
Binds the socket to the given network interface (Linux only). Allows to use Linux VRF, see: https://www.kernel.org/doc/Documentation/networking/vrf.txt. Requires the program to be ran as root or with CAP_NET_RAW.
ipv6
ZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
ReadonlylastEndpoint
ZMQ_LAST_ENDPOINT
The last endpoint bound for TCP and IPC transports.
linger
ZMQ_LINGER
Determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with close().
loopbackFastPath
ZMQ_LOOPBACK_FASTPATH
Enable faster TCP connections on loopback devices. An application can enable this option to reduce the latency and improve the performance of loopback operations on a TCP socket on Windows.
maxMessageSize
ZMQ_MAXMSGSIZE
Limits the size of the inbound message. If a peer sends a message larger than the limit it is disconnected. Value of -1 means no limit.
multicastMaxTransportDataUnit
ZMQ_MULTICAST_MAXTPDU
Sets the maximum transport data unit size used for outbound multicast packets. This must be set at or below the minimum Maximum Transmission Unit (MTU) for all network paths over which multicast reception is required.
plainPassword
ZMQ_PLAIN_PASSWORD
Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
plainServer
ZMQ_PLAIN_SERVER
Defines whether the socket will act as server for PLAIN security. A value of true means the socket will act as PLAIN server. A value of false means the socket will not act as PLAIN server, and its security role then depends on other option settings.
plainUsername
ZMQ_PLAIN_USERNAME
Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
rate
ZMQ_RATE
Maximum send or receive data rate for multicast transports such as pgm.
Readonlyreadable
Whether any messages are currently available. If true, the next call to Readable.receive() will immediately read a message from the socket. For sockets that cannot receive messsages this is always false.
reconnectInterval
ZMQ_RECONNECT_IVL
Period ØMQ shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. The value -1 means no reconnection.
reconnectMaxInterval
ZMQ_RECONNECT_IVL_MAX
Maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled until reconnectMaxInterval is reached. This allows for exponential backoff strategy. Zero (the default) means no exponential backoff is performed and reconnect interval calculations are only based on reconnectInterval.
recoveryInterval
ZMQ_RECOVERY_IVL
Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
ReadonlysecurityMechanism
| null
| "plain"
| "curve"
| "gssapi"
ZMQ_MECHANISM
Returns the current security mechanism for the socket, if any. The security mechanism is set implictly by using any of the relevant security options. The returned value is one of:
null- No security mechanism is used."plain"- The PLAIN mechanism defines a simple username/password mechanism that lets a server authenticate a client. PLAIN makes no attempt at security or confidentiality."curve"- The CURVE mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server. CURVE is intended for use on public networks."gssapi"- The GSSAPI mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server using the Generic Security Service Application Program Interface (GSSAPI). The GSSAPI mechanism can be used on both public and private networks.
socksProxy
ZMQ_SOCKS_PROXY
The SOCKS5 proxy address that shall be used by the socket for the TCP connection(s). Does not support SOCKS5 authentication. If the endpoints are domain names instead of addresses they shall not be resolved and they shall be forwarded unchanged to the SOCKS proxy service in the client connection request message (address type 0x03 domain name).
tcpAcceptFilter
ZMQ_TCP_ACCEPT_FILTER
Assign a filter that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one filter is applied then new connection source IP should be matched. To clear all filters set to null. Filter is a string with IPv6 or IPv4 CIDR.
tcpKeepalive
ZMQ_TCP_KEEPALIVE
Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveCount
ZMQ_TCP_KEEPALIVE_CNT
Overrides TCP_KEEPCNT socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveIdle
ZMQ_TCP_KEEPALIVE_IDLE
Overrides TCP_KEEPIDLE / TCP_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveInterval
ZMQ_TCP_KEEPALIVE_INTVL
Overrides TCP_KEEPINTVL socket option (if supported by the OS). The default value of -1 leaves it to the OS default.
tcpMaxRetransmitTimeout
ZMQ_TCP_MAXRT
Sets how long before an unacknowledged TCP retransmit times out (if supported by the OS). The system normally attempts many TCP retransmits following an exponential backoff strategy. This means that after a network outage, it may take a long time before the session can be re-established. Setting this option allows the timeout to happen at a shorter interval.
ReadonlythreadSafe
ZMQ_THREAD_SAFE
Whether or not the socket is threadsafe. Currently only DRAFT sockets is thread-safe.
Readonlytype
ZMQ_TYPE
Retrieve the socket type. This is fairly useless because you can test the socket class with e.g. socket instanceof Dealer.
typeOfService
ZMQ_TOS
Sets the ToS fields (the Differentiated Services (DS) and Explicit Congestion Notification (ECN) field) of the IP header. The ToS field is typically used to specify a packet's priority. The availability of this option is dependent on intermediate network equipment that inspect the ToS field and provide a path for low-delay, high-throughput, highly-reliable service, etc.
vmciBufferMaxSize
ZMQ_VMCI_BUFFER_MAX_SIZE
Maximum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferMinSize
ZMQ_VMCI_BUFFER_MIN_SIZE
Minimum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferSize
ZMQ_VMCI_BUFFER_SIZE
The size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciConnectTimeout
ZMQ_VMCI_CONNECT_TIMEOUT
Connection timeout for the socket. For vmci:// transports only.
Readonlywritable
Whether any messages can be queued for sending. If true, the next call to Writable.send() will immediately queue a message on the socket. For sockets that cannot send messsages this is always false.
zapDomain
ZMQ_ZAP_DOMAIN
Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the default on all tcp:// connections), ZAP authentication only happens if you set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 for more details.
zapEnforceDomain
ZMQ_ZAP_ENFORCE_DOMAIN
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.
Methods
bind
- bind(address): Promise<void>
Binds the socket to the given address. During bind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.You can use
*in place of a hostname to bind on all interfaces/addresses, and you can use*in place of a port to bind to a random port (which can be retrieved with lastEndpoint later).await socket.bind("tcp://127.0.0.1:3456")
await socket.bind("tcp://*:3456") // binds on all interfaces
await socket.bind("tcp://127.0.0.1:*") // binds on random port -Parameters
- address: string
Address to bind this socket to.
Returns Promise<void>
Resolved when the socket was successfully bound.
- address: string
close
- close(): void
Closes the socket and disposes of all resources. Any messages that are queued may be discarded or sent in the background depending on the linger setting.
After this method is called, it is no longer possible to call any other methods on this socket.
Sockets that go out of scope and have no Readable.receive() or Writable.send() operations in progress will automatically be closed. Therefore it is not necessary in most applications to call close() manually.
Calling this method on a socket that is already closed is a no-op.
Returns void
connect
disconnect
- disconnect(address): void
Disconnects a previously connected socket from the given address and returns immediately. Disonnection will happen asynchronously in the background.
socket.disconnect("tcp://127.0.0.1:3456") -Parameters
- address: string
The previously connected address to disconnect from.
Returns void
- address: string
ProtectedgetBoolOption
ProtectedgetInt32Option
ProtectedgetInt64Option
ProtectedgetStringOption
ProtectedgetUint32Option
ProtectedgetUint64Option
ProtectedsetBoolOption
ProtectedsetInt32Option
ProtectedsetInt64Option
ProtectedsetStringOption
ProtectedsetUint32Option
ProtectedsetUint64Option
unbind
- unbind(address): Promise<void>
Unbinds the socket to the given address. During unbind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.Parameters
- address: string
Address to unbind this socket from.
Returns Promise<void>
Resolved when the socket was successfully unbound.
- address: string
Class SocketAbstract
A ØMQ socket. This class should generally not be used directly. Instead, create one of its subclasses that corresponds to the socket type you want to use.
new zmq.Pair(...)
new zmq.Publisher(...)
new zmq.Subscriber(...)
new zmq.Request(...)
new zmq.Reply(...)
new zmq.Dealer(...)
new zmq.Router(...)
new zmq.Pull(...)
new zmq.Push(...)
new zmq.XPublisher(...)
new zmq.XSubscriber(...)
new zmq.Stream(...)
+Socket options can be set during construction or via a property after the socket was created. Most socket options do not take effect until the next bind() or connect() call. Setting such an option after the socket is already connected or bound will display a warning.
Hierarchy (View Summary)
Index
Constructors
Properties
Methods
Properties
affinity
ZMQ_AFFINITY
I/O thread affinity, which determines which threads from the ØMQ I/O thread pool associated with the socket's context shall handle newly created connections.
Note: This value is a bit mask, but values higher than Number.MAX_SAFE_INTEGER may not be represented accurately! This currently means that configurations beyond 52 threads are unreliable.
backlog
ZMQ_BACKLOG
Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.
Readonlyclosed
Whether this socket was previously closed with close().
connectTimeout
ZMQ_CONNECT_TIMEOUT
Sets how long to wait before timing-out a connect() system call. The connect() system call normally takes a long time before it returns a time out error. Setting this option allows the library to time out the call at an earlier interval.
Readonlycontext
Context that this socket belongs to.
curvePublicKey
ZMQ_CURVE_PUBLICKEY
Sets the socket's long term public key. You must set this on CURVE client sockets. A server socket does not need to know its own public key. You can create a new keypair with curveKeyPair().
curveSecretKey
ZMQ_CURVE_SECRETKEY
Sets the socket's long term secret key. You must set this on both CURVE client and server sockets. You can create a new keypair with curveKeyPair().
curveServer
ZMQ_CURVE_SERVER
Defines whether the socket will act as server for CURVE security. A value of true means the socket will act as CURVE server. A value of false means the socket will not act as CURVE server, and its security role then depends on other option settings.
curveServerKey
ZMQ_CURVE_SERVERKEY
Sets the socket's long term server key. This is the public key of the CURVE server socket. You must set this on CURVE client sockets. This key must have been generated together with the server's secret key. You can create a new keypair with curveKeyPair().
Readonlyevents
Event Observer for this socket. This starts up a ØMQ monitoring socket internally that receives all socket events.
gssapiPlainText
gssapiPrincipal
gssapiPrincipalNameType
gssapiServer
gssapiServicePrincipal
gssapiServicePrincipalNameType
handshakeInterval
ZMQ_HANDSHAKE_IVL
Handshaking is the exchange of socket configuration information (socket type, identity, security) that occurs when a connection is first opened (only for connection-oriented transports). If handshaking does not complete within the configured time, the connection shall be closed. The value 0 means no handshake time limit.
heartbeatInterval
ZMQ_HEARTBEAT_IVL
Interval in milliseconds between sending ZMTP heartbeats for the specified socket. If this option is greater than 0, then a PING ZMTP command will be sent after every interval.
heartbeatTimeout
ZMQ_HEARTBEAT_TIMEOUT
How long (in milliseconds) to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic. This option is only valid if heartbeatInterval is greater than 0. The connection will time out if there is no traffic received after sending the PING command. The received traffic does not have to be a PONG command - any received traffic will cancel the timeout.
heartbeatTimeToLive
ZMQ_HEARTBEAT_TTL
The timeout in milliseconds on the remote peer for ZMTP heartbeats. If this option is greater than 0, the remote side shall time out the connection if it does not receive any more traffic within the TTL period. This option does not have any effect if heartbeatInterval is 0. Internally, this value is rounded down to the nearest decisecond, any value less than 100 will have no effect.
immediate
ZMQ_IMMEDIATE
By default queues will fill on outgoing connections even if the connection has not completed. This can lead to "lost" messages on sockets with round-robin routing (Request, Push, Dealer). If this option is set to true, messages shall be queued only to completed connections. This will cause the socket to block if there are no other connections, but will prevent queues from filling on pipes awaiting connection.
interface
ZMQ_BINDTODEVICE
Binds the socket to the given network interface (Linux only). Allows to use Linux VRF, see: https://www.kernel.org/doc/Documentation/networking/vrf.txt. Requires the program to be ran as root or with CAP_NET_RAW.
ipv6
ZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
ReadonlylastEndpoint
ZMQ_LAST_ENDPOINT
The last endpoint bound for TCP and IPC transports.
linger
ZMQ_LINGER
Determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with close().
loopbackFastPath
ZMQ_LOOPBACK_FASTPATH
Enable faster TCP connections on loopback devices. An application can enable this option to reduce the latency and improve the performance of loopback operations on a TCP socket on Windows.
maxMessageSize
ZMQ_MAXMSGSIZE
Limits the size of the inbound message. If a peer sends a message larger than the limit it is disconnected. Value of -1 means no limit.
multicastMaxTransportDataUnit
ZMQ_MULTICAST_MAXTPDU
Sets the maximum transport data unit size used for outbound multicast packets. This must be set at or below the minimum Maximum Transmission Unit (MTU) for all network paths over which multicast reception is required.
plainPassword
ZMQ_PLAIN_PASSWORD
Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
plainServer
ZMQ_PLAIN_SERVER
Defines whether the socket will act as server for PLAIN security. A value of true means the socket will act as PLAIN server. A value of false means the socket will not act as PLAIN server, and its security role then depends on other option settings.
plainUsername
ZMQ_PLAIN_USERNAME
Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
rate
ZMQ_RATE
Maximum send or receive data rate for multicast transports such as pgm.
Readonlyreadable
Whether any messages are currently available. If true, the next call to Readable.receive() will immediately read a message from the socket. For sockets that cannot receive messsages this is always false.
reconnectInterval
ZMQ_RECONNECT_IVL
Period ØMQ shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. The value -1 means no reconnection.
reconnectMaxInterval
ZMQ_RECONNECT_IVL_MAX
Maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled until reconnectMaxInterval is reached. This allows for exponential backoff strategy. Zero (the default) means no exponential backoff is performed and reconnect interval calculations are only based on reconnectInterval.
recoveryInterval
ZMQ_RECOVERY_IVL
Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
ReadonlysecurityMechanism
ZMQ_MECHANISM
Returns the current security mechanism for the socket, if any. The security mechanism is set implictly by using any of the relevant security options. The returned value is one of:
null- No security mechanism is used."plain"- The PLAIN mechanism defines a simple username/password mechanism that lets a server authenticate a client. PLAIN makes no attempt at security or confidentiality."curve"- The CURVE mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server. CURVE is intended for use on public networks."gssapi"- The GSSAPI mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server using the Generic Security Service Application Program Interface (GSSAPI). The GSSAPI mechanism can be used on both public and private networks.
socksProxy
ZMQ_SOCKS_PROXY
The SOCKS5 proxy address that shall be used by the socket for the TCP connection(s). Does not support SOCKS5 authentication. If the endpoints are domain names instead of addresses they shall not be resolved and they shall be forwarded unchanged to the SOCKS proxy service in the client connection request message (address type 0x03 domain name).
tcpAcceptFilter
ZMQ_TCP_ACCEPT_FILTER
Assign a filter that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one filter is applied then new connection source IP should be matched. To clear all filters set to null. Filter is a string with IPv6 or IPv4 CIDR.
tcpKeepalive
ZMQ_TCP_KEEPALIVE
Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveCount
ZMQ_TCP_KEEPALIVE_CNT
Overrides TCP_KEEPCNT socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveIdle
ZMQ_TCP_KEEPALIVE_IDLE
Overrides TCP_KEEPIDLE / TCP_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveInterval
ZMQ_TCP_KEEPALIVE_INTVL
Overrides TCP_KEEPINTVL socket option (if supported by the OS). The default value of -1 leaves it to the OS default.
tcpMaxRetransmitTimeout
ZMQ_TCP_MAXRT
Sets how long before an unacknowledged TCP retransmit times out (if supported by the OS). The system normally attempts many TCP retransmits following an exponential backoff strategy. This means that after a network outage, it may take a long time before the session can be re-established. Setting this option allows the timeout to happen at a shorter interval.
ReadonlythreadSafe
ZMQ_THREAD_SAFE
Whether or not the socket is threadsafe. Currently only DRAFT sockets is thread-safe.
Readonlytype
ZMQ_TYPE
Retrieve the socket type. This is fairly useless because you can test the socket class with e.g. socket instanceof Dealer.
typeOfService
ZMQ_TOS
Sets the ToS fields (the Differentiated Services (DS) and Explicit Congestion Notification (ECN) field) of the IP header. The ToS field is typically used to specify a packet's priority. The availability of this option is dependent on intermediate network equipment that inspect the ToS field and provide a path for low-delay, high-throughput, highly-reliable service, etc.
vmciBufferMaxSize
ZMQ_VMCI_BUFFER_MAX_SIZE
Maximum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferMinSize
ZMQ_VMCI_BUFFER_MIN_SIZE
Minimum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferSize
ZMQ_VMCI_BUFFER_SIZE
The size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciConnectTimeout
ZMQ_VMCI_CONNECT_TIMEOUT
Connection timeout for the socket. For vmci:// transports only.
Readonlywritable
Whether any messages can be queued for sending. If true, the next call to Writable.send() will immediately queue a message on the socket. For sockets that cannot send messsages this is always false.
zapDomain
ZMQ_ZAP_DOMAIN
Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the default on all tcp:// connections), ZAP authentication only happens if you set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 for more details.
zapEnforceDomain
ZMQ_ZAP_ENFORCE_DOMAIN
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.
Methods
bind
- bind(address: string): Promise<void>
Binds the socket to the given address. During bind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.You can use
*in place of a hostname to bind on all interfaces/addresses, and you can use*in place of a port to bind to a random port (which can be retrieved with lastEndpoint later).await socket.bind("tcp://127.0.0.1:3456")
await socket.bind("tcp://*:3456") // binds on all interfaces
await socket.bind("tcp://127.0.0.1:*") // binds on random port +Parameters
- address: string
Address to bind this socket to.
Returns Promise<void>
Resolved when the socket was successfully bound.
- address: string
bindSync
- bindSync(address: string): void
Binds the socket to the given address. During bind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.You can use
*in place of a hostname to bind on all interfaces/addresses, and you can use*in place of a port to bind to a random port (which can be retrieved with lastEndpoint later).socket.bindSync("tcp://127.0.0.1:3456")
socket.bindSync("tcp://*:3456") // binds on all interfaces
socket.bindSync("tcp://127.0.0.1:*") // binds on random port +Parameters
- address: string
Address to bind this socket to.
Returns void
Resolved when the socket was successfully bound.
- address: string
close
- close(): void
Closes the socket and disposes of all resources. Any messages that are queued may be discarded or sent in the background depending on the linger setting.
After this method is called, it is no longer possible to call any other methods on this socket.
Sockets that go out of scope and have no Readable.receive() or Writable.send() operations in progress will automatically be closed. Therefore it is not necessary in most applications to call close() manually.
Calling this method on a socket that is already closed is a no-op.
Returns void
connect
disconnect
- disconnect(address: string): void
Disconnects a previously connected socket from the given address and returns immediately. Disonnection will happen asynchronously in the background.
socket.disconnect("tcp://127.0.0.1:3456") +Parameters
- address: string
The previously connected address to disconnect from.
Returns void
- address: string
ProtectedgetBoolOption
ProtectedgetInt32Option
ProtectedgetInt64Option
ProtectedgetStringOption
ProtectedgetUint32Option
ProtectedgetUint64Option
ProtectedsetBoolOption
ProtectedsetInt32Option
ProtectedsetInt64Option
ProtectedsetStringOption
ProtectedsetUint32Option
ProtectedsetUint64Option
unbind
- unbind(address: string): Promise<void>
Unbinds the socket to the given address. During unbind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.Parameters
- address: string
Address to unbind this socket from.
Returns Promise<void>
Resolved when the socket was successfully unbound.
- address: string
unbindSync
- unbindSync(address: string): void
Unbinds the socket to the given address. During unbind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.Parameters
- address: string
Address to unbind this socket from.
Returns void
Resolved when the socket was successfully unbound.
- address: string
Class Stream
A Stream is used to send and receive TCP data from a non-ØMQ peer with the tcp:// transport. A Stream can act as client and/or server, sending and/or receiving TCP data asynchronously.
When sending and receiving data with Writable.send() and Readable.receive(), the first message part shall be the routing id of the peer. Unroutable messages will cause an error.
When a connection is made to a Stream, a zero-length message will be received. Similarly, when the peer disconnects (or the connection is lost), a zero-length message will be received.
To close a specific connection, Writable.send() the routing id frame followed by a zero-length message.
To open a connection to a server, use Stream.connect().
Hierarchy (view full)
- Socket
- Readable<[Message, Message]>
- Writable<[MessageLike, MessageLike]>
- Stream
Index
Constructors
Properties
Methods
Constructors
constructor
- new
Stream (options?): Stream Parameters
Optionaloptions: {
affinity?: number;
backlog?: number;
connectTimeout?: number;
context?: Context;
curvePublicKey?: null | string;
curveSecretKey?: null | string;
curveServer?: boolean;
curveServerKey?: null | string;
gssapiPlainText?: boolean;
gssapiPrincipal?: null | string;
gssapiPrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
gssapiServer?: boolean;
gssapiServicePrincipal?: null | string;
gssapiServicePrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
handshakeInterval?: number;
heartbeatInterval?: number;
heartbeatTimeout?: number;
heartbeatTimeToLive?: number;
immediate?: boolean;
interface?: null | string;
ipv6?: boolean;
linger?: number;
loopbackFastPath?: boolean;
maxMessageSize?: number;
multicastHops?: number;
multicastMaxTransportDataUnit?: number;
notify?: boolean;
plainPassword?: null | string;
plainServer?: boolean;
plainUsername?: null | string;
rate?: number;
receiveBufferSize?: number;
receiveHighWaterMark?: number;
receiveTimeout?: number;
reconnectInterval?: number;
reconnectMaxInterval?: number;
recoveryInterval?: number;
sendBufferSize?: number;
sendHighWaterMark?: number;
sendTimeout?: number;
socksProxy?: null | string;
tcpAcceptFilter?: null | string;
tcpKeepalive?: number;
tcpKeepaliveCount?: number;
tcpKeepaliveIdle?: number;
tcpKeepaliveInterval?: number;
tcpMaxRetransmitTimeout?: number;
typeOfService?: number;
vmciBufferMaxSize?: number;
vmciBufferMinSize?: number;
vmciBufferSize?: number;
vmciConnectTimeout?: number;
zapDomain?: null | string;
zapEnforceDomain?: boolean;
}Optionalaffinity?: numberZMQ_AFFINITY
I/O thread affinity, which determines which threads from the ØMQ I/O thread pool associated with the socket's context shall handle newly created connections.
Note: This value is a bit mask, but values higher than
Number.MAX_SAFE_INTEGERmay not be represented accurately! This currently means that configurations beyond 52 threads are unreliable.Optionalbacklog?: numberZMQ_BACKLOG
Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.
OptionalconnectTimeout ?: numberZMQ_CONNECT_TIMEOUT
Sets how long to wait before timing-out a connect() system call. The connect() system call normally takes a long time before it returns a time out error. Setting this option allows the library to time out the call at an earlier interval.
Optionalcontext?: ContextOptionalcurvePublic ?: null | stringKey ZMQ_CURVE_PUBLICKEY
Sets the socket's long term public key. You must set this on CURVE client sockets. A server socket does not need to know its own public key. You can create a new keypair with curveKeyPair().
OptionalcurveSecret ?: null | stringKey ZMQ_CURVE_SECRETKEY
Sets the socket's long term secret key. You must set this on both CURVE client and server sockets. You can create a new keypair with curveKeyPair().
OptionalcurveServer ?: booleanZMQ_CURVE_SERVER
Defines whether the socket will act as server for CURVE security. A value of
truemeans the socket will act as CURVE server. A value offalsemeans the socket will not act as CURVE server, and its security role then depends on other option settings.OptionalcurveServer ?: null | stringKey ZMQ_CURVE_SERVERKEY
Sets the socket's long term server key. This is the public key of the CURVE server socket. You must set this on CURVE client sockets. This key must have been generated together with the server's secret key. You can create a new keypair with curveKeyPair().
OptionalgssapiPlain ?: booleanText OptionalgssapiPrincipal ?: null | stringOptionalgssapiPrincipal ?: "hostBased" | "userName" | "krb5Principal"Name Type OptionalgssapiServer ?: booleanOptionalgssapiService ?: null | stringPrincipal OptionalgssapiService ?: "hostBased" | "userName" | "krb5Principal"Principal Name Type OptionalhandshakeInterval ?: numberZMQ_HANDSHAKE_IVL
Handshaking is the exchange of socket configuration information (socket type, identity, security) that occurs when a connection is first opened (only for connection-oriented transports). If handshaking does not complete within the configured time, the connection shall be closed. The value 0 means no handshake time limit.
OptionalheartbeatInterval ?: numberZMQ_HEARTBEAT_IVL
Interval in milliseconds between sending ZMTP heartbeats for the specified socket. If this option is greater than 0, then a PING ZMTP command will be sent after every interval.
OptionalheartbeatTimeout ?: numberZMQ_HEARTBEAT_TIMEOUT
How long (in milliseconds) to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic. This option is only valid if heartbeatInterval is greater than 0. The connection will time out if there is no traffic received after sending the PING command. The received traffic does not have to be a PONG command - any received traffic will cancel the timeout.
OptionalheartbeatTime ?: numberTo Live ZMQ_HEARTBEAT_TTL
The timeout in milliseconds on the remote peer for ZMTP heartbeats. If this option is greater than 0, the remote side shall time out the connection if it does not receive any more traffic within the TTL period. This option does not have any effect if heartbeatInterval is 0. Internally, this value is rounded down to the nearest decisecond, any value less than 100 will have no effect.
Optionalimmediate?: booleanZMQ_IMMEDIATE
By default queues will fill on outgoing connections even if the connection has not completed. This can lead to "lost" messages on sockets with round-robin routing (Request, Push, Dealer). If this option is set to
true, messages shall be queued only to completed connections. This will cause the socket to block if there are no other connections, but will prevent queues from filling on pipes awaiting connection.Optionalinterface?: null | stringZMQ_BINDTODEVICE
Binds the socket to the given network interface (Linux only). Allows to use Linux VRF, see: https://www.kernel.org/doc/Documentation/networking/vrf.txt. Requires the program to be ran as root or with
CAP_NET_RAW.Optionalipv6?: booleanZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
Optionallinger?: numberZMQ_LINGER
Determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with close().
OptionalloopbackFast ?: booleanPath ZMQ_LOOPBACK_FASTPATH
Enable faster TCP connections on loopback devices. An application can enable this option to reduce the latency and improve the performance of loopback operations on a TCP socket on Windows.
OptionalmaxMessage ?: numberSize ZMQ_MAXMSGSIZE
Limits the size of the inbound message. If a peer sends a message larger than the limit it is disconnected. Value of -1 means no limit.
OptionalmulticastHops ?: numberZMQ_MULTICAST_HOPS
Sets the time-to-live field in every multicast packet sent from this socket. The default is 1 which means that the multicast packets don't leave the local network.
OptionalmulticastMax ?: numberTransport Data Unit ZMQ_MULTICAST_MAXTPDU
Sets the maximum transport data unit size used for outbound multicast packets. This must be set at or below the minimum Maximum Transmission Unit (MTU) for all network paths over which multicast reception is required.
Optionalnotify?: booleanZMQ_STREAM_NOTIFY
Enables connect and disconnect notifications on a Stream when set to
true. When notifications are enabled, the socket delivers a zero-length message when a peer connects or disconnects.OptionalplainPassword ?: null | stringZMQ_PLAIN_PASSWORD
Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
OptionalplainServer ?: booleanZMQ_PLAIN_SERVER
Defines whether the socket will act as server for PLAIN security. A value of
truemeans the socket will act as PLAIN server. A value offalsemeans the socket will not act as PLAIN server, and its security role then depends on other option settings.OptionalplainUsername ?: null | stringZMQ_PLAIN_USERNAME
Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
Optionalrate?: numberZMQ_RATE
Maximum send or receive data rate for multicast transports such as
pgm.OptionalreceiveBuffer ?: numberSize ZMQ_RCVBUF
Underlying kernel receive buffer size in bytes. A value of -1 means leave the OS default unchanged.
OptionalreceiveHigh ?: numberWater Mark ZMQ_RCVHWM
The high water mark is a hard limit on the maximum number of incoming messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
OptionalreceiveTimeout ?: numberZMQ_RCVTIMEO
Sets the timeout receiving messages on the socket. If the value is 0, receive() will return a rejected promise immediately if there is no message to receive. If the value is -1, it will wait asynchronously until a message is available. For all other values, it will wait for a message for that amount of time before rejecting.
OptionalreconnectInterval ?: numberZMQ_RECONNECT_IVL
Period ØMQ shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. The value -1 means no reconnection.
OptionalreconnectMax ?: numberInterval ZMQ_RECONNECT_IVL_MAX
Maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled until reconnectMaxInterval is reached. This allows for exponential backoff strategy. Zero (the default) means no exponential backoff is performed and reconnect interval calculations are only based on reconnectInterval.
OptionalrecoveryInterval ?: numberZMQ_RECOVERY_IVL
Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
OptionalsendBuffer ?: numberSize ZMQ_SNDBUF
Underlying kernel transmit buffer size in bytes. A value of -1 means leave the OS default unchanged.
OptionalsendHigh ?: numberWater Mark ZMQ_SNDHWM
The high water mark is a hard limit on the maximum number of outgoing messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
OptionalsendTimeout ?: numberZMQ_SNDTIMEO
Sets the timeout for sending messages on the socket. If the value is 0, send() will return a rejected promise immediately if the message cannot be sent. If the value is -1, it will wait asynchronously until the message is sent. For all other values, it will try to send the message for that amount of time before rejecting.
OptionalsocksProxy ?: null | stringZMQ_SOCKS_PROXY
The SOCKS5 proxy address that shall be used by the socket for the TCP connection(s). Does not support SOCKS5 authentication. If the endpoints are domain names instead of addresses they shall not be resolved and they shall be forwarded unchanged to the SOCKS proxy service in the client connection request message (address type 0x03 domain name).
OptionaltcpAccept ?: null | stringFilter ZMQ_TCP_ACCEPT_FILTER
Assign a filter that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one filter is applied then new connection source IP should be matched. To clear all filters set to
null. Filter is a string with IPv6 or IPv4 CIDR.OptionaltcpKeepalive ?: numberZMQ_TCP_KEEPALIVE
Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepalive ?: numberCount ZMQ_TCP_KEEPALIVE_CNT
Overrides TCP_KEEPCNT socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepalive ?: numberIdle ZMQ_TCP_KEEPALIVE_IDLE
Overrides TCP_KEEPIDLE / TCP_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepalive ?: numberInterval ZMQ_TCP_KEEPALIVE_INTVL
Overrides TCP_KEEPINTVL socket option (if supported by the OS). The default value of -1 leaves it to the OS default.
OptionaltcpMax ?: numberRetransmit Timeout ZMQ_TCP_MAXRT
Sets how long before an unacknowledged TCP retransmit times out (if supported by the OS). The system normally attempts many TCP retransmits following an exponential backoff strategy. This means that after a network outage, it may take a long time before the session can be re-established. Setting this option allows the timeout to happen at a shorter interval.
OptionaltypeOf ?: numberService ZMQ_TOS
Sets the ToS fields (the Differentiated Services (DS) and Explicit Congestion Notification (ECN) field) of the IP header. The ToS field is typically used to specify a packet's priority. The availability of this option is dependent on intermediate network equipment that inspect the ToS field and provide a path for low-delay, high-throughput, highly-reliable service, etc.
OptionalvmciBuffer ?: numberMax Size ZMQ_VMCI_BUFFER_MAX_SIZE
Maximum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciBuffer ?: numberMin Size ZMQ_VMCI_BUFFER_MIN_SIZE
Minimum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciBuffer ?: numberSize ZMQ_VMCI_BUFFER_SIZE
The size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciConnect ?: numberTimeout ZMQ_VMCI_CONNECT_TIMEOUT
Connection timeout for the socket. For
vmci://transports only.OptionalzapDomain ?: null | stringZMQ_ZAP_DOMAIN
Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the default on all
tcp://connections), ZAP authentication only happens if you set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 for more details.OptionalzapEnforce ?: booleanDomain ZMQ_ZAP_ENFORCE_DOMAIN
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.
Returns Stream
Properties
affinity
ZMQ_AFFINITY
I/O thread affinity, which determines which threads from the ØMQ I/O thread pool associated with the socket's context shall handle newly created connections.
Note: This value is a bit mask, but values higher than Number.MAX_SAFE_INTEGER may not be represented accurately! This currently means that configurations beyond 52 threads are unreliable.
backlog
ZMQ_BACKLOG
Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.
Readonlyclosed
Whether this socket was previously closed with close().
connectTimeout
ZMQ_CONNECT_TIMEOUT
Sets how long to wait before timing-out a connect() system call. The connect() system call normally takes a long time before it returns a time out error. Setting this option allows the library to time out the call at an earlier interval.
Readonlycontext
Context that this socket belongs to.
curvePublicKey
ZMQ_CURVE_PUBLICKEY
Sets the socket's long term public key. You must set this on CURVE client sockets. A server socket does not need to know its own public key. You can create a new keypair with curveKeyPair().
curveSecretKey
ZMQ_CURVE_SECRETKEY
Sets the socket's long term secret key. You must set this on both CURVE client and server sockets. You can create a new keypair with curveKeyPair().
curveServer
ZMQ_CURVE_SERVER
Defines whether the socket will act as server for CURVE security. A value of true means the socket will act as CURVE server. A value of false means the socket will not act as CURVE server, and its security role then depends on other option settings.
curveServerKey
ZMQ_CURVE_SERVERKEY
Sets the socket's long term server key. This is the public key of the CURVE server socket. You must set this on CURVE client sockets. This key must have been generated together with the server's secret key. You can create a new keypair with curveKeyPair().
Readonlyevents
Event Observer for this socket. This starts up a ØMQ monitoring socket internally that receives all socket events.
gssapiPlainText
gssapiPrincipal
gssapiPrincipalNameType
gssapiServer
gssapiServicePrincipal
gssapiServicePrincipalNameType
handshakeInterval
ZMQ_HANDSHAKE_IVL
Handshaking is the exchange of socket configuration information (socket type, identity, security) that occurs when a connection is first opened (only for connection-oriented transports). If handshaking does not complete within the configured time, the connection shall be closed. The value 0 means no handshake time limit.
heartbeatInterval
ZMQ_HEARTBEAT_IVL
Interval in milliseconds between sending ZMTP heartbeats for the specified socket. If this option is greater than 0, then a PING ZMTP command will be sent after every interval.
heartbeatTimeout
ZMQ_HEARTBEAT_TIMEOUT
How long (in milliseconds) to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic. This option is only valid if heartbeatInterval is greater than 0. The connection will time out if there is no traffic received after sending the PING command. The received traffic does not have to be a PONG command - any received traffic will cancel the timeout.
heartbeatTimeToLive
ZMQ_HEARTBEAT_TTL
The timeout in milliseconds on the remote peer for ZMTP heartbeats. If this option is greater than 0, the remote side shall time out the connection if it does not receive any more traffic within the TTL period. This option does not have any effect if heartbeatInterval is 0. Internally, this value is rounded down to the nearest decisecond, any value less than 100 will have no effect.
immediate
ZMQ_IMMEDIATE
By default queues will fill on outgoing connections even if the connection has not completed. This can lead to "lost" messages on sockets with round-robin routing (Request, Push, Dealer). If this option is set to true, messages shall be queued only to completed connections. This will cause the socket to block if there are no other connections, but will prevent queues from filling on pipes awaiting connection.
interface
ZMQ_BINDTODEVICE
Binds the socket to the given network interface (Linux only). Allows to use Linux VRF, see: https://www.kernel.org/doc/Documentation/networking/vrf.txt. Requires the program to be ran as root or with CAP_NET_RAW.
ipv6
ZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
ReadonlylastEndpoint
ZMQ_LAST_ENDPOINT
The last endpoint bound for TCP and IPC transports.
linger
ZMQ_LINGER
Determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with close().
loopbackFastPath
ZMQ_LOOPBACK_FASTPATH
Enable faster TCP connections on loopback devices. An application can enable this option to reduce the latency and improve the performance of loopback operations on a TCP socket on Windows.
maxMessageSize
ZMQ_MAXMSGSIZE
Limits the size of the inbound message. If a peer sends a message larger than the limit it is disconnected. Value of -1 means no limit.
multicastHops
ZMQ_MULTICAST_HOPS
Sets the time-to-live field in every multicast packet sent from this socket. The default is 1 which means that the multicast packets don't leave the local network.
multicastMaxTransportDataUnit
ZMQ_MULTICAST_MAXTPDU
Sets the maximum transport data unit size used for outbound multicast packets. This must be set at or below the minimum Maximum Transmission Unit (MTU) for all network paths over which multicast reception is required.
notify
ZMQ_STREAM_NOTIFY
Enables connect and disconnect notifications on a Stream when set to true. When notifications are enabled, the socket delivers a zero-length message when a peer connects or disconnects.
plainPassword
ZMQ_PLAIN_PASSWORD
Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
plainServer
ZMQ_PLAIN_SERVER
Defines whether the socket will act as server for PLAIN security. A value of true means the socket will act as PLAIN server. A value of false means the socket will not act as PLAIN server, and its security role then depends on other option settings.
plainUsername
ZMQ_PLAIN_USERNAME
Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
rate
ZMQ_RATE
Maximum send or receive data rate for multicast transports such as pgm.
Readonlyreadable
Whether any messages are currently available. If true, the next call to Readable.receive() will immediately read a message from the socket. For sockets that cannot receive messsages this is always false.
receiveBufferSize
ZMQ_RCVBUF
Underlying kernel receive buffer size in bytes. A value of -1 means leave the OS default unchanged.
receiveHighWaterMark
ZMQ_RCVHWM
The high water mark is a hard limit on the maximum number of incoming messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
receiveTimeout
ZMQ_RCVTIMEO
Sets the timeout receiving messages on the socket. If the value is 0, receive() will return a rejected promise immediately if there is no message to receive. If the value is -1, it will wait asynchronously until a message is available. For all other values, it will wait for a message for that amount of time before rejecting.
reconnectInterval
ZMQ_RECONNECT_IVL
Period ØMQ shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. The value -1 means no reconnection.
reconnectMaxInterval
ZMQ_RECONNECT_IVL_MAX
Maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled until reconnectMaxInterval is reached. This allows for exponential backoff strategy. Zero (the default) means no exponential backoff is performed and reconnect interval calculations are only based on reconnectInterval.
recoveryInterval
ZMQ_RECOVERY_IVL
Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
ReadonlysecurityMechanism
| null
| "plain"
| "curve"
| "gssapi"
ZMQ_MECHANISM
Returns the current security mechanism for the socket, if any. The security mechanism is set implictly by using any of the relevant security options. The returned value is one of:
null- No security mechanism is used."plain"- The PLAIN mechanism defines a simple username/password mechanism that lets a server authenticate a client. PLAIN makes no attempt at security or confidentiality."curve"- The CURVE mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server. CURVE is intended for use on public networks."gssapi"- The GSSAPI mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server using the Generic Security Service Application Program Interface (GSSAPI). The GSSAPI mechanism can be used on both public and private networks.
sendBufferSize
ZMQ_SNDBUF
Underlying kernel transmit buffer size in bytes. A value of -1 means leave the OS default unchanged.
sendHighWaterMark
ZMQ_SNDHWM
The high water mark is a hard limit on the maximum number of outgoing messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
sendTimeout
ZMQ_SNDTIMEO
Sets the timeout for sending messages on the socket. If the value is 0, send() will return a rejected promise immediately if the message cannot be sent. If the value is -1, it will wait asynchronously until the message is sent. For all other values, it will try to send the message for that amount of time before rejecting.
socksProxy
ZMQ_SOCKS_PROXY
The SOCKS5 proxy address that shall be used by the socket for the TCP connection(s). Does not support SOCKS5 authentication. If the endpoints are domain names instead of addresses they shall not be resolved and they shall be forwarded unchanged to the SOCKS proxy service in the client connection request message (address type 0x03 domain name).
tcpAcceptFilter
ZMQ_TCP_ACCEPT_FILTER
Assign a filter that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one filter is applied then new connection source IP should be matched. To clear all filters set to null. Filter is a string with IPv6 or IPv4 CIDR.
tcpKeepalive
ZMQ_TCP_KEEPALIVE
Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveCount
ZMQ_TCP_KEEPALIVE_CNT
Overrides TCP_KEEPCNT socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveIdle
ZMQ_TCP_KEEPALIVE_IDLE
Overrides TCP_KEEPIDLE / TCP_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveInterval
ZMQ_TCP_KEEPALIVE_INTVL
Overrides TCP_KEEPINTVL socket option (if supported by the OS). The default value of -1 leaves it to the OS default.
tcpMaxRetransmitTimeout
ZMQ_TCP_MAXRT
Sets how long before an unacknowledged TCP retransmit times out (if supported by the OS). The system normally attempts many TCP retransmits following an exponential backoff strategy. This means that after a network outage, it may take a long time before the session can be re-established. Setting this option allows the timeout to happen at a shorter interval.
ReadonlythreadSafe
ZMQ_THREAD_SAFE
Whether or not the socket is threadsafe. Currently only DRAFT sockets is thread-safe.
Readonlytype
ZMQ_TYPE
Retrieve the socket type. This is fairly useless because you can test the socket class with e.g. socket instanceof Dealer.
typeOfService
ZMQ_TOS
Sets the ToS fields (the Differentiated Services (DS) and Explicit Congestion Notification (ECN) field) of the IP header. The ToS field is typically used to specify a packet's priority. The availability of this option is dependent on intermediate network equipment that inspect the ToS field and provide a path for low-delay, high-throughput, highly-reliable service, etc.
vmciBufferMaxSize
ZMQ_VMCI_BUFFER_MAX_SIZE
Maximum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferMinSize
ZMQ_VMCI_BUFFER_MIN_SIZE
Minimum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferSize
ZMQ_VMCI_BUFFER_SIZE
The size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciConnectTimeout
ZMQ_VMCI_CONNECT_TIMEOUT
Connection timeout for the socket. For vmci:// transports only.
Readonlywritable
Whether any messages can be queued for sending. If true, the next call to Writable.send() will immediately queue a message on the socket. For sockets that cannot send messsages this is always false.
zapDomain
ZMQ_ZAP_DOMAIN
Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the default on all tcp:// connections), ZAP authentication only happens if you set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 for more details.
zapEnforceDomain
ZMQ_ZAP_ENFORCE_DOMAIN
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.
Methods
[asyncIterator]
- [async
Iterator] (): AsyncIterator<[Buffer, Buffer], undefined, undefined> Asynchronously iterate over messages becoming available on the socket. When the socket is closed with Socket.close(), the iterator will return. Returning early from the iterator will not close the socket unless it also goes out of scope.
for await (const [msg] of socket) {
// handle messages
} -Returns AsyncIterator<[Buffer, Buffer], undefined, undefined>
bind
- bind(address): Promise<void>
Binds the socket to the given address. During bind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.You can use
*in place of a hostname to bind on all interfaces/addresses, and you can use*in place of a port to bind to a random port (which can be retrieved with lastEndpoint later).await socket.bind("tcp://127.0.0.1:3456")
await socket.bind("tcp://*:3456") // binds on all interfaces
await socket.bind("tcp://127.0.0.1:*") // binds on random port -Parameters
- address: string
Address to bind this socket to.
Returns Promise<void>
Resolved when the socket was successfully bound.
- address: string
close
- close(): void
Closes the socket and disposes of all resources. Any messages that are queued may be discarded or sent in the background depending on the linger setting.
After this method is called, it is no longer possible to call any other methods on this socket.
Sockets that go out of scope and have no Readable.receive() or Writable.send() operations in progress will automatically be closed. Therefore it is not necessary in most applications to call close() manually.
Calling this method on a socket that is already closed is a no-op.
Returns void
connect
- connect(address, options?): void
Connects to the given remote address. To specificy a specific routing id, provide a
routingIdoption. The identity should be unique, from 1 to 255 bytes long and MAY NOT start with binary zero.Parameters
- address: string
The
tcp://address to connect to. - options: StreamConnectOptions = {}
Any connection options.
Returns void
- address: string
disconnect
- disconnect(address): void
Disconnects a previously connected socket from the given address and returns immediately. Disonnection will happen asynchronously in the background.
socket.disconnect("tcp://127.0.0.1:3456") -Parameters
- address: string
The previously connected address to disconnect from.
Returns void
- address: string
ProtectedgetBoolOption
ProtectedgetInt32Option
ProtectedgetInt64Option
ProtectedgetStringOption
ProtectedgetUint32Option
ProtectedgetUint64Option
receive
- receive(): Promise<[Buffer, Buffer]>
Waits for the next single or multipart message to become availeble on the socket. Reads a message immediately if possible. If no messages can be read, it will wait asynchonously. The promise will be resolved with an array containing the parts of the next message when available.
const [msg] = await socket.receive()
const [part1, part2] = await socket.receive() -Reading may fail (eventually) if the socket has been configured with a receiveTimeout.
A call to receive() is guaranteed to return with a resolved promise immediately if a message could be read from the socket directly.
Only one asynchronously blocking call to receive() can be in progress simultaneously. If you call receive() again on the same socket it will return a rejected promise with an
EBUSYerror. For example, if no messages can be read and noawaitis used:socket.receive() // -> pending promise until read is possible
socket.receive() // -> promise rejection with `EBUSY` error -Note: Due to the nature of Node.js and to avoid blocking the main thread, this method always attempts to read messages with the
ZMQ_DONTWAITflag. It polls asynchronously if reading is not currently possible. This means that all functionality related to timeouts and blocking behaviour is reimplemented in the Node.js bindings. Any differences in behaviour with the native ZMQ library is considered a bug.Returns Promise<[Buffer, Buffer]>
Resolved with message parts that were successfully read.
send
- send(message, ...options): Promise<void>
Sends a single message or a multipart message on the socket. Queues the message immediately if possible, and returns a resolved promise. If the message cannot be queued because the high water mark has been reached, it will wait asynchronously. The promise will be resolved when the message was queued successfully.
await socket.send("hello world")
await socket.send(["hello", "world"]) -Queueing may fail eventually if the socket has been configured with a sendTimeout.
A call to send() is guaranteed to return with a resolved promise immediately if the message could be queued directly.
Only one asynchronously blocking call to send() may be executed simultaneously. If you call send() again on a socket that is in the mute state it will return a rejected promise with an
EBUSYerror.The reason for disallowing multiple send() calls simultaneously is that it could create an implicit queue of unsendable outgoing messages. This would circumvent the socket's sendHighWaterMark. Such an implementation could even exhaust all system memory and cause the Node.js process to abort.
For most application you should not notice this implementation detail. Only in rare occasions will a call to send() that does not resolve immediately be undesired. Here are some common scenarios:
If you wish to send a message, use
await send(...). ZeroMQ socket types have been carefully designed to give you the correct blocking behaviour on the chosen socket type in almost all cases:If sending is not possible, it is often better to wait than to continue as if nothing happened. For example, on a Request socket, you can only receive a reply once a message has been sent; so waiting until a message could be queued before continuing with the rest of the program (likely to read from the socket) is required.
Certain socket types (such as Router) will always allow queueing messages and
await send(...)won't delay any code that comes after. This makes sense for routers, since typically you don't want a single send operation to stop the handling of other incoming or outgoing messages.
If you wish to send on an occasionally blocking socket (for example on a Router with the Router.mandatory option set, or on a Dealer) and you're 100% certain that dropping a message is better than blocking, then you can set the sendTimeout option to
0to effectively force send() to always resolve immediately. Be prepared to catch exceptions if sending a message is not immediately possible.If you wish to send on a socket and messages should be queued before they are dropped, you should implement a simple queue in JavaScript. Such a queue is not provided by this library because most real world applications need to deal with undeliverable messages in more complex ways - for example, they might need to reply with a status message; or first retry delivery a certain number of times before giving up.
Parameters
- message: [MessageLike, MessageLike]
Single message or multipart message to queue for sending.
Rest...options: []Any options, if applicable to the socket type (DRAFT only).
Returns Promise<void>
Resolved when the message was successfully queued.
ProtectedsetBoolOption
ProtectedsetInt32Option
ProtectedsetInt64Option
ProtectedsetStringOption
ProtectedsetUint32Option
ProtectedsetUint64Option
unbind
- unbind(address): Promise<void>
Unbinds the socket to the given address. During unbind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.Parameters
- address: string
Address to unbind this socket from.
Returns Promise<void>
Resolved when the socket was successfully unbound.
- address: string
Class Stream
A Stream is used to send and receive TCP data from a non-ØMQ peer with the tcp:// transport. A Stream can act as client and/or server, sending and/or receiving TCP data asynchronously.
When sending and receiving data with Writable.send() and Readable.receive(), the first message part shall be the routing id of the peer. Unroutable messages will cause an error.
When a connection is made to a Stream, a zero-length message will be received. Similarly, when the peer disconnects (or the connection is lost), a zero-length message will be received.
To close a specific connection, Writable.send() the routing id frame followed by a zero-length message.
To open a connection to a server, use Stream.connect().
Hierarchy (View Summary)
- Socket
- Readable<[Message, Message]>
- Writable<[MessageLike, MessageLike]>
- Stream
Index
Constructors
Properties
Methods
Constructors
constructor
- new Stream(
options?: {
affinity?: number;
backlog?: number;
connectTimeout?: number;
context?: Context;
curvePublicKey?: null | string;
curveSecretKey?: null | string;
curveServer?: boolean;
curveServerKey?: null | string;
gssapiPlainText?: boolean;
gssapiPrincipal?: null | string;
gssapiPrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
gssapiServer?: boolean;
gssapiServicePrincipal?: null | string;
gssapiServicePrincipalNameType?:
| "hostBased"
| "userName"
| "krb5Principal";
handshakeInterval?: number;
heartbeatInterval?: number;
heartbeatTimeout?: number;
heartbeatTimeToLive?: number;
immediate?: boolean;
interface?: null
| string;
ipv6?: boolean;
linger?: number;
loopbackFastPath?: boolean;
maxMessageSize?: number;
multicastHops?: number;
multicastMaxTransportDataUnit?: number;
notify?: boolean;
plainPassword?: null | string;
plainServer?: boolean;
plainUsername?: null | string;
rate?: number;
receiveBufferSize?: number;
receiveHighWaterMark?: number;
receiveTimeout?: number;
reconnectInterval?: number;
reconnectMaxInterval?: number;
recoveryInterval?: number;
sendBufferSize?: number;
sendHighWaterMark?: number;
sendTimeout?: number;
socksProxy?: null | string;
tcpAcceptFilter?: null | string;
tcpKeepalive?: number;
tcpKeepaliveCount?: number;
tcpKeepaliveIdle?: number;
tcpKeepaliveInterval?: number;
tcpMaxRetransmitTimeout?: number;
typeOfService?: number;
vmciBufferMaxSize?: number;
vmciBufferMinSize?: number;
vmciBufferSize?: number;
vmciConnectTimeout?: number;
zapDomain?: null | string;
zapEnforceDomain?: boolean;
},
): Stream Parameters
Optionaloptions: {
affinity?: number;
backlog?: number;
connectTimeout?: number;
context?: Context;
curvePublicKey?: null | string;
curveSecretKey?: null | string;
curveServer?: boolean;
curveServerKey?: null | string;
gssapiPlainText?: boolean;
gssapiPrincipal?: null | string;
gssapiPrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
gssapiServer?: boolean;
gssapiServicePrincipal?: null | string;
gssapiServicePrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
handshakeInterval?: number;
heartbeatInterval?: number;
heartbeatTimeout?: number;
heartbeatTimeToLive?: number;
immediate?: boolean;
interface?: null | string;
ipv6?: boolean;
linger?: number;
loopbackFastPath?: boolean;
maxMessageSize?: number;
multicastHops?: number;
multicastMaxTransportDataUnit?: number;
notify?: boolean;
plainPassword?: null | string;
plainServer?: boolean;
plainUsername?: null | string;
rate?: number;
receiveBufferSize?: number;
receiveHighWaterMark?: number;
receiveTimeout?: number;
reconnectInterval?: number;
reconnectMaxInterval?: number;
recoveryInterval?: number;
sendBufferSize?: number;
sendHighWaterMark?: number;
sendTimeout?: number;
socksProxy?: null | string;
tcpAcceptFilter?: null | string;
tcpKeepalive?: number;
tcpKeepaliveCount?: number;
tcpKeepaliveIdle?: number;
tcpKeepaliveInterval?: number;
tcpMaxRetransmitTimeout?: number;
typeOfService?: number;
vmciBufferMaxSize?: number;
vmciBufferMinSize?: number;
vmciBufferSize?: number;
vmciConnectTimeout?: number;
zapDomain?: null | string;
zapEnforceDomain?: boolean;
}Optionalaffinity?: numberZMQ_AFFINITY
I/O thread affinity, which determines which threads from the ØMQ I/O thread pool associated with the socket's context shall handle newly created connections.
Note: This value is a bit mask, but values higher than
Number.MAX_SAFE_INTEGERmay not be represented accurately! This currently means that configurations beyond 52 threads are unreliable.Optionalbacklog?: numberZMQ_BACKLOG
Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.
OptionalconnectTimeout?: numberZMQ_CONNECT_TIMEOUT
Sets how long to wait before timing-out a connect() system call. The connect() system call normally takes a long time before it returns a time out error. Setting this option allows the library to time out the call at an earlier interval.
Optionalcontext?: ContextOptionalcurvePublicKey?: null | stringZMQ_CURVE_PUBLICKEY
Sets the socket's long term public key. You must set this on CURVE client sockets. A server socket does not need to know its own public key. You can create a new keypair with curveKeyPair().
OptionalcurveSecretKey?: null | stringZMQ_CURVE_SECRETKEY
Sets the socket's long term secret key. You must set this on both CURVE client and server sockets. You can create a new keypair with curveKeyPair().
OptionalcurveServer?: booleanZMQ_CURVE_SERVER
Defines whether the socket will act as server for CURVE security. A value of
truemeans the socket will act as CURVE server. A value offalsemeans the socket will not act as CURVE server, and its security role then depends on other option settings.OptionalcurveServerKey?: null | stringZMQ_CURVE_SERVERKEY
Sets the socket's long term server key. This is the public key of the CURVE server socket. You must set this on CURVE client sockets. This key must have been generated together with the server's secret key. You can create a new keypair with curveKeyPair().
OptionalgssapiPlainText?: booleanOptionalgssapiPrincipal?: null | stringOptionalgssapiPrincipalNameType?: "hostBased" | "userName" | "krb5Principal"OptionalgssapiServer?: booleanOptionalgssapiServicePrincipal?: null | stringOptionalgssapiServicePrincipalNameType?: "hostBased" | "userName" | "krb5Principal"OptionalhandshakeInterval?: numberZMQ_HANDSHAKE_IVL
Handshaking is the exchange of socket configuration information (socket type, identity, security) that occurs when a connection is first opened (only for connection-oriented transports). If handshaking does not complete within the configured time, the connection shall be closed. The value 0 means no handshake time limit.
OptionalheartbeatInterval?: numberZMQ_HEARTBEAT_IVL
Interval in milliseconds between sending ZMTP heartbeats for the specified socket. If this option is greater than 0, then a PING ZMTP command will be sent after every interval.
OptionalheartbeatTimeout?: numberZMQ_HEARTBEAT_TIMEOUT
How long (in milliseconds) to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic. This option is only valid if heartbeatInterval is greater than 0. The connection will time out if there is no traffic received after sending the PING command. The received traffic does not have to be a PONG command - any received traffic will cancel the timeout.
OptionalheartbeatTimeToLive?: numberZMQ_HEARTBEAT_TTL
The timeout in milliseconds on the remote peer for ZMTP heartbeats. If this option is greater than 0, the remote side shall time out the connection if it does not receive any more traffic within the TTL period. This option does not have any effect if heartbeatInterval is 0. Internally, this value is rounded down to the nearest decisecond, any value less than 100 will have no effect.
Optionalimmediate?: booleanZMQ_IMMEDIATE
By default queues will fill on outgoing connections even if the connection has not completed. This can lead to "lost" messages on sockets with round-robin routing (Request, Push, Dealer). If this option is set to
true, messages shall be queued only to completed connections. This will cause the socket to block if there are no other connections, but will prevent queues from filling on pipes awaiting connection.Optionalinterface?: null | stringZMQ_BINDTODEVICE
Binds the socket to the given network interface (Linux only). Allows to use Linux VRF, see: https://www.kernel.org/doc/Documentation/networking/vrf.txt. Requires the program to be ran as root or with
CAP_NET_RAW.Optionalipv6?: booleanZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
Optionallinger?: numberZMQ_LINGER
Determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with close().
OptionalloopbackFastPath?: booleanZMQ_LOOPBACK_FASTPATH
Enable faster TCP connections on loopback devices. An application can enable this option to reduce the latency and improve the performance of loopback operations on a TCP socket on Windows.
OptionalmaxMessageSize?: numberZMQ_MAXMSGSIZE
Limits the size of the inbound message. If a peer sends a message larger than the limit it is disconnected. Value of -1 means no limit.
OptionalmulticastHops?: numberZMQ_MULTICAST_HOPS
Sets the time-to-live field in every multicast packet sent from this socket. The default is 1 which means that the multicast packets don't leave the local network.
OptionalmulticastMaxTransportDataUnit?: numberZMQ_MULTICAST_MAXTPDU
Sets the maximum transport data unit size used for outbound multicast packets. This must be set at or below the minimum Maximum Transmission Unit (MTU) for all network paths over which multicast reception is required.
Optionalnotify?: booleanZMQ_STREAM_NOTIFY
Enables connect and disconnect notifications on a Stream when set to
true. When notifications are enabled, the socket delivers a zero-length message when a peer connects or disconnects.OptionalplainPassword?: null | stringZMQ_PLAIN_PASSWORD
Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
OptionalplainServer?: booleanZMQ_PLAIN_SERVER
Defines whether the socket will act as server for PLAIN security. A value of
truemeans the socket will act as PLAIN server. A value offalsemeans the socket will not act as PLAIN server, and its security role then depends on other option settings.OptionalplainUsername?: null | stringZMQ_PLAIN_USERNAME
Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
Optionalrate?: numberZMQ_RATE
Maximum send or receive data rate for multicast transports such as
pgm.OptionalreceiveBufferSize?: numberZMQ_RCVBUF
Underlying kernel receive buffer size in bytes. A value of -1 means leave the OS default unchanged.
OptionalreceiveHighWaterMark?: numberZMQ_RCVHWM
The high water mark is a hard limit on the maximum number of incoming messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
OptionalreceiveTimeout?: numberZMQ_RCVTIMEO
Sets the timeout receiving messages on the socket. If the value is 0, receive() will return a rejected promise immediately if there is no message to receive. If the value is -1, it will wait asynchronously until a message is available. For all other values, it will wait for a message for that amount of time before rejecting.
OptionalreconnectInterval?: numberZMQ_RECONNECT_IVL
Period ØMQ shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. The value -1 means no reconnection.
OptionalreconnectMaxInterval?: numberZMQ_RECONNECT_IVL_MAX
Maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled until reconnectMaxInterval is reached. This allows for exponential backoff strategy. Zero (the default) means no exponential backoff is performed and reconnect interval calculations are only based on reconnectInterval.
OptionalrecoveryInterval?: numberZMQ_RECOVERY_IVL
Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
OptionalsendBufferSize?: numberZMQ_SNDBUF
Underlying kernel transmit buffer size in bytes. A value of -1 means leave the OS default unchanged.
OptionalsendHighWaterMark?: numberZMQ_SNDHWM
The high water mark is a hard limit on the maximum number of outgoing messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
OptionalsendTimeout?: numberZMQ_SNDTIMEO
Sets the timeout for sending messages on the socket. If the value is 0, send() will return a rejected promise immediately if the message cannot be sent. If the value is -1, it will wait asynchronously until the message is sent. For all other values, it will try to send the message for that amount of time before rejecting.
OptionalsocksProxy?: null | stringZMQ_SOCKS_PROXY
The SOCKS5 proxy address that shall be used by the socket for the TCP connection(s). Does not support SOCKS5 authentication. If the endpoints are domain names instead of addresses they shall not be resolved and they shall be forwarded unchanged to the SOCKS proxy service in the client connection request message (address type 0x03 domain name).
OptionaltcpAcceptFilter?: null | stringZMQ_TCP_ACCEPT_FILTER
Assign a filter that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one filter is applied then new connection source IP should be matched. To clear all filters set to
null. Filter is a string with IPv6 or IPv4 CIDR.OptionaltcpKeepalive?: numberZMQ_TCP_KEEPALIVE
Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepaliveCount?: numberZMQ_TCP_KEEPALIVE_CNT
Overrides TCP_KEEPCNT socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepaliveIdle?: numberZMQ_TCP_KEEPALIVE_IDLE
Overrides TCP_KEEPIDLE / TCP_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepaliveInterval?: numberZMQ_TCP_KEEPALIVE_INTVL
Overrides TCP_KEEPINTVL socket option (if supported by the OS). The default value of -1 leaves it to the OS default.
OptionaltcpMaxRetransmitTimeout?: numberZMQ_TCP_MAXRT
Sets how long before an unacknowledged TCP retransmit times out (if supported by the OS). The system normally attempts many TCP retransmits following an exponential backoff strategy. This means that after a network outage, it may take a long time before the session can be re-established. Setting this option allows the timeout to happen at a shorter interval.
OptionaltypeOfService?: numberZMQ_TOS
Sets the ToS fields (the Differentiated Services (DS) and Explicit Congestion Notification (ECN) field) of the IP header. The ToS field is typically used to specify a packet's priority. The availability of this option is dependent on intermediate network equipment that inspect the ToS field and provide a path for low-delay, high-throughput, highly-reliable service, etc.
OptionalvmciBufferMaxSize?: numberZMQ_VMCI_BUFFER_MAX_SIZE
Maximum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciBufferMinSize?: numberZMQ_VMCI_BUFFER_MIN_SIZE
Minimum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciBufferSize?: numberZMQ_VMCI_BUFFER_SIZE
The size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciConnectTimeout?: numberZMQ_VMCI_CONNECT_TIMEOUT
Connection timeout for the socket. For
vmci://transports only.OptionalzapDomain?: null | stringZMQ_ZAP_DOMAIN
Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the default on all
tcp://connections), ZAP authentication only happens if you set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 for more details.OptionalzapEnforceDomain?: booleanZMQ_ZAP_ENFORCE_DOMAIN
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.
Returns Stream
Properties
affinity
ZMQ_AFFINITY
I/O thread affinity, which determines which threads from the ØMQ I/O thread pool associated with the socket's context shall handle newly created connections.
Note: This value is a bit mask, but values higher than Number.MAX_SAFE_INTEGER may not be represented accurately! This currently means that configurations beyond 52 threads are unreliable.
backlog
ZMQ_BACKLOG
Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.
Readonlyclosed
Whether this socket was previously closed with close().
connectTimeout
ZMQ_CONNECT_TIMEOUT
Sets how long to wait before timing-out a connect() system call. The connect() system call normally takes a long time before it returns a time out error. Setting this option allows the library to time out the call at an earlier interval.
Readonlycontext
Context that this socket belongs to.
curvePublicKey
ZMQ_CURVE_PUBLICKEY
Sets the socket's long term public key. You must set this on CURVE client sockets. A server socket does not need to know its own public key. You can create a new keypair with curveKeyPair().
curveSecretKey
ZMQ_CURVE_SECRETKEY
Sets the socket's long term secret key. You must set this on both CURVE client and server sockets. You can create a new keypair with curveKeyPair().
curveServer
ZMQ_CURVE_SERVER
Defines whether the socket will act as server for CURVE security. A value of true means the socket will act as CURVE server. A value of false means the socket will not act as CURVE server, and its security role then depends on other option settings.
curveServerKey
ZMQ_CURVE_SERVERKEY
Sets the socket's long term server key. This is the public key of the CURVE server socket. You must set this on CURVE client sockets. This key must have been generated together with the server's secret key. You can create a new keypair with curveKeyPair().
Readonlyevents
Event Observer for this socket. This starts up a ØMQ monitoring socket internally that receives all socket events.
gssapiPlainText
gssapiPrincipal
gssapiPrincipalNameType
gssapiServer
gssapiServicePrincipal
gssapiServicePrincipalNameType
handshakeInterval
ZMQ_HANDSHAKE_IVL
Handshaking is the exchange of socket configuration information (socket type, identity, security) that occurs when a connection is first opened (only for connection-oriented transports). If handshaking does not complete within the configured time, the connection shall be closed. The value 0 means no handshake time limit.
heartbeatInterval
ZMQ_HEARTBEAT_IVL
Interval in milliseconds between sending ZMTP heartbeats for the specified socket. If this option is greater than 0, then a PING ZMTP command will be sent after every interval.
heartbeatTimeout
ZMQ_HEARTBEAT_TIMEOUT
How long (in milliseconds) to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic. This option is only valid if heartbeatInterval is greater than 0. The connection will time out if there is no traffic received after sending the PING command. The received traffic does not have to be a PONG command - any received traffic will cancel the timeout.
heartbeatTimeToLive
ZMQ_HEARTBEAT_TTL
The timeout in milliseconds on the remote peer for ZMTP heartbeats. If this option is greater than 0, the remote side shall time out the connection if it does not receive any more traffic within the TTL period. This option does not have any effect if heartbeatInterval is 0. Internally, this value is rounded down to the nearest decisecond, any value less than 100 will have no effect.
immediate
ZMQ_IMMEDIATE
By default queues will fill on outgoing connections even if the connection has not completed. This can lead to "lost" messages on sockets with round-robin routing (Request, Push, Dealer). If this option is set to true, messages shall be queued only to completed connections. This will cause the socket to block if there are no other connections, but will prevent queues from filling on pipes awaiting connection.
interface
ZMQ_BINDTODEVICE
Binds the socket to the given network interface (Linux only). Allows to use Linux VRF, see: https://www.kernel.org/doc/Documentation/networking/vrf.txt. Requires the program to be ran as root or with CAP_NET_RAW.
ipv6
ZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
ReadonlylastEndpoint
ZMQ_LAST_ENDPOINT
The last endpoint bound for TCP and IPC transports.
linger
ZMQ_LINGER
Determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with close().
loopbackFastPath
ZMQ_LOOPBACK_FASTPATH
Enable faster TCP connections on loopback devices. An application can enable this option to reduce the latency and improve the performance of loopback operations on a TCP socket on Windows.
maxMessageSize
ZMQ_MAXMSGSIZE
Limits the size of the inbound message. If a peer sends a message larger than the limit it is disconnected. Value of -1 means no limit.
multicastHops
ZMQ_MULTICAST_HOPS
Sets the time-to-live field in every multicast packet sent from this socket. The default is 1 which means that the multicast packets don't leave the local network.
multicastMaxTransportDataUnit
ZMQ_MULTICAST_MAXTPDU
Sets the maximum transport data unit size used for outbound multicast packets. This must be set at or below the minimum Maximum Transmission Unit (MTU) for all network paths over which multicast reception is required.
notify
ZMQ_STREAM_NOTIFY
Enables connect and disconnect notifications on a Stream when set to true. When notifications are enabled, the socket delivers a zero-length message when a peer connects or disconnects.
plainPassword
ZMQ_PLAIN_PASSWORD
Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
plainServer
ZMQ_PLAIN_SERVER
Defines whether the socket will act as server for PLAIN security. A value of true means the socket will act as PLAIN server. A value of false means the socket will not act as PLAIN server, and its security role then depends on other option settings.
plainUsername
ZMQ_PLAIN_USERNAME
Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
rate
ZMQ_RATE
Maximum send or receive data rate for multicast transports such as pgm.
Readonlyreadable
Whether any messages are currently available. If true, the next call to Readable.receive() will immediately read a message from the socket. For sockets that cannot receive messsages this is always false.
receiveBufferSize
ZMQ_RCVBUF
Underlying kernel receive buffer size in bytes. A value of -1 means leave the OS default unchanged.
receiveHighWaterMark
ZMQ_RCVHWM
The high water mark is a hard limit on the maximum number of incoming messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
receiveTimeout
ZMQ_RCVTIMEO
Sets the timeout receiving messages on the socket. If the value is 0, receive() will return a rejected promise immediately if there is no message to receive. If the value is -1, it will wait asynchronously until a message is available. For all other values, it will wait for a message for that amount of time before rejecting.
reconnectInterval
ZMQ_RECONNECT_IVL
Period ØMQ shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. The value -1 means no reconnection.
reconnectMaxInterval
ZMQ_RECONNECT_IVL_MAX
Maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled until reconnectMaxInterval is reached. This allows for exponential backoff strategy. Zero (the default) means no exponential backoff is performed and reconnect interval calculations are only based on reconnectInterval.
recoveryInterval
ZMQ_RECOVERY_IVL
Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
ReadonlysecurityMechanism
ZMQ_MECHANISM
Returns the current security mechanism for the socket, if any. The security mechanism is set implictly by using any of the relevant security options. The returned value is one of:
null- No security mechanism is used."plain"- The PLAIN mechanism defines a simple username/password mechanism that lets a server authenticate a client. PLAIN makes no attempt at security or confidentiality."curve"- The CURVE mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server. CURVE is intended for use on public networks."gssapi"- The GSSAPI mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server using the Generic Security Service Application Program Interface (GSSAPI). The GSSAPI mechanism can be used on both public and private networks.
sendBufferSize
ZMQ_SNDBUF
Underlying kernel transmit buffer size in bytes. A value of -1 means leave the OS default unchanged.
sendHighWaterMark
ZMQ_SNDHWM
The high water mark is a hard limit on the maximum number of outgoing messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
sendTimeout
ZMQ_SNDTIMEO
Sets the timeout for sending messages on the socket. If the value is 0, send() will return a rejected promise immediately if the message cannot be sent. If the value is -1, it will wait asynchronously until the message is sent. For all other values, it will try to send the message for that amount of time before rejecting.
socksProxy
ZMQ_SOCKS_PROXY
The SOCKS5 proxy address that shall be used by the socket for the TCP connection(s). Does not support SOCKS5 authentication. If the endpoints are domain names instead of addresses they shall not be resolved and they shall be forwarded unchanged to the SOCKS proxy service in the client connection request message (address type 0x03 domain name).
tcpAcceptFilter
ZMQ_TCP_ACCEPT_FILTER
Assign a filter that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one filter is applied then new connection source IP should be matched. To clear all filters set to null. Filter is a string with IPv6 or IPv4 CIDR.
tcpKeepalive
ZMQ_TCP_KEEPALIVE
Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveCount
ZMQ_TCP_KEEPALIVE_CNT
Overrides TCP_KEEPCNT socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveIdle
ZMQ_TCP_KEEPALIVE_IDLE
Overrides TCP_KEEPIDLE / TCP_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveInterval
ZMQ_TCP_KEEPALIVE_INTVL
Overrides TCP_KEEPINTVL socket option (if supported by the OS). The default value of -1 leaves it to the OS default.
tcpMaxRetransmitTimeout
ZMQ_TCP_MAXRT
Sets how long before an unacknowledged TCP retransmit times out (if supported by the OS). The system normally attempts many TCP retransmits following an exponential backoff strategy. This means that after a network outage, it may take a long time before the session can be re-established. Setting this option allows the timeout to happen at a shorter interval.
ReadonlythreadSafe
ZMQ_THREAD_SAFE
Whether or not the socket is threadsafe. Currently only DRAFT sockets is thread-safe.
Readonlytype
ZMQ_TYPE
Retrieve the socket type. This is fairly useless because you can test the socket class with e.g. socket instanceof Dealer.
typeOfService
ZMQ_TOS
Sets the ToS fields (the Differentiated Services (DS) and Explicit Congestion Notification (ECN) field) of the IP header. The ToS field is typically used to specify a packet's priority. The availability of this option is dependent on intermediate network equipment that inspect the ToS field and provide a path for low-delay, high-throughput, highly-reliable service, etc.
vmciBufferMaxSize
ZMQ_VMCI_BUFFER_MAX_SIZE
Maximum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferMinSize
ZMQ_VMCI_BUFFER_MIN_SIZE
Minimum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferSize
ZMQ_VMCI_BUFFER_SIZE
The size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciConnectTimeout
ZMQ_VMCI_CONNECT_TIMEOUT
Connection timeout for the socket. For vmci:// transports only.
Readonlywritable
Whether any messages can be queued for sending. If true, the next call to Writable.send() will immediately queue a message on the socket. For sockets that cannot send messsages this is always false.
zapDomain
ZMQ_ZAP_DOMAIN
Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the default on all tcp:// connections), ZAP authentication only happens if you set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 for more details.
zapEnforceDomain
ZMQ_ZAP_ENFORCE_DOMAIN
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.
Methods
[asyncIterator]
- "[asyncIterator]"(): AsyncIterator<[Buffer, Buffer]>
Asynchronously iterate over messages becoming available on the socket. When the socket is closed with Socket.close(), the iterator will return. Returning early from the iterator will not close the socket unless it also goes out of scope.
for await (const [msg] of socket) {
// handle messages
} +Returns AsyncIterator<[Buffer, Buffer]>
bind
- bind(address: string): Promise<void>
Binds the socket to the given address. During bind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.You can use
*in place of a hostname to bind on all interfaces/addresses, and you can use*in place of a port to bind to a random port (which can be retrieved with lastEndpoint later).await socket.bind("tcp://127.0.0.1:3456")
await socket.bind("tcp://*:3456") // binds on all interfaces
await socket.bind("tcp://127.0.0.1:*") // binds on random port +Parameters
- address: string
Address to bind this socket to.
Returns Promise<void>
Resolved when the socket was successfully bound.
- address: string
bindSync
- bindSync(address: string): void
Binds the socket to the given address. During bind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.You can use
*in place of a hostname to bind on all interfaces/addresses, and you can use*in place of a port to bind to a random port (which can be retrieved with lastEndpoint later).socket.bindSync("tcp://127.0.0.1:3456")
socket.bindSync("tcp://*:3456") // binds on all interfaces
socket.bindSync("tcp://127.0.0.1:*") // binds on random port +Parameters
- address: string
Address to bind this socket to.
Returns void
Resolved when the socket was successfully bound.
- address: string
close
- close(): void
Closes the socket and disposes of all resources. Any messages that are queued may be discarded or sent in the background depending on the linger setting.
After this method is called, it is no longer possible to call any other methods on this socket.
Sockets that go out of scope and have no Readable.receive() or Writable.send() operations in progress will automatically be closed. Therefore it is not necessary in most applications to call close() manually.
Calling this method on a socket that is already closed is a no-op.
Returns void
connect
- connect(address: string, options?: StreamConnectOptions): void
Connects to the given remote address. To specificy a specific routing id, provide a
routingIdoption. The identity should be unique, from 1 to 255 bytes long and MAY NOT start with binary zero.Parameters
- address: string
The
tcp://address to connect to. - options: StreamConnectOptions = {}
Any connection options.
Returns void
- address: string
disconnect
- disconnect(address: string): void
Disconnects a previously connected socket from the given address and returns immediately. Disonnection will happen asynchronously in the background.
socket.disconnect("tcp://127.0.0.1:3456") +Parameters
- address: string
The previously connected address to disconnect from.
Returns void
- address: string
ProtectedgetBoolOption
ProtectedgetInt32Option
ProtectedgetInt64Option
ProtectedgetStringOption
ProtectedgetUint32Option
ProtectedgetUint64Option
receive
- receive(): Promise<[Buffer, Buffer]>
Waits for the next single or multipart message to become availeble on the socket. Reads a message immediately if possible. If no messages can be read, it will wait asynchonously. The promise will be resolved with an array containing the parts of the next message when available.
const [msg] = await socket.receive()
const [part1, part2] = await socket.receive() +Reading may fail (eventually) if the socket has been configured with a receiveTimeout.
A call to receive() is guaranteed to return with a resolved promise immediately if a message could be read from the socket directly.
Only one asynchronously blocking call to receive() can be in progress simultaneously. If you call receive() again on the same socket it will return a rejected promise with an
EBUSYerror. For example, if no messages can be read and noawaitis used:socket.receive() // -> pending promise until read is possible
socket.receive() // -> promise rejection with `EBUSY` error +Note: Due to the nature of Node.js and to avoid blocking the main thread, this method always attempts to read messages with the
ZMQ_DONTWAITflag. It polls asynchronously if reading is not currently possible. This means that all functionality related to timeouts and blocking behaviour is reimplemented in the Node.js bindings. Any differences in behaviour with the native ZMQ library is considered a bug.Returns Promise<[Buffer, Buffer]>
Resolved with message parts that were successfully read.
send
- send(message: [MessageLike, MessageLike], ...options: []): Promise<void>
Sends a single message or a multipart message on the socket. Queues the message immediately if possible, and returns a resolved promise. If the message cannot be queued because the high water mark has been reached, it will wait asynchronously. The promise will be resolved when the message was queued successfully.
await socket.send("hello world")
await socket.send(["hello", "world"]) +Queueing may fail eventually if the socket has been configured with a sendTimeout.
A call to send() is guaranteed to return with a resolved promise immediately if the message could be queued directly.
Only one asynchronously blocking call to send() may be executed simultaneously. If you call send() again on a socket that is in the mute state it will return a rejected promise with an
EBUSYerror.The reason for disallowing multiple send() calls simultaneously is that it could create an implicit queue of unsendable outgoing messages. This would circumvent the socket's sendHighWaterMark. Such an implementation could even exhaust all system memory and cause the Node.js process to abort.
For most application you should not notice this implementation detail. Only in rare occasions will a call to send() that does not resolve immediately be undesired. Here are some common scenarios:
If you wish to send a message, use
await send(...). ZeroMQ socket types have been carefully designed to give you the correct blocking behaviour on the chosen socket type in almost all cases:If sending is not possible, it is often better to wait than to continue as if nothing happened. For example, on a Request socket, you can only receive a reply once a message has been sent; so waiting until a message could be queued before continuing with the rest of the program (likely to read from the socket) is required.
Certain socket types (such as Router) will always allow queueing messages and
await send(...)won't delay any code that comes after. This makes sense for routers, since typically you don't want a single send operation to stop the handling of other incoming or outgoing messages.
If you wish to send on an occasionally blocking socket (for example on a Router with the Router.mandatory option set, or on a Dealer) and you're 100% certain that dropping a message is better than blocking, then you can set the sendTimeout option to
0to effectively force send() to always resolve immediately. Be prepared to catch exceptions if sending a message is not immediately possible.If you wish to send on a socket and messages should be queued before they are dropped, you should implement a simple queue in JavaScript. Such a queue is not provided by this library because most real world applications need to deal with undeliverable messages in more complex ways - for example, they might need to reply with a status message; or first retry delivery a certain number of times before giving up.
Parameters
- message: [MessageLike, MessageLike]
Single message or multipart message to queue for sending.
- ...options: []
Any options, if applicable to the socket type (DRAFT only).
Returns Promise<void>
Resolved when the message was successfully queued.
ProtectedsetBoolOption
ProtectedsetInt32Option
ProtectedsetInt64Option
ProtectedsetStringOption
ProtectedsetUint32Option
ProtectedsetUint64Option
unbind
- unbind(address: string): Promise<void>
Unbinds the socket to the given address. During unbind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.Parameters
- address: string
Address to unbind this socket from.
Returns Promise<void>
Resolved when the socket was successfully unbound.
- address: string
unbindSync
- unbindSync(address: string): void
Unbinds the socket to the given address. During unbind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.Parameters
- address: string
Address to unbind this socket from.
Returns void
Resolved when the socket was successfully unbound.
- address: string
Class Subscriber
A Subscriber socket is used to subscribe to data distributed by a Publisher. Initially a Subscriber is not subscribed to any messages. Use Subscriber.subscribe() to specify which messages to subscribe to. This socket cannot send messages.
Hierarchy (view full)
Index
Constructors
Properties
Methods
Constructors
constructor
- new
Subscriber (options?): Subscriber Parameters
Optionaloptions: {
affinity?: number;
backlog?: number;
conflate?: boolean;
connectTimeout?: number;
context?: Context;
curvePublicKey?: null | string;
curveSecretKey?: null | string;
curveServer?: boolean;
curveServerKey?: null | string;
gssapiPlainText?: boolean;
gssapiPrincipal?: null | string;
gssapiPrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
gssapiServer?: boolean;
gssapiServicePrincipal?: null | string;
gssapiServicePrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
handshakeInterval?: number;
heartbeatInterval?: number;
heartbeatTimeout?: number;
heartbeatTimeToLive?: number;
immediate?: boolean;
interface?: null | string;
invertMatching?: boolean;
ipv6?: boolean;
linger?: number;
loopbackFastPath?: boolean;
maxMessageSize?: number;
multicastMaxTransportDataUnit?: number;
plainPassword?: null | string;
plainServer?: boolean;
plainUsername?: null | string;
rate?: number;
receiveBufferSize?: number;
receiveHighWaterMark?: number;
receiveTimeout?: number;
reconnectInterval?: number;
reconnectMaxInterval?: number;
recoveryInterval?: number;
socksProxy?: null | string;
tcpAcceptFilter?: null | string;
tcpKeepalive?: number;
tcpKeepaliveCount?: number;
tcpKeepaliveIdle?: number;
tcpKeepaliveInterval?: number;
tcpMaxRetransmitTimeout?: number;
typeOfService?: number;
vmciBufferMaxSize?: number;
vmciBufferMinSize?: number;
vmciBufferSize?: number;
vmciConnectTimeout?: number;
zapDomain?: null | string;
zapEnforceDomain?: boolean;
}Optionalaffinity?: numberZMQ_AFFINITY
I/O thread affinity, which determines which threads from the ØMQ I/O thread pool associated with the socket's context shall handle newly created connections.
Note: This value is a bit mask, but values higher than
Number.MAX_SAFE_INTEGERmay not be represented accurately! This currently means that configurations beyond 52 threads are unreliable.Optionalbacklog?: numberZMQ_BACKLOG
Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.
Optionalconflate?: booleanZMQ_CONFLATE
If set to
true, a socket shall keep only one message in its inbound/outbound queue: the last message to be received/sent. Ignores any high water mark options. Does not support multi-part messages - in particular, only one part of it is kept in the socket internal queue.OptionalconnectTimeout ?: numberZMQ_CONNECT_TIMEOUT
Sets how long to wait before timing-out a connect() system call. The connect() system call normally takes a long time before it returns a time out error. Setting this option allows the library to time out the call at an earlier interval.
Optionalcontext?: ContextOptionalcurvePublic ?: null | stringKey ZMQ_CURVE_PUBLICKEY
Sets the socket's long term public key. You must set this on CURVE client sockets. A server socket does not need to know its own public key. You can create a new keypair with curveKeyPair().
OptionalcurveSecret ?: null | stringKey ZMQ_CURVE_SECRETKEY
Sets the socket's long term secret key. You must set this on both CURVE client and server sockets. You can create a new keypair with curveKeyPair().
OptionalcurveServer ?: booleanZMQ_CURVE_SERVER
Defines whether the socket will act as server for CURVE security. A value of
truemeans the socket will act as CURVE server. A value offalsemeans the socket will not act as CURVE server, and its security role then depends on other option settings.OptionalcurveServer ?: null | stringKey ZMQ_CURVE_SERVERKEY
Sets the socket's long term server key. This is the public key of the CURVE server socket. You must set this on CURVE client sockets. This key must have been generated together with the server's secret key. You can create a new keypair with curveKeyPair().
OptionalgssapiPlain ?: booleanText OptionalgssapiPrincipal ?: null | stringOptionalgssapiPrincipal ?: "hostBased" | "userName" | "krb5Principal"Name Type OptionalgssapiServer ?: booleanOptionalgssapiService ?: null | stringPrincipal OptionalgssapiService ?: "hostBased" | "userName" | "krb5Principal"Principal Name Type OptionalhandshakeInterval ?: numberZMQ_HANDSHAKE_IVL
Handshaking is the exchange of socket configuration information (socket type, identity, security) that occurs when a connection is first opened (only for connection-oriented transports). If handshaking does not complete within the configured time, the connection shall be closed. The value 0 means no handshake time limit.
OptionalheartbeatInterval ?: numberZMQ_HEARTBEAT_IVL
Interval in milliseconds between sending ZMTP heartbeats for the specified socket. If this option is greater than 0, then a PING ZMTP command will be sent after every interval.
OptionalheartbeatTimeout ?: numberZMQ_HEARTBEAT_TIMEOUT
How long (in milliseconds) to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic. This option is only valid if heartbeatInterval is greater than 0. The connection will time out if there is no traffic received after sending the PING command. The received traffic does not have to be a PONG command - any received traffic will cancel the timeout.
OptionalheartbeatTime ?: numberTo Live ZMQ_HEARTBEAT_TTL
The timeout in milliseconds on the remote peer for ZMTP heartbeats. If this option is greater than 0, the remote side shall time out the connection if it does not receive any more traffic within the TTL period. This option does not have any effect if heartbeatInterval is 0. Internally, this value is rounded down to the nearest decisecond, any value less than 100 will have no effect.
Optionalimmediate?: booleanZMQ_IMMEDIATE
By default queues will fill on outgoing connections even if the connection has not completed. This can lead to "lost" messages on sockets with round-robin routing (Request, Push, Dealer). If this option is set to
true, messages shall be queued only to completed connections. This will cause the socket to block if there are no other connections, but will prevent queues from filling on pipes awaiting connection.Optionalinterface?: null | stringZMQ_BINDTODEVICE
Binds the socket to the given network interface (Linux only). Allows to use Linux VRF, see: https://www.kernel.org/doc/Documentation/networking/vrf.txt. Requires the program to be ran as root or with
CAP_NET_RAW.OptionalinvertMatching ?: booleanZMQ_INVERT_MATCHING
Causes incoming messages that do not match any of the socket's subscriptions to be received by the user.
All Subscriber sockets connecting to a Publisher must also have the option set to
true. Failure to do so will have the Subscriber sockets reject everything the Publisher socket sends them.Optionalipv6?: booleanZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
Optionallinger?: numberZMQ_LINGER
Determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with close().
OptionalloopbackFast ?: booleanPath ZMQ_LOOPBACK_FASTPATH
Enable faster TCP connections on loopback devices. An application can enable this option to reduce the latency and improve the performance of loopback operations on a TCP socket on Windows.
OptionalmaxMessage ?: numberSize ZMQ_MAXMSGSIZE
Limits the size of the inbound message. If a peer sends a message larger than the limit it is disconnected. Value of -1 means no limit.
OptionalmulticastMax ?: numberTransport Data Unit ZMQ_MULTICAST_MAXTPDU
Sets the maximum transport data unit size used for outbound multicast packets. This must be set at or below the minimum Maximum Transmission Unit (MTU) for all network paths over which multicast reception is required.
OptionalplainPassword ?: null | stringZMQ_PLAIN_PASSWORD
Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
OptionalplainServer ?: booleanZMQ_PLAIN_SERVER
Defines whether the socket will act as server for PLAIN security. A value of
truemeans the socket will act as PLAIN server. A value offalsemeans the socket will not act as PLAIN server, and its security role then depends on other option settings.OptionalplainUsername ?: null | stringZMQ_PLAIN_USERNAME
Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
Optionalrate?: numberZMQ_RATE
Maximum send or receive data rate for multicast transports such as
pgm.OptionalreceiveBuffer ?: numberSize ZMQ_RCVBUF
Underlying kernel receive buffer size in bytes. A value of -1 means leave the OS default unchanged.
OptionalreceiveHigh ?: numberWater Mark ZMQ_RCVHWM
The high water mark is a hard limit on the maximum number of incoming messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
OptionalreceiveTimeout ?: numberZMQ_RCVTIMEO
Sets the timeout receiving messages on the socket. If the value is 0, receive() will return a rejected promise immediately if there is no message to receive. If the value is -1, it will wait asynchronously until a message is available. For all other values, it will wait for a message for that amount of time before rejecting.
OptionalreconnectInterval ?: numberZMQ_RECONNECT_IVL
Period ØMQ shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. The value -1 means no reconnection.
OptionalreconnectMax ?: numberInterval ZMQ_RECONNECT_IVL_MAX
Maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled until reconnectMaxInterval is reached. This allows for exponential backoff strategy. Zero (the default) means no exponential backoff is performed and reconnect interval calculations are only based on reconnectInterval.
OptionalrecoveryInterval ?: numberZMQ_RECOVERY_IVL
Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
OptionalsocksProxy ?: null | stringZMQ_SOCKS_PROXY
The SOCKS5 proxy address that shall be used by the socket for the TCP connection(s). Does not support SOCKS5 authentication. If the endpoints are domain names instead of addresses they shall not be resolved and they shall be forwarded unchanged to the SOCKS proxy service in the client connection request message (address type 0x03 domain name).
OptionaltcpAccept ?: null | stringFilter ZMQ_TCP_ACCEPT_FILTER
Assign a filter that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one filter is applied then new connection source IP should be matched. To clear all filters set to
null. Filter is a string with IPv6 or IPv4 CIDR.OptionaltcpKeepalive ?: numberZMQ_TCP_KEEPALIVE
Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepalive ?: numberCount ZMQ_TCP_KEEPALIVE_CNT
Overrides TCP_KEEPCNT socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepalive ?: numberIdle ZMQ_TCP_KEEPALIVE_IDLE
Overrides TCP_KEEPIDLE / TCP_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepalive ?: numberInterval ZMQ_TCP_KEEPALIVE_INTVL
Overrides TCP_KEEPINTVL socket option (if supported by the OS). The default value of -1 leaves it to the OS default.
OptionaltcpMax ?: numberRetransmit Timeout ZMQ_TCP_MAXRT
Sets how long before an unacknowledged TCP retransmit times out (if supported by the OS). The system normally attempts many TCP retransmits following an exponential backoff strategy. This means that after a network outage, it may take a long time before the session can be re-established. Setting this option allows the timeout to happen at a shorter interval.
OptionaltypeOf ?: numberService ZMQ_TOS
Sets the ToS fields (the Differentiated Services (DS) and Explicit Congestion Notification (ECN) field) of the IP header. The ToS field is typically used to specify a packet's priority. The availability of this option is dependent on intermediate network equipment that inspect the ToS field and provide a path for low-delay, high-throughput, highly-reliable service, etc.
OptionalvmciBuffer ?: numberMax Size ZMQ_VMCI_BUFFER_MAX_SIZE
Maximum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciBuffer ?: numberMin Size ZMQ_VMCI_BUFFER_MIN_SIZE
Minimum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciBuffer ?: numberSize ZMQ_VMCI_BUFFER_SIZE
The size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciConnect ?: numberTimeout ZMQ_VMCI_CONNECT_TIMEOUT
Connection timeout for the socket. For
vmci://transports only.OptionalzapDomain ?: null | stringZMQ_ZAP_DOMAIN
Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the default on all
tcp://connections), ZAP authentication only happens if you set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 for more details.OptionalzapEnforce ?: booleanDomain ZMQ_ZAP_ENFORCE_DOMAIN
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.
Returns Subscriber
Properties
affinity
ZMQ_AFFINITY
I/O thread affinity, which determines which threads from the ØMQ I/O thread pool associated with the socket's context shall handle newly created connections.
Note: This value is a bit mask, but values higher than Number.MAX_SAFE_INTEGER may not be represented accurately! This currently means that configurations beyond 52 threads are unreliable.
backlog
ZMQ_BACKLOG
Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.
Readonlyclosed
Whether this socket was previously closed with close().
conflate
ZMQ_CONFLATE
If set to true, a socket shall keep only one message in its inbound/outbound queue: the last message to be received/sent. Ignores any high water mark options. Does not support multi-part messages - in particular, only one part of it is kept in the socket internal queue.
connectTimeout
ZMQ_CONNECT_TIMEOUT
Sets how long to wait before timing-out a connect() system call. The connect() system call normally takes a long time before it returns a time out error. Setting this option allows the library to time out the call at an earlier interval.
Readonlycontext
Context that this socket belongs to.
curvePublicKey
ZMQ_CURVE_PUBLICKEY
Sets the socket's long term public key. You must set this on CURVE client sockets. A server socket does not need to know its own public key. You can create a new keypair with curveKeyPair().
curveSecretKey
ZMQ_CURVE_SECRETKEY
Sets the socket's long term secret key. You must set this on both CURVE client and server sockets. You can create a new keypair with curveKeyPair().
curveServer
ZMQ_CURVE_SERVER
Defines whether the socket will act as server for CURVE security. A value of true means the socket will act as CURVE server. A value of false means the socket will not act as CURVE server, and its security role then depends on other option settings.
curveServerKey
ZMQ_CURVE_SERVERKEY
Sets the socket's long term server key. This is the public key of the CURVE server socket. You must set this on CURVE client sockets. This key must have been generated together with the server's secret key. You can create a new keypair with curveKeyPair().
Readonlyevents
Event Observer for this socket. This starts up a ØMQ monitoring socket internally that receives all socket events.
gssapiPlainText
gssapiPrincipal
gssapiPrincipalNameType
gssapiServer
gssapiServicePrincipal
gssapiServicePrincipalNameType
handshakeInterval
ZMQ_HANDSHAKE_IVL
Handshaking is the exchange of socket configuration information (socket type, identity, security) that occurs when a connection is first opened (only for connection-oriented transports). If handshaking does not complete within the configured time, the connection shall be closed. The value 0 means no handshake time limit.
heartbeatInterval
ZMQ_HEARTBEAT_IVL
Interval in milliseconds between sending ZMTP heartbeats for the specified socket. If this option is greater than 0, then a PING ZMTP command will be sent after every interval.
heartbeatTimeout
ZMQ_HEARTBEAT_TIMEOUT
How long (in milliseconds) to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic. This option is only valid if heartbeatInterval is greater than 0. The connection will time out if there is no traffic received after sending the PING command. The received traffic does not have to be a PONG command - any received traffic will cancel the timeout.
heartbeatTimeToLive
ZMQ_HEARTBEAT_TTL
The timeout in milliseconds on the remote peer for ZMTP heartbeats. If this option is greater than 0, the remote side shall time out the connection if it does not receive any more traffic within the TTL period. This option does not have any effect if heartbeatInterval is 0. Internally, this value is rounded down to the nearest decisecond, any value less than 100 will have no effect.
immediate
ZMQ_IMMEDIATE
By default queues will fill on outgoing connections even if the connection has not completed. This can lead to "lost" messages on sockets with round-robin routing (Request, Push, Dealer). If this option is set to true, messages shall be queued only to completed connections. This will cause the socket to block if there are no other connections, but will prevent queues from filling on pipes awaiting connection.
interface
ZMQ_BINDTODEVICE
Binds the socket to the given network interface (Linux only). Allows to use Linux VRF, see: https://www.kernel.org/doc/Documentation/networking/vrf.txt. Requires the program to be ran as root or with CAP_NET_RAW.
invertMatching
ZMQ_INVERT_MATCHING
Causes incoming messages that do not match any of the socket's subscriptions to be received by the user.
All Subscriber sockets connecting to a Publisher must also have the option set to true. Failure to do so will have the Subscriber sockets reject everything the Publisher socket sends them.
ipv6
ZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
ReadonlylastEndpoint
ZMQ_LAST_ENDPOINT
The last endpoint bound for TCP and IPC transports.
linger
ZMQ_LINGER
Determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with close().
loopbackFastPath
ZMQ_LOOPBACK_FASTPATH
Enable faster TCP connections on loopback devices. An application can enable this option to reduce the latency and improve the performance of loopback operations on a TCP socket on Windows.
maxMessageSize
ZMQ_MAXMSGSIZE
Limits the size of the inbound message. If a peer sends a message larger than the limit it is disconnected. Value of -1 means no limit.
multicastMaxTransportDataUnit
ZMQ_MULTICAST_MAXTPDU
Sets the maximum transport data unit size used for outbound multicast packets. This must be set at or below the minimum Maximum Transmission Unit (MTU) for all network paths over which multicast reception is required.
plainPassword
ZMQ_PLAIN_PASSWORD
Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
plainServer
ZMQ_PLAIN_SERVER
Defines whether the socket will act as server for PLAIN security. A value of true means the socket will act as PLAIN server. A value of false means the socket will not act as PLAIN server, and its security role then depends on other option settings.
plainUsername
ZMQ_PLAIN_USERNAME
Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
rate
ZMQ_RATE
Maximum send or receive data rate for multicast transports such as pgm.
Readonlyreadable
Whether any messages are currently available. If true, the next call to Readable.receive() will immediately read a message from the socket. For sockets that cannot receive messsages this is always false.
receiveBufferSize
ZMQ_RCVBUF
Underlying kernel receive buffer size in bytes. A value of -1 means leave the OS default unchanged.
receiveHighWaterMark
ZMQ_RCVHWM
The high water mark is a hard limit on the maximum number of incoming messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
receiveTimeout
ZMQ_RCVTIMEO
Sets the timeout receiving messages on the socket. If the value is 0, receive() will return a rejected promise immediately if there is no message to receive. If the value is -1, it will wait asynchronously until a message is available. For all other values, it will wait for a message for that amount of time before rejecting.
reconnectInterval
ZMQ_RECONNECT_IVL
Period ØMQ shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. The value -1 means no reconnection.
reconnectMaxInterval
ZMQ_RECONNECT_IVL_MAX
Maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled until reconnectMaxInterval is reached. This allows for exponential backoff strategy. Zero (the default) means no exponential backoff is performed and reconnect interval calculations are only based on reconnectInterval.
recoveryInterval
ZMQ_RECOVERY_IVL
Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
ReadonlysecurityMechanism
| null
| "plain"
| "curve"
| "gssapi"
ZMQ_MECHANISM
Returns the current security mechanism for the socket, if any. The security mechanism is set implictly by using any of the relevant security options. The returned value is one of:
null- No security mechanism is used."plain"- The PLAIN mechanism defines a simple username/password mechanism that lets a server authenticate a client. PLAIN makes no attempt at security or confidentiality."curve"- The CURVE mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server. CURVE is intended for use on public networks."gssapi"- The GSSAPI mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server using the Generic Security Service Application Program Interface (GSSAPI). The GSSAPI mechanism can be used on both public and private networks.
socksProxy
ZMQ_SOCKS_PROXY
The SOCKS5 proxy address that shall be used by the socket for the TCP connection(s). Does not support SOCKS5 authentication. If the endpoints are domain names instead of addresses they shall not be resolved and they shall be forwarded unchanged to the SOCKS proxy service in the client connection request message (address type 0x03 domain name).
tcpAcceptFilter
ZMQ_TCP_ACCEPT_FILTER
Assign a filter that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one filter is applied then new connection source IP should be matched. To clear all filters set to null. Filter is a string with IPv6 or IPv4 CIDR.
tcpKeepalive
ZMQ_TCP_KEEPALIVE
Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveCount
ZMQ_TCP_KEEPALIVE_CNT
Overrides TCP_KEEPCNT socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveIdle
ZMQ_TCP_KEEPALIVE_IDLE
Overrides TCP_KEEPIDLE / TCP_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveInterval
ZMQ_TCP_KEEPALIVE_INTVL
Overrides TCP_KEEPINTVL socket option (if supported by the OS). The default value of -1 leaves it to the OS default.
tcpMaxRetransmitTimeout
ZMQ_TCP_MAXRT
Sets how long before an unacknowledged TCP retransmit times out (if supported by the OS). The system normally attempts many TCP retransmits following an exponential backoff strategy. This means that after a network outage, it may take a long time before the session can be re-established. Setting this option allows the timeout to happen at a shorter interval.
ReadonlythreadSafe
ZMQ_THREAD_SAFE
Whether or not the socket is threadsafe. Currently only DRAFT sockets is thread-safe.
Readonlytype
ZMQ_TYPE
Retrieve the socket type. This is fairly useless because you can test the socket class with e.g. socket instanceof Dealer.
typeOfService
ZMQ_TOS
Sets the ToS fields (the Differentiated Services (DS) and Explicit Congestion Notification (ECN) field) of the IP header. The ToS field is typically used to specify a packet's priority. The availability of this option is dependent on intermediate network equipment that inspect the ToS field and provide a path for low-delay, high-throughput, highly-reliable service, etc.
vmciBufferMaxSize
ZMQ_VMCI_BUFFER_MAX_SIZE
Maximum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferMinSize
ZMQ_VMCI_BUFFER_MIN_SIZE
Minimum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferSize
ZMQ_VMCI_BUFFER_SIZE
The size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciConnectTimeout
ZMQ_VMCI_CONNECT_TIMEOUT
Connection timeout for the socket. For vmci:// transports only.
Readonlywritable
Whether any messages can be queued for sending. If true, the next call to Writable.send() will immediately queue a message on the socket. For sockets that cannot send messsages this is always false.
zapDomain
ZMQ_ZAP_DOMAIN
Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the default on all tcp:// connections), ZAP authentication only happens if you set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 for more details.
zapEnforceDomain
ZMQ_ZAP_ENFORCE_DOMAIN
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.
Methods
[asyncIterator]
- [async
Iterator] (): AsyncIterator<Buffer[], undefined, undefined> Asynchronously iterate over messages becoming available on the socket. When the socket is closed with Socket.close(), the iterator will return. Returning early from the iterator will not close the socket unless it also goes out of scope.
for await (const [msg] of socket) {
// handle messages
} -Returns AsyncIterator<Buffer[], undefined, undefined>
bind
- bind(address): Promise<void>
Binds the socket to the given address. During bind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.You can use
*in place of a hostname to bind on all interfaces/addresses, and you can use*in place of a port to bind to a random port (which can be retrieved with lastEndpoint later).await socket.bind("tcp://127.0.0.1:3456")
await socket.bind("tcp://*:3456") // binds on all interfaces
await socket.bind("tcp://127.0.0.1:*") // binds on random port -Parameters
- address: string
Address to bind this socket to.
Returns Promise<void>
Resolved when the socket was successfully bound.
- address: string
close
- close(): void
Closes the socket and disposes of all resources. Any messages that are queued may be discarded or sent in the background depending on the linger setting.
After this method is called, it is no longer possible to call any other methods on this socket.
Sockets that go out of scope and have no Readable.receive() or Writable.send() operations in progress will automatically be closed. Therefore it is not necessary in most applications to call close() manually.
Calling this method on a socket that is already closed is a no-op.
Returns void
connect
disconnect
- disconnect(address): void
Disconnects a previously connected socket from the given address and returns immediately. Disonnection will happen asynchronously in the background.
socket.disconnect("tcp://127.0.0.1:3456") -Parameters
- address: string
The previously connected address to disconnect from.
Returns void
- address: string
ProtectedgetBoolOption
ProtectedgetInt32Option
ProtectedgetInt64Option
ProtectedgetStringOption
ProtectedgetUint32Option
ProtectedgetUint64Option
receive
- receive(): Promise<Buffer[]>
Waits for the next single or multipart message to become availeble on the socket. Reads a message immediately if possible. If no messages can be read, it will wait asynchonously. The promise will be resolved with an array containing the parts of the next message when available.
const [msg] = await socket.receive()
const [part1, part2] = await socket.receive() -Reading may fail (eventually) if the socket has been configured with a receiveTimeout.
A call to receive() is guaranteed to return with a resolved promise immediately if a message could be read from the socket directly.
Only one asynchronously blocking call to receive() can be in progress simultaneously. If you call receive() again on the same socket it will return a rejected promise with an
EBUSYerror. For example, if no messages can be read and noawaitis used:socket.receive() // -> pending promise until read is possible
socket.receive() // -> promise rejection with `EBUSY` error -Note: Due to the nature of Node.js and to avoid blocking the main thread, this method always attempts to read messages with the
ZMQ_DONTWAITflag. It polls asynchronously if reading is not currently possible. This means that all functionality related to timeouts and blocking behaviour is reimplemented in the Node.js bindings. Any differences in behaviour with the native ZMQ library is considered a bug.Returns Promise<Buffer[]>
Resolved with message parts that were successfully read.
ProtectedsetBoolOption
ProtectedsetInt32Option
ProtectedsetInt64Option
ProtectedsetStringOption
ProtectedsetUint32Option
ProtectedsetUint64Option
subscribe
- subscribe(...prefixes): void
Establish a new message filter. Newly created Subsriber sockets will filtered out all incoming messages. Call this method to subscribe to messages beginning with the given prefix.
Multiple filters may be attached to a single socket, in which case a message shall be accepted if it matches at least one filter. Subscribing without any filters shall subscribe to all incoming messages.
const sub = new Subscriber()
// Listen to all messages beginning with 'foo'.
sub.subscribe("foo")
// Listen to all incoming messages.
sub.subscribe() -Parameters
Rest...prefixes: (string | Buffer)[]The prefixes of messages to subscribe to.
Returns void
unbind
- unbind(address): Promise<void>
Unbinds the socket to the given address. During unbind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.Parameters
- address: string
Address to unbind this socket from.
Returns Promise<void>
Resolved when the socket was successfully unbound.
- address: string
unsubscribe
- unsubscribe(...prefixes): void
Remove an existing message filter which was previously established with subscribe(). Stops receiving messages with the given prefix.
Unsubscribing without any filters shall unsubscribe from the "subscribe all" filter that is added by calling subscribe() without arguments.
const sub = new Subscriber()
// Listen to all messages beginning with 'foo'.
sub.subscribe("foo")
// ...
// Stop listening to messages beginning with 'foo'.
sub.unsubscribe("foo") -Parameters
Rest...prefixes: (string | Buffer)[]The prefixes of messages to subscribe to.
Returns void
Class Subscriber
A Subscriber socket is used to subscribe to data distributed by a Publisher. Initially a Subscriber is not subscribed to any messages. Use Subscriber.subscribe() to specify which messages to subscribe to. This socket cannot send messages.
Hierarchy (View Summary)
Index
Constructors
Properties
Methods
Constructors
constructor
- new Subscriber(
options?: {
affinity?: number;
backlog?: number;
conflate?: boolean;
connectTimeout?: number;
context?: Context;
curvePublicKey?: null | string;
curveSecretKey?: null | string;
curveServer?: boolean;
curveServerKey?: null | string;
gssapiPlainText?: boolean;
gssapiPrincipal?: null | string;
gssapiPrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
gssapiServer?: boolean;
gssapiServicePrincipal?: null | string;
gssapiServicePrincipalNameType?:
| "hostBased"
| "userName"
| "krb5Principal";
handshakeInterval?: number;
heartbeatInterval?: number;
heartbeatTimeout?: number;
heartbeatTimeToLive?: number;
immediate?: boolean;
interface?: null
| string;
invertMatching?: boolean;
ipv6?: boolean;
linger?: number;
loopbackFastPath?: boolean;
maxMessageSize?: number;
multicastMaxTransportDataUnit?: number;
plainPassword?: null | string;
plainServer?: boolean;
plainUsername?: null | string;
rate?: number;
receiveBufferSize?: number;
receiveHighWaterMark?: number;
receiveTimeout?: number;
reconnectInterval?: number;
reconnectMaxInterval?: number;
recoveryInterval?: number;
socksProxy?: null | string;
tcpAcceptFilter?: null | string;
tcpKeepalive?: number;
tcpKeepaliveCount?: number;
tcpKeepaliveIdle?: number;
tcpKeepaliveInterval?: number;
tcpMaxRetransmitTimeout?: number;
typeOfService?: number;
vmciBufferMaxSize?: number;
vmciBufferMinSize?: number;
vmciBufferSize?: number;
vmciConnectTimeout?: number;
zapDomain?: null | string;
zapEnforceDomain?: boolean;
},
): Subscriber Parameters
Optionaloptions: {
affinity?: number;
backlog?: number;
conflate?: boolean;
connectTimeout?: number;
context?: Context;
curvePublicKey?: null | string;
curveSecretKey?: null | string;
curveServer?: boolean;
curveServerKey?: null | string;
gssapiPlainText?: boolean;
gssapiPrincipal?: null | string;
gssapiPrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
gssapiServer?: boolean;
gssapiServicePrincipal?: null | string;
gssapiServicePrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
handshakeInterval?: number;
heartbeatInterval?: number;
heartbeatTimeout?: number;
heartbeatTimeToLive?: number;
immediate?: boolean;
interface?: null | string;
invertMatching?: boolean;
ipv6?: boolean;
linger?: number;
loopbackFastPath?: boolean;
maxMessageSize?: number;
multicastMaxTransportDataUnit?: number;
plainPassword?: null | string;
plainServer?: boolean;
plainUsername?: null | string;
rate?: number;
receiveBufferSize?: number;
receiveHighWaterMark?: number;
receiveTimeout?: number;
reconnectInterval?: number;
reconnectMaxInterval?: number;
recoveryInterval?: number;
socksProxy?: null | string;
tcpAcceptFilter?: null | string;
tcpKeepalive?: number;
tcpKeepaliveCount?: number;
tcpKeepaliveIdle?: number;
tcpKeepaliveInterval?: number;
tcpMaxRetransmitTimeout?: number;
typeOfService?: number;
vmciBufferMaxSize?: number;
vmciBufferMinSize?: number;
vmciBufferSize?: number;
vmciConnectTimeout?: number;
zapDomain?: null | string;
zapEnforceDomain?: boolean;
}Optionalaffinity?: numberZMQ_AFFINITY
I/O thread affinity, which determines which threads from the ØMQ I/O thread pool associated with the socket's context shall handle newly created connections.
Note: This value is a bit mask, but values higher than
Number.MAX_SAFE_INTEGERmay not be represented accurately! This currently means that configurations beyond 52 threads are unreliable.Optionalbacklog?: numberZMQ_BACKLOG
Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.
Optionalconflate?: booleanZMQ_CONFLATE
If set to
true, a socket shall keep only one message in its inbound/outbound queue: the last message to be received/sent. Ignores any high water mark options. Does not support multi-part messages - in particular, only one part of it is kept in the socket internal queue.OptionalconnectTimeout?: numberZMQ_CONNECT_TIMEOUT
Sets how long to wait before timing-out a connect() system call. The connect() system call normally takes a long time before it returns a time out error. Setting this option allows the library to time out the call at an earlier interval.
Optionalcontext?: ContextOptionalcurvePublicKey?: null | stringZMQ_CURVE_PUBLICKEY
Sets the socket's long term public key. You must set this on CURVE client sockets. A server socket does not need to know its own public key. You can create a new keypair with curveKeyPair().
OptionalcurveSecretKey?: null | stringZMQ_CURVE_SECRETKEY
Sets the socket's long term secret key. You must set this on both CURVE client and server sockets. You can create a new keypair with curveKeyPair().
OptionalcurveServer?: booleanZMQ_CURVE_SERVER
Defines whether the socket will act as server for CURVE security. A value of
truemeans the socket will act as CURVE server. A value offalsemeans the socket will not act as CURVE server, and its security role then depends on other option settings.OptionalcurveServerKey?: null | stringZMQ_CURVE_SERVERKEY
Sets the socket's long term server key. This is the public key of the CURVE server socket. You must set this on CURVE client sockets. This key must have been generated together with the server's secret key. You can create a new keypair with curveKeyPair().
OptionalgssapiPlainText?: booleanOptionalgssapiPrincipal?: null | stringOptionalgssapiPrincipalNameType?: "hostBased" | "userName" | "krb5Principal"OptionalgssapiServer?: booleanOptionalgssapiServicePrincipal?: null | stringOptionalgssapiServicePrincipalNameType?: "hostBased" | "userName" | "krb5Principal"OptionalhandshakeInterval?: numberZMQ_HANDSHAKE_IVL
Handshaking is the exchange of socket configuration information (socket type, identity, security) that occurs when a connection is first opened (only for connection-oriented transports). If handshaking does not complete within the configured time, the connection shall be closed. The value 0 means no handshake time limit.
OptionalheartbeatInterval?: numberZMQ_HEARTBEAT_IVL
Interval in milliseconds between sending ZMTP heartbeats for the specified socket. If this option is greater than 0, then a PING ZMTP command will be sent after every interval.
OptionalheartbeatTimeout?: numberZMQ_HEARTBEAT_TIMEOUT
How long (in milliseconds) to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic. This option is only valid if heartbeatInterval is greater than 0. The connection will time out if there is no traffic received after sending the PING command. The received traffic does not have to be a PONG command - any received traffic will cancel the timeout.
OptionalheartbeatTimeToLive?: numberZMQ_HEARTBEAT_TTL
The timeout in milliseconds on the remote peer for ZMTP heartbeats. If this option is greater than 0, the remote side shall time out the connection if it does not receive any more traffic within the TTL period. This option does not have any effect if heartbeatInterval is 0. Internally, this value is rounded down to the nearest decisecond, any value less than 100 will have no effect.
Optionalimmediate?: booleanZMQ_IMMEDIATE
By default queues will fill on outgoing connections even if the connection has not completed. This can lead to "lost" messages on sockets with round-robin routing (Request, Push, Dealer). If this option is set to
true, messages shall be queued only to completed connections. This will cause the socket to block if there are no other connections, but will prevent queues from filling on pipes awaiting connection.Optionalinterface?: null | stringZMQ_BINDTODEVICE
Binds the socket to the given network interface (Linux only). Allows to use Linux VRF, see: https://www.kernel.org/doc/Documentation/networking/vrf.txt. Requires the program to be ran as root or with
CAP_NET_RAW.OptionalinvertMatching?: booleanZMQ_INVERT_MATCHING
Causes incoming messages that do not match any of the socket's subscriptions to be received by the user.
All Subscriber sockets connecting to a Publisher must also have the option set to
true. Failure to do so will have the Subscriber sockets reject everything the Publisher socket sends them.Optionalipv6?: booleanZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
Optionallinger?: numberZMQ_LINGER
Determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with close().
OptionalloopbackFastPath?: booleanZMQ_LOOPBACK_FASTPATH
Enable faster TCP connections on loopback devices. An application can enable this option to reduce the latency and improve the performance of loopback operations on a TCP socket on Windows.
OptionalmaxMessageSize?: numberZMQ_MAXMSGSIZE
Limits the size of the inbound message. If a peer sends a message larger than the limit it is disconnected. Value of -1 means no limit.
OptionalmulticastMaxTransportDataUnit?: numberZMQ_MULTICAST_MAXTPDU
Sets the maximum transport data unit size used for outbound multicast packets. This must be set at or below the minimum Maximum Transmission Unit (MTU) for all network paths over which multicast reception is required.
OptionalplainPassword?: null | stringZMQ_PLAIN_PASSWORD
Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
OptionalplainServer?: booleanZMQ_PLAIN_SERVER
Defines whether the socket will act as server for PLAIN security. A value of
truemeans the socket will act as PLAIN server. A value offalsemeans the socket will not act as PLAIN server, and its security role then depends on other option settings.OptionalplainUsername?: null | stringZMQ_PLAIN_USERNAME
Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
Optionalrate?: numberZMQ_RATE
Maximum send or receive data rate for multicast transports such as
pgm.OptionalreceiveBufferSize?: numberZMQ_RCVBUF
Underlying kernel receive buffer size in bytes. A value of -1 means leave the OS default unchanged.
OptionalreceiveHighWaterMark?: numberZMQ_RCVHWM
The high water mark is a hard limit on the maximum number of incoming messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
OptionalreceiveTimeout?: numberZMQ_RCVTIMEO
Sets the timeout receiving messages on the socket. If the value is 0, receive() will return a rejected promise immediately if there is no message to receive. If the value is -1, it will wait asynchronously until a message is available. For all other values, it will wait for a message for that amount of time before rejecting.
OptionalreconnectInterval?: numberZMQ_RECONNECT_IVL
Period ØMQ shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. The value -1 means no reconnection.
OptionalreconnectMaxInterval?: numberZMQ_RECONNECT_IVL_MAX
Maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled until reconnectMaxInterval is reached. This allows for exponential backoff strategy. Zero (the default) means no exponential backoff is performed and reconnect interval calculations are only based on reconnectInterval.
OptionalrecoveryInterval?: numberZMQ_RECOVERY_IVL
Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
OptionalsocksProxy?: null | stringZMQ_SOCKS_PROXY
The SOCKS5 proxy address that shall be used by the socket for the TCP connection(s). Does not support SOCKS5 authentication. If the endpoints are domain names instead of addresses they shall not be resolved and they shall be forwarded unchanged to the SOCKS proxy service in the client connection request message (address type 0x03 domain name).
OptionaltcpAcceptFilter?: null | stringZMQ_TCP_ACCEPT_FILTER
Assign a filter that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one filter is applied then new connection source IP should be matched. To clear all filters set to
null. Filter is a string with IPv6 or IPv4 CIDR.OptionaltcpKeepalive?: numberZMQ_TCP_KEEPALIVE
Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepaliveCount?: numberZMQ_TCP_KEEPALIVE_CNT
Overrides TCP_KEEPCNT socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepaliveIdle?: numberZMQ_TCP_KEEPALIVE_IDLE
Overrides TCP_KEEPIDLE / TCP_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepaliveInterval?: numberZMQ_TCP_KEEPALIVE_INTVL
Overrides TCP_KEEPINTVL socket option (if supported by the OS). The default value of -1 leaves it to the OS default.
OptionaltcpMaxRetransmitTimeout?: numberZMQ_TCP_MAXRT
Sets how long before an unacknowledged TCP retransmit times out (if supported by the OS). The system normally attempts many TCP retransmits following an exponential backoff strategy. This means that after a network outage, it may take a long time before the session can be re-established. Setting this option allows the timeout to happen at a shorter interval.
OptionaltypeOfService?: numberZMQ_TOS
Sets the ToS fields (the Differentiated Services (DS) and Explicit Congestion Notification (ECN) field) of the IP header. The ToS field is typically used to specify a packet's priority. The availability of this option is dependent on intermediate network equipment that inspect the ToS field and provide a path for low-delay, high-throughput, highly-reliable service, etc.
OptionalvmciBufferMaxSize?: numberZMQ_VMCI_BUFFER_MAX_SIZE
Maximum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciBufferMinSize?: numberZMQ_VMCI_BUFFER_MIN_SIZE
Minimum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciBufferSize?: numberZMQ_VMCI_BUFFER_SIZE
The size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciConnectTimeout?: numberZMQ_VMCI_CONNECT_TIMEOUT
Connection timeout for the socket. For
vmci://transports only.OptionalzapDomain?: null | stringZMQ_ZAP_DOMAIN
Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the default on all
tcp://connections), ZAP authentication only happens if you set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 for more details.OptionalzapEnforceDomain?: booleanZMQ_ZAP_ENFORCE_DOMAIN
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.
Returns Subscriber
Properties
affinity
ZMQ_AFFINITY
I/O thread affinity, which determines which threads from the ØMQ I/O thread pool associated with the socket's context shall handle newly created connections.
Note: This value is a bit mask, but values higher than Number.MAX_SAFE_INTEGER may not be represented accurately! This currently means that configurations beyond 52 threads are unreliable.
backlog
ZMQ_BACKLOG
Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.
Readonlyclosed
Whether this socket was previously closed with close().
conflate
ZMQ_CONFLATE
If set to true, a socket shall keep only one message in its inbound/outbound queue: the last message to be received/sent. Ignores any high water mark options. Does not support multi-part messages - in particular, only one part of it is kept in the socket internal queue.
connectTimeout
ZMQ_CONNECT_TIMEOUT
Sets how long to wait before timing-out a connect() system call. The connect() system call normally takes a long time before it returns a time out error. Setting this option allows the library to time out the call at an earlier interval.
Readonlycontext
Context that this socket belongs to.
curvePublicKey
ZMQ_CURVE_PUBLICKEY
Sets the socket's long term public key. You must set this on CURVE client sockets. A server socket does not need to know its own public key. You can create a new keypair with curveKeyPair().
curveSecretKey
ZMQ_CURVE_SECRETKEY
Sets the socket's long term secret key. You must set this on both CURVE client and server sockets. You can create a new keypair with curveKeyPair().
curveServer
ZMQ_CURVE_SERVER
Defines whether the socket will act as server for CURVE security. A value of true means the socket will act as CURVE server. A value of false means the socket will not act as CURVE server, and its security role then depends on other option settings.
curveServerKey
ZMQ_CURVE_SERVERKEY
Sets the socket's long term server key. This is the public key of the CURVE server socket. You must set this on CURVE client sockets. This key must have been generated together with the server's secret key. You can create a new keypair with curveKeyPair().
Readonlyevents
Event Observer for this socket. This starts up a ØMQ monitoring socket internally that receives all socket events.
gssapiPlainText
gssapiPrincipal
gssapiPrincipalNameType
gssapiServer
gssapiServicePrincipal
gssapiServicePrincipalNameType
handshakeInterval
ZMQ_HANDSHAKE_IVL
Handshaking is the exchange of socket configuration information (socket type, identity, security) that occurs when a connection is first opened (only for connection-oriented transports). If handshaking does not complete within the configured time, the connection shall be closed. The value 0 means no handshake time limit.
heartbeatInterval
ZMQ_HEARTBEAT_IVL
Interval in milliseconds between sending ZMTP heartbeats for the specified socket. If this option is greater than 0, then a PING ZMTP command will be sent after every interval.
heartbeatTimeout
ZMQ_HEARTBEAT_TIMEOUT
How long (in milliseconds) to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic. This option is only valid if heartbeatInterval is greater than 0. The connection will time out if there is no traffic received after sending the PING command. The received traffic does not have to be a PONG command - any received traffic will cancel the timeout.
heartbeatTimeToLive
ZMQ_HEARTBEAT_TTL
The timeout in milliseconds on the remote peer for ZMTP heartbeats. If this option is greater than 0, the remote side shall time out the connection if it does not receive any more traffic within the TTL period. This option does not have any effect if heartbeatInterval is 0. Internally, this value is rounded down to the nearest decisecond, any value less than 100 will have no effect.
immediate
ZMQ_IMMEDIATE
By default queues will fill on outgoing connections even if the connection has not completed. This can lead to "lost" messages on sockets with round-robin routing (Request, Push, Dealer). If this option is set to true, messages shall be queued only to completed connections. This will cause the socket to block if there are no other connections, but will prevent queues from filling on pipes awaiting connection.
interface
ZMQ_BINDTODEVICE
Binds the socket to the given network interface (Linux only). Allows to use Linux VRF, see: https://www.kernel.org/doc/Documentation/networking/vrf.txt. Requires the program to be ran as root or with CAP_NET_RAW.
invertMatching
ZMQ_INVERT_MATCHING
Causes incoming messages that do not match any of the socket's subscriptions to be received by the user.
All Subscriber sockets connecting to a Publisher must also have the option set to true. Failure to do so will have the Subscriber sockets reject everything the Publisher socket sends them.
ipv6
ZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
ReadonlylastEndpoint
ZMQ_LAST_ENDPOINT
The last endpoint bound for TCP and IPC transports.
linger
ZMQ_LINGER
Determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with close().
loopbackFastPath
ZMQ_LOOPBACK_FASTPATH
Enable faster TCP connections on loopback devices. An application can enable this option to reduce the latency and improve the performance of loopback operations on a TCP socket on Windows.
maxMessageSize
ZMQ_MAXMSGSIZE
Limits the size of the inbound message. If a peer sends a message larger than the limit it is disconnected. Value of -1 means no limit.
multicastMaxTransportDataUnit
ZMQ_MULTICAST_MAXTPDU
Sets the maximum transport data unit size used for outbound multicast packets. This must be set at or below the minimum Maximum Transmission Unit (MTU) for all network paths over which multicast reception is required.
plainPassword
ZMQ_PLAIN_PASSWORD
Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
plainServer
ZMQ_PLAIN_SERVER
Defines whether the socket will act as server for PLAIN security. A value of true means the socket will act as PLAIN server. A value of false means the socket will not act as PLAIN server, and its security role then depends on other option settings.
plainUsername
ZMQ_PLAIN_USERNAME
Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
rate
ZMQ_RATE
Maximum send or receive data rate for multicast transports such as pgm.
Readonlyreadable
Whether any messages are currently available. If true, the next call to Readable.receive() will immediately read a message from the socket. For sockets that cannot receive messsages this is always false.
receiveBufferSize
ZMQ_RCVBUF
Underlying kernel receive buffer size in bytes. A value of -1 means leave the OS default unchanged.
receiveHighWaterMark
ZMQ_RCVHWM
The high water mark is a hard limit on the maximum number of incoming messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
receiveTimeout
ZMQ_RCVTIMEO
Sets the timeout receiving messages on the socket. If the value is 0, receive() will return a rejected promise immediately if there is no message to receive. If the value is -1, it will wait asynchronously until a message is available. For all other values, it will wait for a message for that amount of time before rejecting.
reconnectInterval
ZMQ_RECONNECT_IVL
Period ØMQ shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. The value -1 means no reconnection.
reconnectMaxInterval
ZMQ_RECONNECT_IVL_MAX
Maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled until reconnectMaxInterval is reached. This allows for exponential backoff strategy. Zero (the default) means no exponential backoff is performed and reconnect interval calculations are only based on reconnectInterval.
recoveryInterval
ZMQ_RECOVERY_IVL
Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
ReadonlysecurityMechanism
ZMQ_MECHANISM
Returns the current security mechanism for the socket, if any. The security mechanism is set implictly by using any of the relevant security options. The returned value is one of:
null- No security mechanism is used."plain"- The PLAIN mechanism defines a simple username/password mechanism that lets a server authenticate a client. PLAIN makes no attempt at security or confidentiality."curve"- The CURVE mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server. CURVE is intended for use on public networks."gssapi"- The GSSAPI mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server using the Generic Security Service Application Program Interface (GSSAPI). The GSSAPI mechanism can be used on both public and private networks.
socksProxy
ZMQ_SOCKS_PROXY
The SOCKS5 proxy address that shall be used by the socket for the TCP connection(s). Does not support SOCKS5 authentication. If the endpoints are domain names instead of addresses they shall not be resolved and they shall be forwarded unchanged to the SOCKS proxy service in the client connection request message (address type 0x03 domain name).
tcpAcceptFilter
ZMQ_TCP_ACCEPT_FILTER
Assign a filter that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one filter is applied then new connection source IP should be matched. To clear all filters set to null. Filter is a string with IPv6 or IPv4 CIDR.
tcpKeepalive
ZMQ_TCP_KEEPALIVE
Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveCount
ZMQ_TCP_KEEPALIVE_CNT
Overrides TCP_KEEPCNT socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveIdle
ZMQ_TCP_KEEPALIVE_IDLE
Overrides TCP_KEEPIDLE / TCP_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveInterval
ZMQ_TCP_KEEPALIVE_INTVL
Overrides TCP_KEEPINTVL socket option (if supported by the OS). The default value of -1 leaves it to the OS default.
tcpMaxRetransmitTimeout
ZMQ_TCP_MAXRT
Sets how long before an unacknowledged TCP retransmit times out (if supported by the OS). The system normally attempts many TCP retransmits following an exponential backoff strategy. This means that after a network outage, it may take a long time before the session can be re-established. Setting this option allows the timeout to happen at a shorter interval.
ReadonlythreadSafe
ZMQ_THREAD_SAFE
Whether or not the socket is threadsafe. Currently only DRAFT sockets is thread-safe.
Readonlytype
ZMQ_TYPE
Retrieve the socket type. This is fairly useless because you can test the socket class with e.g. socket instanceof Dealer.
typeOfService
ZMQ_TOS
Sets the ToS fields (the Differentiated Services (DS) and Explicit Congestion Notification (ECN) field) of the IP header. The ToS field is typically used to specify a packet's priority. The availability of this option is dependent on intermediate network equipment that inspect the ToS field and provide a path for low-delay, high-throughput, highly-reliable service, etc.
vmciBufferMaxSize
ZMQ_VMCI_BUFFER_MAX_SIZE
Maximum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferMinSize
ZMQ_VMCI_BUFFER_MIN_SIZE
Minimum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferSize
ZMQ_VMCI_BUFFER_SIZE
The size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciConnectTimeout
ZMQ_VMCI_CONNECT_TIMEOUT
Connection timeout for the socket. For vmci:// transports only.
Readonlywritable
Whether any messages can be queued for sending. If true, the next call to Writable.send() will immediately queue a message on the socket. For sockets that cannot send messsages this is always false.
zapDomain
ZMQ_ZAP_DOMAIN
Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the default on all tcp:// connections), ZAP authentication only happens if you set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 for more details.
zapEnforceDomain
ZMQ_ZAP_ENFORCE_DOMAIN
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.
Methods
[asyncIterator]
- "[asyncIterator]"(): AsyncIterator<Buffer[]>
Asynchronously iterate over messages becoming available on the socket. When the socket is closed with Socket.close(), the iterator will return. Returning early from the iterator will not close the socket unless it also goes out of scope.
for await (const [msg] of socket) {
// handle messages
} +Returns AsyncIterator<Buffer[]>
bind
- bind(address: string): Promise<void>
Binds the socket to the given address. During bind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.You can use
*in place of a hostname to bind on all interfaces/addresses, and you can use*in place of a port to bind to a random port (which can be retrieved with lastEndpoint later).await socket.bind("tcp://127.0.0.1:3456")
await socket.bind("tcp://*:3456") // binds on all interfaces
await socket.bind("tcp://127.0.0.1:*") // binds on random port +Parameters
- address: string
Address to bind this socket to.
Returns Promise<void>
Resolved when the socket was successfully bound.
- address: string
bindSync
- bindSync(address: string): void
Binds the socket to the given address. During bind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.You can use
*in place of a hostname to bind on all interfaces/addresses, and you can use*in place of a port to bind to a random port (which can be retrieved with lastEndpoint later).socket.bindSync("tcp://127.0.0.1:3456")
socket.bindSync("tcp://*:3456") // binds on all interfaces
socket.bindSync("tcp://127.0.0.1:*") // binds on random port +Parameters
- address: string
Address to bind this socket to.
Returns void
Resolved when the socket was successfully bound.
- address: string
close
- close(): void
Closes the socket and disposes of all resources. Any messages that are queued may be discarded or sent in the background depending on the linger setting.
After this method is called, it is no longer possible to call any other methods on this socket.
Sockets that go out of scope and have no Readable.receive() or Writable.send() operations in progress will automatically be closed. Therefore it is not necessary in most applications to call close() manually.
Calling this method on a socket that is already closed is a no-op.
Returns void
connect
disconnect
- disconnect(address: string): void
Disconnects a previously connected socket from the given address and returns immediately. Disonnection will happen asynchronously in the background.
socket.disconnect("tcp://127.0.0.1:3456") +Parameters
- address: string
The previously connected address to disconnect from.
Returns void
- address: string
ProtectedgetBoolOption
ProtectedgetInt32Option
ProtectedgetInt64Option
ProtectedgetStringOption
ProtectedgetUint32Option
ProtectedgetUint64Option
receive
- receive(): Promise<Buffer[]>
Waits for the next single or multipart message to become availeble on the socket. Reads a message immediately if possible. If no messages can be read, it will wait asynchonously. The promise will be resolved with an array containing the parts of the next message when available.
const [msg] = await socket.receive()
const [part1, part2] = await socket.receive() +Reading may fail (eventually) if the socket has been configured with a receiveTimeout.
A call to receive() is guaranteed to return with a resolved promise immediately if a message could be read from the socket directly.
Only one asynchronously blocking call to receive() can be in progress simultaneously. If you call receive() again on the same socket it will return a rejected promise with an
EBUSYerror. For example, if no messages can be read and noawaitis used:socket.receive() // -> pending promise until read is possible
socket.receive() // -> promise rejection with `EBUSY` error +Note: Due to the nature of Node.js and to avoid blocking the main thread, this method always attempts to read messages with the
ZMQ_DONTWAITflag. It polls asynchronously if reading is not currently possible. This means that all functionality related to timeouts and blocking behaviour is reimplemented in the Node.js bindings. Any differences in behaviour with the native ZMQ library is considered a bug.Returns Promise<Buffer[]>
Resolved with message parts that were successfully read.
ProtectedsetBoolOption
ProtectedsetInt32Option
ProtectedsetInt64Option
ProtectedsetStringOption
ProtectedsetUint32Option
ProtectedsetUint64Option
subscribe
- subscribe(...prefixes: (string | Buffer)[]): void
Establish a new message filter. Newly created Subsriber sockets will filtered out all incoming messages. Call this method to subscribe to messages beginning with the given prefix.
Multiple filters may be attached to a single socket, in which case a message shall be accepted if it matches at least one filter. Subscribing without any filters shall subscribe to all incoming messages.
const sub = new Subscriber()
// Listen to all messages beginning with 'foo'.
sub.subscribe("foo")
// Listen to all incoming messages.
sub.subscribe() +Parameters
- ...prefixes: (string | Buffer)[]
The prefixes of messages to subscribe to.
Returns void
- ...prefixes: (string | Buffer)[]
unbind
- unbind(address: string): Promise<void>
Unbinds the socket to the given address. During unbind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.Parameters
- address: string
Address to unbind this socket from.
Returns Promise<void>
Resolved when the socket was successfully unbound.
- address: string
unbindSync
- unbindSync(address: string): void
Unbinds the socket to the given address. During unbind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.Parameters
- address: string
Address to unbind this socket from.
Returns void
Resolved when the socket was successfully unbound.
- address: string
unsubscribe
- unsubscribe(...prefixes: (string | Buffer)[]): void
Remove an existing message filter which was previously established with subscribe(). Stops receiving messages with the given prefix.
Unsubscribing without any filters shall unsubscribe from the "subscribe all" filter that is added by calling subscribe() without arguments.
const sub = new Subscriber()
// Listen to all messages beginning with 'foo'.
sub.subscribe("foo")
// ...
// Stop listening to messages beginning with 'foo'.
sub.unsubscribe("foo") +Parameters
- ...prefixes: (string | Buffer)[]
The prefixes of messages to subscribe to.
Returns void
- ...prefixes: (string | Buffer)[]
Class XPublisher
Same as Publisher, except that you can receive subscriptions from the peers in form of incoming messages. Subscription message is a byte 1 (for subscriptions) or byte 0 (for unsubscriptions) followed by the subscription body. Messages without a sub/unsub prefix are also received, but have no effect on subscription status.
Hierarchy (view full)
Index
Constructors
Properties
Accessors
Methods
Constructors
constructor
- new XPublisher(options?): XPublisher
Parameters
Optionaloptions: {
affinity?: number;
backlog?: number;
connectTimeout?: number;
context?: Context;
curvePublicKey?: null | string;
curveSecretKey?: null | string;
curveServer?: boolean;
curveServerKey?: null | string;
gssapiPlainText?: boolean;
gssapiPrincipal?: null | string;
gssapiPrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
gssapiServer?: boolean;
gssapiServicePrincipal?: null | string;
gssapiServicePrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
handshakeInterval?: number;
heartbeatInterval?: number;
heartbeatTimeout?: number;
heartbeatTimeToLive?: number;
immediate?: boolean;
interface?: null | string;
invertMatching?: boolean;
ipv6?: boolean;
linger?: number;
loopbackFastPath?: boolean;
manual?: boolean;
maxMessageSize?: number;
multicastHops?: number;
multicastMaxTransportDataUnit?: number;
noDrop?: boolean;
plainPassword?: null | string;
plainServer?: boolean;
plainUsername?: null | string;
rate?: number;
receiveBufferSize?: number;
receiveHighWaterMark?: number;
receiveTimeout?: number;
reconnectInterval?: number;
reconnectMaxInterval?: number;
recoveryInterval?: number;
sendBufferSize?: number;
sendHighWaterMark?: number;
sendTimeout?: number;
socksProxy?: null | string;
tcpAcceptFilter?: null | string;
tcpKeepalive?: number;
tcpKeepaliveCount?: number;
tcpKeepaliveIdle?: number;
tcpKeepaliveInterval?: number;
tcpMaxRetransmitTimeout?: number;
typeOfService?: number;
verbosity:
| undefined
| null
| "allSubs"
| "allSubsUnsubs";
vmciBufferMaxSize?: number;
vmciBufferMinSize?: number;
vmciBufferSize?: number;
vmciConnectTimeout?: number;
welcomeMessage?: null | string;
zapDomain?: null | string;
zapEnforceDomain?: boolean;
}Optionalaffinity?: numberZMQ_AFFINITY
I/O thread affinity, which determines which threads from the ØMQ I/O thread pool associated with the socket's context shall handle newly created connections.
Note: This value is a bit mask, but values higher than
Number.MAX_SAFE_INTEGERmay not be represented accurately! This currently means that configurations beyond 52 threads are unreliable.Optionalbacklog?: numberZMQ_BACKLOG
Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.
OptionalconnectTimeout ?: numberZMQ_CONNECT_TIMEOUT
Sets how long to wait before timing-out a connect() system call. The connect() system call normally takes a long time before it returns a time out error. Setting this option allows the library to time out the call at an earlier interval.
Optionalcontext?: ContextOptionalcurvePublic ?: null | stringKey ZMQ_CURVE_PUBLICKEY
Sets the socket's long term public key. You must set this on CURVE client sockets. A server socket does not need to know its own public key. You can create a new keypair with curveKeyPair().
OptionalcurveSecret ?: null | stringKey ZMQ_CURVE_SECRETKEY
Sets the socket's long term secret key. You must set this on both CURVE client and server sockets. You can create a new keypair with curveKeyPair().
OptionalcurveServer ?: booleanZMQ_CURVE_SERVER
Defines whether the socket will act as server for CURVE security. A value of
truemeans the socket will act as CURVE server. A value offalsemeans the socket will not act as CURVE server, and its security role then depends on other option settings.OptionalcurveServer ?: null | stringKey ZMQ_CURVE_SERVERKEY
Sets the socket's long term server key. This is the public key of the CURVE server socket. You must set this on CURVE client sockets. This key must have been generated together with the server's secret key. You can create a new keypair with curveKeyPair().
OptionalgssapiPlain ?: booleanText OptionalgssapiPrincipal ?: null | stringOptionalgssapiPrincipal ?: "hostBased" | "userName" | "krb5Principal"Name Type OptionalgssapiServer ?: booleanOptionalgssapiService ?: null | stringPrincipal OptionalgssapiService ?: "hostBased" | "userName" | "krb5Principal"Principal Name Type OptionalhandshakeInterval ?: numberZMQ_HANDSHAKE_IVL
Handshaking is the exchange of socket configuration information (socket type, identity, security) that occurs when a connection is first opened (only for connection-oriented transports). If handshaking does not complete within the configured time, the connection shall be closed. The value 0 means no handshake time limit.
OptionalheartbeatInterval ?: numberZMQ_HEARTBEAT_IVL
Interval in milliseconds between sending ZMTP heartbeats for the specified socket. If this option is greater than 0, then a PING ZMTP command will be sent after every interval.
OptionalheartbeatTimeout ?: numberZMQ_HEARTBEAT_TIMEOUT
How long (in milliseconds) to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic. This option is only valid if heartbeatInterval is greater than 0. The connection will time out if there is no traffic received after sending the PING command. The received traffic does not have to be a PONG command - any received traffic will cancel the timeout.
OptionalheartbeatTime ?: numberTo Live ZMQ_HEARTBEAT_TTL
The timeout in milliseconds on the remote peer for ZMTP heartbeats. If this option is greater than 0, the remote side shall time out the connection if it does not receive any more traffic within the TTL period. This option does not have any effect if heartbeatInterval is 0. Internally, this value is rounded down to the nearest decisecond, any value less than 100 will have no effect.
Optionalimmediate?: booleanZMQ_IMMEDIATE
By default queues will fill on outgoing connections even if the connection has not completed. This can lead to "lost" messages on sockets with round-robin routing (Request, Push, Dealer). If this option is set to
true, messages shall be queued only to completed connections. This will cause the socket to block if there are no other connections, but will prevent queues from filling on pipes awaiting connection.Optionalinterface?: null | stringZMQ_BINDTODEVICE
Binds the socket to the given network interface (Linux only). Allows to use Linux VRF, see: https://www.kernel.org/doc/Documentation/networking/vrf.txt. Requires the program to be ran as root or with
CAP_NET_RAW.OptionalinvertMatching ?: booleanZMQ_INVERT_MATCHING
Causes messages to be sent to all connected sockets except those subscribed to a prefix that matches the message.
Optionalipv6?: booleanZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
Optionallinger?: numberZMQ_LINGER
Determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with close().
OptionalloopbackFast ?: booleanPath ZMQ_LOOPBACK_FASTPATH
Enable faster TCP connections on loopback devices. An application can enable this option to reduce the latency and improve the performance of loopback operations on a TCP socket on Windows.
Optionalmanual?: booleanZMQ_XPUB_MANUAL
Sets the XPublisher socket subscription handling mode to manual/automatic. A value of
truewill change the subscription requests handling to manual.OptionalmaxMessage ?: numberSize ZMQ_MAXMSGSIZE
Limits the size of the inbound message. If a peer sends a message larger than the limit it is disconnected. Value of -1 means no limit.
OptionalmulticastHops ?: numberZMQ_MULTICAST_HOPS
Sets the time-to-live field in every multicast packet sent from this socket. The default is 1 which means that the multicast packets don't leave the local network.
OptionalmulticastMax ?: numberTransport Data Unit ZMQ_MULTICAST_MAXTPDU
Sets the maximum transport data unit size used for outbound multicast packets. This must be set at or below the minimum Maximum Transmission Unit (MTU) for all network paths over which multicast reception is required.
OptionalnoDrop ?: booleanZMQ_XPUB_NODROP
Sets the socket behaviour to return an error if the high water mark is reached and the message could not be send. The default is to drop the message silently when the peer high water mark is reached.
OptionalplainPassword ?: null | stringZMQ_PLAIN_PASSWORD
Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
OptionalplainServer ?: booleanZMQ_PLAIN_SERVER
Defines whether the socket will act as server for PLAIN security. A value of
truemeans the socket will act as PLAIN server. A value offalsemeans the socket will not act as PLAIN server, and its security role then depends on other option settings.OptionalplainUsername ?: null | stringZMQ_PLAIN_USERNAME
Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
Optionalrate?: numberZMQ_RATE
Maximum send or receive data rate for multicast transports such as
pgm.OptionalreceiveBuffer ?: numberSize ZMQ_RCVBUF
Underlying kernel receive buffer size in bytes. A value of -1 means leave the OS default unchanged.
OptionalreceiveHigh ?: numberWater Mark ZMQ_RCVHWM
The high water mark is a hard limit on the maximum number of incoming messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
OptionalreceiveTimeout ?: numberZMQ_RCVTIMEO
Sets the timeout receiving messages on the socket. If the value is 0, receive() will return a rejected promise immediately if there is no message to receive. If the value is -1, it will wait asynchronously until a message is available. For all other values, it will wait for a message for that amount of time before rejecting.
OptionalreconnectInterval ?: numberZMQ_RECONNECT_IVL
Period ØMQ shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. The value -1 means no reconnection.
OptionalreconnectMax ?: numberInterval ZMQ_RECONNECT_IVL_MAX
Maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled until reconnectMaxInterval is reached. This allows for exponential backoff strategy. Zero (the default) means no exponential backoff is performed and reconnect interval calculations are only based on reconnectInterval.
OptionalrecoveryInterval ?: numberZMQ_RECOVERY_IVL
Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
OptionalsendBuffer ?: numberSize ZMQ_SNDBUF
Underlying kernel transmit buffer size in bytes. A value of -1 means leave the OS default unchanged.
OptionalsendHigh ?: numberWater Mark ZMQ_SNDHWM
The high water mark is a hard limit on the maximum number of outgoing messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
OptionalsendTimeout ?: numberZMQ_SNDTIMEO
Sets the timeout for sending messages on the socket. If the value is 0, send() will return a rejected promise immediately if the message cannot be sent. If the value is -1, it will wait asynchronously until the message is sent. For all other values, it will try to send the message for that amount of time before rejecting.
OptionalsocksProxy ?: null | stringZMQ_SOCKS_PROXY
The SOCKS5 proxy address that shall be used by the socket for the TCP connection(s). Does not support SOCKS5 authentication. If the endpoints are domain names instead of addresses they shall not be resolved and they shall be forwarded unchanged to the SOCKS proxy service in the client connection request message (address type 0x03 domain name).
OptionaltcpAccept ?: null | stringFilter ZMQ_TCP_ACCEPT_FILTER
Assign a filter that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one filter is applied then new connection source IP should be matched. To clear all filters set to
null. Filter is a string with IPv6 or IPv4 CIDR.OptionaltcpKeepalive ?: numberZMQ_TCP_KEEPALIVE
Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepalive ?: numberCount ZMQ_TCP_KEEPALIVE_CNT
Overrides TCP_KEEPCNT socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepalive ?: numberIdle ZMQ_TCP_KEEPALIVE_IDLE
Overrides TCP_KEEPIDLE / TCP_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepalive ?: numberInterval ZMQ_TCP_KEEPALIVE_INTVL
Overrides TCP_KEEPINTVL socket option (if supported by the OS). The default value of -1 leaves it to the OS default.
OptionaltcpMax ?: numberRetransmit Timeout ZMQ_TCP_MAXRT
Sets how long before an unacknowledged TCP retransmit times out (if supported by the OS). The system normally attempts many TCP retransmits following an exponential backoff strategy. This means that after a network outage, it may take a long time before the session can be re-established. Setting this option allows the timeout to happen at a shorter interval.
OptionaltypeOf ?: numberService ZMQ_TOS
Sets the ToS fields (the Differentiated Services (DS) and Explicit Congestion Notification (ECN) field) of the IP header. The ToS field is typically used to specify a packet's priority. The availability of this option is dependent on intermediate network equipment that inspect the ToS field and provide a path for low-delay, high-throughput, highly-reliable service, etc.
verbosity:
| undefined
| null
| "allSubs"
| "allSubsUnsubs"OptionalvmciBuffer ?: numberMax Size ZMQ_VMCI_BUFFER_MAX_SIZE
Maximum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciBuffer ?: numberMin Size ZMQ_VMCI_BUFFER_MIN_SIZE
Minimum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciBuffer ?: numberSize ZMQ_VMCI_BUFFER_SIZE
The size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciConnect ?: numberTimeout ZMQ_VMCI_CONNECT_TIMEOUT
Connection timeout for the socket. For
vmci://transports only.OptionalwelcomeMessage ?: null | stringZMQ_XPUB_WELCOME_MSG
Sets a welcome message that will be recieved by subscriber when connecting. Subscriber must subscribe to the welcome message before connecting. For welcome messages to work well, poll on incoming subscription messages on the XPublisher socket and handle them.
OptionalzapDomain ?: null | stringZMQ_ZAP_DOMAIN
Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the default on all
tcp://connections), ZAP authentication only happens if you set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 for more details.OptionalzapEnforce ?: booleanDomain ZMQ_ZAP_ENFORCE_DOMAIN
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.
Returns XPublisher
Properties
affinity
ZMQ_AFFINITY
I/O thread affinity, which determines which threads from the ØMQ I/O thread pool associated with the socket's context shall handle newly created connections.
Note: This value is a bit mask, but values higher than Number.MAX_SAFE_INTEGER may not be represented accurately! This currently means that configurations beyond 52 threads are unreliable.
backlog
ZMQ_BACKLOG
Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.
Readonlyclosed
Whether this socket was previously closed with close().
connectTimeout
ZMQ_CONNECT_TIMEOUT
Sets how long to wait before timing-out a connect() system call. The connect() system call normally takes a long time before it returns a time out error. Setting this option allows the library to time out the call at an earlier interval.
Readonlycontext
Context that this socket belongs to.
curvePublicKey
ZMQ_CURVE_PUBLICKEY
Sets the socket's long term public key. You must set this on CURVE client sockets. A server socket does not need to know its own public key. You can create a new keypair with curveKeyPair().
curveSecretKey
ZMQ_CURVE_SECRETKEY
Sets the socket's long term secret key. You must set this on both CURVE client and server sockets. You can create a new keypair with curveKeyPair().
curveServer
ZMQ_CURVE_SERVER
Defines whether the socket will act as server for CURVE security. A value of true means the socket will act as CURVE server. A value of false means the socket will not act as CURVE server, and its security role then depends on other option settings.
curveServerKey
ZMQ_CURVE_SERVERKEY
Sets the socket's long term server key. This is the public key of the CURVE server socket. You must set this on CURVE client sockets. This key must have been generated together with the server's secret key. You can create a new keypair with curveKeyPair().
Readonlyevents
Event Observer for this socket. This starts up a ØMQ monitoring socket internally that receives all socket events.
gssapiPlainText
gssapiPrincipal
gssapiPrincipalNameType
gssapiServer
gssapiServicePrincipal
gssapiServicePrincipalNameType
handshakeInterval
ZMQ_HANDSHAKE_IVL
Handshaking is the exchange of socket configuration information (socket type, identity, security) that occurs when a connection is first opened (only for connection-oriented transports). If handshaking does not complete within the configured time, the connection shall be closed. The value 0 means no handshake time limit.
heartbeatInterval
ZMQ_HEARTBEAT_IVL
Interval in milliseconds between sending ZMTP heartbeats for the specified socket. If this option is greater than 0, then a PING ZMTP command will be sent after every interval.
heartbeatTimeout
ZMQ_HEARTBEAT_TIMEOUT
How long (in milliseconds) to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic. This option is only valid if heartbeatInterval is greater than 0. The connection will time out if there is no traffic received after sending the PING command. The received traffic does not have to be a PONG command - any received traffic will cancel the timeout.
heartbeatTimeToLive
ZMQ_HEARTBEAT_TTL
The timeout in milliseconds on the remote peer for ZMTP heartbeats. If this option is greater than 0, the remote side shall time out the connection if it does not receive any more traffic within the TTL period. This option does not have any effect if heartbeatInterval is 0. Internally, this value is rounded down to the nearest decisecond, any value less than 100 will have no effect.
immediate
ZMQ_IMMEDIATE
By default queues will fill on outgoing connections even if the connection has not completed. This can lead to "lost" messages on sockets with round-robin routing (Request, Push, Dealer). If this option is set to true, messages shall be queued only to completed connections. This will cause the socket to block if there are no other connections, but will prevent queues from filling on pipes awaiting connection.
interface
ZMQ_BINDTODEVICE
Binds the socket to the given network interface (Linux only). Allows to use Linux VRF, see: https://www.kernel.org/doc/Documentation/networking/vrf.txt. Requires the program to be ran as root or with CAP_NET_RAW.
invertMatching
ZMQ_INVERT_MATCHING
Causes messages to be sent to all connected sockets except those subscribed to a prefix that matches the message.
ipv6
ZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
ReadonlylastEndpoint
ZMQ_LAST_ENDPOINT
The last endpoint bound for TCP and IPC transports.
linger
ZMQ_LINGER
Determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with close().
loopbackFastPath
ZMQ_LOOPBACK_FASTPATH
Enable faster TCP connections on loopback devices. An application can enable this option to reduce the latency and improve the performance of loopback operations on a TCP socket on Windows.
manual
ZMQ_XPUB_MANUAL
Sets the XPublisher socket subscription handling mode to manual/automatic. A value of true will change the subscription requests handling to manual.
maxMessageSize
ZMQ_MAXMSGSIZE
Limits the size of the inbound message. If a peer sends a message larger than the limit it is disconnected. Value of -1 means no limit.
multicastHops
ZMQ_MULTICAST_HOPS
Sets the time-to-live field in every multicast packet sent from this socket. The default is 1 which means that the multicast packets don't leave the local network.
multicastMaxTransportDataUnit
ZMQ_MULTICAST_MAXTPDU
Sets the maximum transport data unit size used for outbound multicast packets. This must be set at or below the minimum Maximum Transmission Unit (MTU) for all network paths over which multicast reception is required.
noDrop
ZMQ_XPUB_NODROP
Sets the socket behaviour to return an error if the high water mark is reached and the message could not be send. The default is to drop the message silently when the peer high water mark is reached.
plainPassword
ZMQ_PLAIN_PASSWORD
Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
plainServer
ZMQ_PLAIN_SERVER
Defines whether the socket will act as server for PLAIN security. A value of true means the socket will act as PLAIN server. A value of false means the socket will not act as PLAIN server, and its security role then depends on other option settings.
plainUsername
ZMQ_PLAIN_USERNAME
Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
rate
ZMQ_RATE
Maximum send or receive data rate for multicast transports such as pgm.
Readonlyreadable
Whether any messages are currently available. If true, the next call to Readable.receive() will immediately read a message from the socket. For sockets that cannot receive messsages this is always false.
receiveBufferSize
ZMQ_RCVBUF
Underlying kernel receive buffer size in bytes. A value of -1 means leave the OS default unchanged.
receiveHighWaterMark
ZMQ_RCVHWM
The high water mark is a hard limit on the maximum number of incoming messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
receiveTimeout
ZMQ_RCVTIMEO
Sets the timeout receiving messages on the socket. If the value is 0, receive() will return a rejected promise immediately if there is no message to receive. If the value is -1, it will wait asynchronously until a message is available. For all other values, it will wait for a message for that amount of time before rejecting.
reconnectInterval
ZMQ_RECONNECT_IVL
Period ØMQ shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. The value -1 means no reconnection.
reconnectMaxInterval
ZMQ_RECONNECT_IVL_MAX
Maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled until reconnectMaxInterval is reached. This allows for exponential backoff strategy. Zero (the default) means no exponential backoff is performed and reconnect interval calculations are only based on reconnectInterval.
recoveryInterval
ZMQ_RECOVERY_IVL
Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
ReadonlysecurityMechanism
| null
| "plain"
| "curve"
| "gssapi"
ZMQ_MECHANISM
Returns the current security mechanism for the socket, if any. The security mechanism is set implictly by using any of the relevant security options. The returned value is one of:
null- No security mechanism is used."plain"- The PLAIN mechanism defines a simple username/password mechanism that lets a server authenticate a client. PLAIN makes no attempt at security or confidentiality."curve"- The CURVE mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server. CURVE is intended for use on public networks."gssapi"- The GSSAPI mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server using the Generic Security Service Application Program Interface (GSSAPI). The GSSAPI mechanism can be used on both public and private networks.
sendBufferSize
ZMQ_SNDBUF
Underlying kernel transmit buffer size in bytes. A value of -1 means leave the OS default unchanged.
sendHighWaterMark
ZMQ_SNDHWM
The high water mark is a hard limit on the maximum number of outgoing messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
sendTimeout
ZMQ_SNDTIMEO
Sets the timeout for sending messages on the socket. If the value is 0, send() will return a rejected promise immediately if the message cannot be sent. If the value is -1, it will wait asynchronously until the message is sent. For all other values, it will try to send the message for that amount of time before rejecting.
socksProxy
ZMQ_SOCKS_PROXY
The SOCKS5 proxy address that shall be used by the socket for the TCP connection(s). Does not support SOCKS5 authentication. If the endpoints are domain names instead of addresses they shall not be resolved and they shall be forwarded unchanged to the SOCKS proxy service in the client connection request message (address type 0x03 domain name).
tcpAcceptFilter
ZMQ_TCP_ACCEPT_FILTER
Assign a filter that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one filter is applied then new connection source IP should be matched. To clear all filters set to null. Filter is a string with IPv6 or IPv4 CIDR.
tcpKeepalive
ZMQ_TCP_KEEPALIVE
Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveCount
ZMQ_TCP_KEEPALIVE_CNT
Overrides TCP_KEEPCNT socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveIdle
ZMQ_TCP_KEEPALIVE_IDLE
Overrides TCP_KEEPIDLE / TCP_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveInterval
ZMQ_TCP_KEEPALIVE_INTVL
Overrides TCP_KEEPINTVL socket option (if supported by the OS). The default value of -1 leaves it to the OS default.
tcpMaxRetransmitTimeout
ZMQ_TCP_MAXRT
Sets how long before an unacknowledged TCP retransmit times out (if supported by the OS). The system normally attempts many TCP retransmits following an exponential backoff strategy. This means that after a network outage, it may take a long time before the session can be re-established. Setting this option allows the timeout to happen at a shorter interval.
ReadonlythreadSafe
ZMQ_THREAD_SAFE
Whether or not the socket is threadsafe. Currently only DRAFT sockets is thread-safe.
Readonlytype
ZMQ_TYPE
Retrieve the socket type. This is fairly useless because you can test the socket class with e.g. socket instanceof Dealer.
typeOfService
ZMQ_TOS
Sets the ToS fields (the Differentiated Services (DS) and Explicit Congestion Notification (ECN) field) of the IP header. The ToS field is typically used to specify a packet's priority. The availability of this option is dependent on intermediate network equipment that inspect the ToS field and provide a path for low-delay, high-throughput, highly-reliable service, etc.
vmciBufferMaxSize
ZMQ_VMCI_BUFFER_MAX_SIZE
Maximum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferMinSize
ZMQ_VMCI_BUFFER_MIN_SIZE
Minimum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferSize
ZMQ_VMCI_BUFFER_SIZE
The size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciConnectTimeout
ZMQ_VMCI_CONNECT_TIMEOUT
Connection timeout for the socket. For vmci:// transports only.
welcomeMessage
ZMQ_XPUB_WELCOME_MSG
Sets a welcome message that will be recieved by subscriber when connecting. Subscriber must subscribe to the welcome message before connecting. For welcome messages to work well, poll on incoming subscription messages on the XPublisher socket and handle them.
Readonlywritable
Whether any messages can be queued for sending. If true, the next call to Writable.send() will immediately queue a message on the socket. For sockets that cannot send messsages this is always false.
zapDomain
ZMQ_ZAP_DOMAIN
Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the default on all tcp:// connections), ZAP authentication only happens if you set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 for more details.
zapEnforceDomain
ZMQ_ZAP_ENFORCE_DOMAIN
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.
Accessors
verbosity
- set verbosity(value): void
ZMQ_XPUB_VERBOSE / ZMQ_XPUB_VERBOSER
Whether to pass any duplicate subscription/unsuscription messages.
null(default) - Only unique subscribe and unsubscribe messages are visible to the caller."allSubs"- All subscribe messages (including duplicates) are visible to the caller, but only unique unsubscribe messages are visible."allSubsUnsubs"- All subscribe and unsubscribe messages (including duplicates) are visible to the caller.
Parameters
- value: null | "allSubs" | "allSubsUnsubs"
Returns void
Methods
[asyncIterator]
- [async
Iterator] (): AsyncIterator<Buffer[], undefined, undefined> Asynchronously iterate over messages becoming available on the socket. When the socket is closed with Socket.close(), the iterator will return. Returning early from the iterator will not close the socket unless it also goes out of scope.
for await (const [msg] of socket) {
// handle messages
} -Returns AsyncIterator<Buffer[], undefined, undefined>
bind
- bind(address): Promise<void>
Binds the socket to the given address. During bind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.You can use
*in place of a hostname to bind on all interfaces/addresses, and you can use*in place of a port to bind to a random port (which can be retrieved with lastEndpoint later).await socket.bind("tcp://127.0.0.1:3456")
await socket.bind("tcp://*:3456") // binds on all interfaces
await socket.bind("tcp://127.0.0.1:*") // binds on random port -Parameters
- address: string
Address to bind this socket to.
Returns Promise<void>
Resolved when the socket was successfully bound.
- address: string
close
- close(): void
Closes the socket and disposes of all resources. Any messages that are queued may be discarded or sent in the background depending on the linger setting.
After this method is called, it is no longer possible to call any other methods on this socket.
Sockets that go out of scope and have no Readable.receive() or Writable.send() operations in progress will automatically be closed. Therefore it is not necessary in most applications to call close() manually.
Calling this method on a socket that is already closed is a no-op.
Returns void
connect
disconnect
- disconnect(address): void
Disconnects a previously connected socket from the given address and returns immediately. Disonnection will happen asynchronously in the background.
socket.disconnect("tcp://127.0.0.1:3456") -Parameters
- address: string
The previously connected address to disconnect from.
Returns void
- address: string
ProtectedgetBoolOption
ProtectedgetInt32Option
ProtectedgetInt64Option
ProtectedgetStringOption
ProtectedgetUint32Option
ProtectedgetUint64Option
receive
- receive(): Promise<Buffer[]>
Waits for the next single or multipart message to become availeble on the socket. Reads a message immediately if possible. If no messages can be read, it will wait asynchonously. The promise will be resolved with an array containing the parts of the next message when available.
const [msg] = await socket.receive()
const [part1, part2] = await socket.receive() -Reading may fail (eventually) if the socket has been configured with a receiveTimeout.
A call to receive() is guaranteed to return with a resolved promise immediately if a message could be read from the socket directly.
Only one asynchronously blocking call to receive() can be in progress simultaneously. If you call receive() again on the same socket it will return a rejected promise with an
EBUSYerror. For example, if no messages can be read and noawaitis used:socket.receive() // -> pending promise until read is possible
socket.receive() // -> promise rejection with `EBUSY` error -Note: Due to the nature of Node.js and to avoid blocking the main thread, this method always attempts to read messages with the
ZMQ_DONTWAITflag. It polls asynchronously if reading is not currently possible. This means that all functionality related to timeouts and blocking behaviour is reimplemented in the Node.js bindings. Any differences in behaviour with the native ZMQ library is considered a bug.Returns Promise<Buffer[]>
Resolved with message parts that were successfully read.
send
- send(message, ...options): Promise<void>
Sends a single message or a multipart message on the socket. Queues the message immediately if possible, and returns a resolved promise. If the message cannot be queued because the high water mark has been reached, it will wait asynchronously. The promise will be resolved when the message was queued successfully.
await socket.send("hello world")
await socket.send(["hello", "world"]) -Queueing may fail eventually if the socket has been configured with a sendTimeout.
A call to send() is guaranteed to return with a resolved promise immediately if the message could be queued directly.
Only one asynchronously blocking call to send() may be executed simultaneously. If you call send() again on a socket that is in the mute state it will return a rejected promise with an
EBUSYerror.The reason for disallowing multiple send() calls simultaneously is that it could create an implicit queue of unsendable outgoing messages. This would circumvent the socket's sendHighWaterMark. Such an implementation could even exhaust all system memory and cause the Node.js process to abort.
For most application you should not notice this implementation detail. Only in rare occasions will a call to send() that does not resolve immediately be undesired. Here are some common scenarios:
If you wish to send a message, use
await send(...). ZeroMQ socket types have been carefully designed to give you the correct blocking behaviour on the chosen socket type in almost all cases:If sending is not possible, it is often better to wait than to continue as if nothing happened. For example, on a Request socket, you can only receive a reply once a message has been sent; so waiting until a message could be queued before continuing with the rest of the program (likely to read from the socket) is required.
Certain socket types (such as Router) will always allow queueing messages and
await send(...)won't delay any code that comes after. This makes sense for routers, since typically you don't want a single send operation to stop the handling of other incoming or outgoing messages.
If you wish to send on an occasionally blocking socket (for example on a Router with the Router.mandatory option set, or on a Dealer) and you're 100% certain that dropping a message is better than blocking, then you can set the sendTimeout option to
0to effectively force send() to always resolve immediately. Be prepared to catch exceptions if sending a message is not immediately possible.If you wish to send on a socket and messages should be queued before they are dropped, you should implement a simple queue in JavaScript. Such a queue is not provided by this library because most real world applications need to deal with undeliverable messages in more complex ways - for example, they might need to reply with a status message; or first retry delivery a certain number of times before giving up.
Parameters
- message: MessageLike | MessageLike[]
Single message or multipart message to queue for sending.
Rest...options: []Any options, if applicable to the socket type (DRAFT only).
Returns Promise<void>
Resolved when the message was successfully queued.
ProtectedsetBoolOption
ProtectedsetInt32Option
ProtectedsetInt64Option
ProtectedsetStringOption
ProtectedsetUint32Option
ProtectedsetUint64Option
unbind
- unbind(address): Promise<void>
Unbinds the socket to the given address. During unbind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.Parameters
- address: string
Address to unbind this socket from.
Returns Promise<void>
Resolved when the socket was successfully unbound.
- address: string
Class XPublisher
Same as Publisher, except that you can receive subscriptions from the peers in form of incoming messages. Subscription message is a byte 1 (for subscriptions) or byte 0 (for unsubscriptions) followed by the subscription body. Messages without a sub/unsub prefix are also received, but have no effect on subscription status.
Hierarchy (View Summary)
Index
Constructors
Properties
Accessors
Methods
Constructors
constructor
- new XPublisher(
options?: {
affinity?: number;
backlog?: number;
connectTimeout?: number;
context?: Context;
curvePublicKey?: null | string;
curveSecretKey?: null | string;
curveServer?: boolean;
curveServerKey?: null | string;
gssapiPlainText?: boolean;
gssapiPrincipal?: null | string;
gssapiPrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
gssapiServer?: boolean;
gssapiServicePrincipal?: null | string;
gssapiServicePrincipalNameType?:
| "hostBased"
| "userName"
| "krb5Principal";
handshakeInterval?: number;
heartbeatInterval?: number;
heartbeatTimeout?: number;
heartbeatTimeToLive?: number;
immediate?: boolean;
interface?: null
| string;
invertMatching?: boolean;
ipv6?: boolean;
linger?: number;
loopbackFastPath?: boolean;
manual?: boolean;
maxMessageSize?: number;
multicastHops?: number;
multicastMaxTransportDataUnit?: number;
noDrop?: boolean;
plainPassword?: null | string;
plainServer?: boolean;
plainUsername?: null | string;
rate?: number;
receiveBufferSize?: number;
receiveHighWaterMark?: number;
receiveTimeout?: number;
reconnectInterval?: number;
reconnectMaxInterval?: number;
recoveryInterval?: number;
sendBufferSize?: number;
sendHighWaterMark?: number;
sendTimeout?: number;
socksProxy?: null | string;
tcpAcceptFilter?: null | string;
tcpKeepalive?: number;
tcpKeepaliveCount?: number;
tcpKeepaliveIdle?: number;
tcpKeepaliveInterval?: number;
tcpMaxRetransmitTimeout?: number;
typeOfService?: number;
verbosity?: null | "allSubs" | "allSubsUnsubs";
vmciBufferMaxSize?: number;
vmciBufferMinSize?: number;
vmciBufferSize?: number;
vmciConnectTimeout?: number;
welcomeMessage?: null | string;
zapDomain?: null | string;
zapEnforceDomain?: boolean;
},
): XPublisher Parameters
Optionaloptions: {
affinity?: number;
backlog?: number;
connectTimeout?: number;
context?: Context;
curvePublicKey?: null | string;
curveSecretKey?: null | string;
curveServer?: boolean;
curveServerKey?: null | string;
gssapiPlainText?: boolean;
gssapiPrincipal?: null | string;
gssapiPrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
gssapiServer?: boolean;
gssapiServicePrincipal?: null | string;
gssapiServicePrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
handshakeInterval?: number;
heartbeatInterval?: number;
heartbeatTimeout?: number;
heartbeatTimeToLive?: number;
immediate?: boolean;
interface?: null | string;
invertMatching?: boolean;
ipv6?: boolean;
linger?: number;
loopbackFastPath?: boolean;
manual?: boolean;
maxMessageSize?: number;
multicastHops?: number;
multicastMaxTransportDataUnit?: number;
noDrop?: boolean;
plainPassword?: null | string;
plainServer?: boolean;
plainUsername?: null | string;
rate?: number;
receiveBufferSize?: number;
receiveHighWaterMark?: number;
receiveTimeout?: number;
reconnectInterval?: number;
reconnectMaxInterval?: number;
recoveryInterval?: number;
sendBufferSize?: number;
sendHighWaterMark?: number;
sendTimeout?: number;
socksProxy?: null | string;
tcpAcceptFilter?: null | string;
tcpKeepalive?: number;
tcpKeepaliveCount?: number;
tcpKeepaliveIdle?: number;
tcpKeepaliveInterval?: number;
tcpMaxRetransmitTimeout?: number;
typeOfService?: number;
verbosity?: null | "allSubs" | "allSubsUnsubs";
vmciBufferMaxSize?: number;
vmciBufferMinSize?: number;
vmciBufferSize?: number;
vmciConnectTimeout?: number;
welcomeMessage?: null | string;
zapDomain?: null | string;
zapEnforceDomain?: boolean;
}Optionalaffinity?: numberZMQ_AFFINITY
I/O thread affinity, which determines which threads from the ØMQ I/O thread pool associated with the socket's context shall handle newly created connections.
Note: This value is a bit mask, but values higher than
Number.MAX_SAFE_INTEGERmay not be represented accurately! This currently means that configurations beyond 52 threads are unreliable.Optionalbacklog?: numberZMQ_BACKLOG
Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.
OptionalconnectTimeout?: numberZMQ_CONNECT_TIMEOUT
Sets how long to wait before timing-out a connect() system call. The connect() system call normally takes a long time before it returns a time out error. Setting this option allows the library to time out the call at an earlier interval.
Optionalcontext?: ContextOptionalcurvePublicKey?: null | stringZMQ_CURVE_PUBLICKEY
Sets the socket's long term public key. You must set this on CURVE client sockets. A server socket does not need to know its own public key. You can create a new keypair with curveKeyPair().
OptionalcurveSecretKey?: null | stringZMQ_CURVE_SECRETKEY
Sets the socket's long term secret key. You must set this on both CURVE client and server sockets. You can create a new keypair with curveKeyPair().
OptionalcurveServer?: booleanZMQ_CURVE_SERVER
Defines whether the socket will act as server for CURVE security. A value of
truemeans the socket will act as CURVE server. A value offalsemeans the socket will not act as CURVE server, and its security role then depends on other option settings.OptionalcurveServerKey?: null | stringZMQ_CURVE_SERVERKEY
Sets the socket's long term server key. This is the public key of the CURVE server socket. You must set this on CURVE client sockets. This key must have been generated together with the server's secret key. You can create a new keypair with curveKeyPair().
OptionalgssapiPlainText?: booleanOptionalgssapiPrincipal?: null | stringOptionalgssapiPrincipalNameType?: "hostBased" | "userName" | "krb5Principal"OptionalgssapiServer?: booleanOptionalgssapiServicePrincipal?: null | stringOptionalgssapiServicePrincipalNameType?: "hostBased" | "userName" | "krb5Principal"OptionalhandshakeInterval?: numberZMQ_HANDSHAKE_IVL
Handshaking is the exchange of socket configuration information (socket type, identity, security) that occurs when a connection is first opened (only for connection-oriented transports). If handshaking does not complete within the configured time, the connection shall be closed. The value 0 means no handshake time limit.
OptionalheartbeatInterval?: numberZMQ_HEARTBEAT_IVL
Interval in milliseconds between sending ZMTP heartbeats for the specified socket. If this option is greater than 0, then a PING ZMTP command will be sent after every interval.
OptionalheartbeatTimeout?: numberZMQ_HEARTBEAT_TIMEOUT
How long (in milliseconds) to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic. This option is only valid if heartbeatInterval is greater than 0. The connection will time out if there is no traffic received after sending the PING command. The received traffic does not have to be a PONG command - any received traffic will cancel the timeout.
OptionalheartbeatTimeToLive?: numberZMQ_HEARTBEAT_TTL
The timeout in milliseconds on the remote peer for ZMTP heartbeats. If this option is greater than 0, the remote side shall time out the connection if it does not receive any more traffic within the TTL period. This option does not have any effect if heartbeatInterval is 0. Internally, this value is rounded down to the nearest decisecond, any value less than 100 will have no effect.
Optionalimmediate?: booleanZMQ_IMMEDIATE
By default queues will fill on outgoing connections even if the connection has not completed. This can lead to "lost" messages on sockets with round-robin routing (Request, Push, Dealer). If this option is set to
true, messages shall be queued only to completed connections. This will cause the socket to block if there are no other connections, but will prevent queues from filling on pipes awaiting connection.Optionalinterface?: null | stringZMQ_BINDTODEVICE
Binds the socket to the given network interface (Linux only). Allows to use Linux VRF, see: https://www.kernel.org/doc/Documentation/networking/vrf.txt. Requires the program to be ran as root or with
CAP_NET_RAW.OptionalinvertMatching?: booleanZMQ_INVERT_MATCHING
Causes messages to be sent to all connected sockets except those subscribed to a prefix that matches the message.
Optionalipv6?: booleanZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
Optionallinger?: numberZMQ_LINGER
Determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with close().
OptionalloopbackFastPath?: booleanZMQ_LOOPBACK_FASTPATH
Enable faster TCP connections on loopback devices. An application can enable this option to reduce the latency and improve the performance of loopback operations on a TCP socket on Windows.
Optionalmanual?: booleanZMQ_XPUB_MANUAL
Sets the XPublisher socket subscription handling mode to manual/automatic. A value of
truewill change the subscription requests handling to manual.OptionalmaxMessageSize?: numberZMQ_MAXMSGSIZE
Limits the size of the inbound message. If a peer sends a message larger than the limit it is disconnected. Value of -1 means no limit.
OptionalmulticastHops?: numberZMQ_MULTICAST_HOPS
Sets the time-to-live field in every multicast packet sent from this socket. The default is 1 which means that the multicast packets don't leave the local network.
OptionalmulticastMaxTransportDataUnit?: numberZMQ_MULTICAST_MAXTPDU
Sets the maximum transport data unit size used for outbound multicast packets. This must be set at or below the minimum Maximum Transmission Unit (MTU) for all network paths over which multicast reception is required.
OptionalnoDrop?: booleanZMQ_XPUB_NODROP
Sets the socket behaviour to return an error if the high water mark is reached and the message could not be send. The default is to drop the message silently when the peer high water mark is reached.
OptionalplainPassword?: null | stringZMQ_PLAIN_PASSWORD
Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
OptionalplainServer?: booleanZMQ_PLAIN_SERVER
Defines whether the socket will act as server for PLAIN security. A value of
truemeans the socket will act as PLAIN server. A value offalsemeans the socket will not act as PLAIN server, and its security role then depends on other option settings.OptionalplainUsername?: null | stringZMQ_PLAIN_USERNAME
Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
Optionalrate?: numberZMQ_RATE
Maximum send or receive data rate for multicast transports such as
pgm.OptionalreceiveBufferSize?: numberZMQ_RCVBUF
Underlying kernel receive buffer size in bytes. A value of -1 means leave the OS default unchanged.
OptionalreceiveHighWaterMark?: numberZMQ_RCVHWM
The high water mark is a hard limit on the maximum number of incoming messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
OptionalreceiveTimeout?: numberZMQ_RCVTIMEO
Sets the timeout receiving messages on the socket. If the value is 0, receive() will return a rejected promise immediately if there is no message to receive. If the value is -1, it will wait asynchronously until a message is available. For all other values, it will wait for a message for that amount of time before rejecting.
OptionalreconnectInterval?: numberZMQ_RECONNECT_IVL
Period ØMQ shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. The value -1 means no reconnection.
OptionalreconnectMaxInterval?: numberZMQ_RECONNECT_IVL_MAX
Maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled until reconnectMaxInterval is reached. This allows for exponential backoff strategy. Zero (the default) means no exponential backoff is performed and reconnect interval calculations are only based on reconnectInterval.
OptionalrecoveryInterval?: numberZMQ_RECOVERY_IVL
Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
OptionalsendBufferSize?: numberZMQ_SNDBUF
Underlying kernel transmit buffer size in bytes. A value of -1 means leave the OS default unchanged.
OptionalsendHighWaterMark?: numberZMQ_SNDHWM
The high water mark is a hard limit on the maximum number of outgoing messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
OptionalsendTimeout?: numberZMQ_SNDTIMEO
Sets the timeout for sending messages on the socket. If the value is 0, send() will return a rejected promise immediately if the message cannot be sent. If the value is -1, it will wait asynchronously until the message is sent. For all other values, it will try to send the message for that amount of time before rejecting.
OptionalsocksProxy?: null | stringZMQ_SOCKS_PROXY
The SOCKS5 proxy address that shall be used by the socket for the TCP connection(s). Does not support SOCKS5 authentication. If the endpoints are domain names instead of addresses they shall not be resolved and they shall be forwarded unchanged to the SOCKS proxy service in the client connection request message (address type 0x03 domain name).
OptionaltcpAcceptFilter?: null | stringZMQ_TCP_ACCEPT_FILTER
Assign a filter that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one filter is applied then new connection source IP should be matched. To clear all filters set to
null. Filter is a string with IPv6 or IPv4 CIDR.OptionaltcpKeepalive?: numberZMQ_TCP_KEEPALIVE
Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepaliveCount?: numberZMQ_TCP_KEEPALIVE_CNT
Overrides TCP_KEEPCNT socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepaliveIdle?: numberZMQ_TCP_KEEPALIVE_IDLE
Overrides TCP_KEEPIDLE / TCP_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepaliveInterval?: numberZMQ_TCP_KEEPALIVE_INTVL
Overrides TCP_KEEPINTVL socket option (if supported by the OS). The default value of -1 leaves it to the OS default.
OptionaltcpMaxRetransmitTimeout?: numberZMQ_TCP_MAXRT
Sets how long before an unacknowledged TCP retransmit times out (if supported by the OS). The system normally attempts many TCP retransmits following an exponential backoff strategy. This means that after a network outage, it may take a long time before the session can be re-established. Setting this option allows the timeout to happen at a shorter interval.
OptionaltypeOfService?: numberZMQ_TOS
Sets the ToS fields (the Differentiated Services (DS) and Explicit Congestion Notification (ECN) field) of the IP header. The ToS field is typically used to specify a packet's priority. The availability of this option is dependent on intermediate network equipment that inspect the ToS field and provide a path for low-delay, high-throughput, highly-reliable service, etc.
Optionalverbosity?: null | "allSubs" | "allSubsUnsubs"OptionalvmciBufferMaxSize?: numberZMQ_VMCI_BUFFER_MAX_SIZE
Maximum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciBufferMinSize?: numberZMQ_VMCI_BUFFER_MIN_SIZE
Minimum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciBufferSize?: numberZMQ_VMCI_BUFFER_SIZE
The size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciConnectTimeout?: numberZMQ_VMCI_CONNECT_TIMEOUT
Connection timeout for the socket. For
vmci://transports only.OptionalwelcomeMessage?: null | stringZMQ_XPUB_WELCOME_MSG
Sets a welcome message that will be recieved by subscriber when connecting. Subscriber must subscribe to the welcome message before connecting. For welcome messages to work well, poll on incoming subscription messages on the XPublisher socket and handle them.
OptionalzapDomain?: null | stringZMQ_ZAP_DOMAIN
Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the default on all
tcp://connections), ZAP authentication only happens if you set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 for more details.OptionalzapEnforceDomain?: booleanZMQ_ZAP_ENFORCE_DOMAIN
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.
Returns XPublisher
Properties
affinity
ZMQ_AFFINITY
I/O thread affinity, which determines which threads from the ØMQ I/O thread pool associated with the socket's context shall handle newly created connections.
Note: This value is a bit mask, but values higher than Number.MAX_SAFE_INTEGER may not be represented accurately! This currently means that configurations beyond 52 threads are unreliable.
backlog
ZMQ_BACKLOG
Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.
Readonlyclosed
Whether this socket was previously closed with close().
connectTimeout
ZMQ_CONNECT_TIMEOUT
Sets how long to wait before timing-out a connect() system call. The connect() system call normally takes a long time before it returns a time out error. Setting this option allows the library to time out the call at an earlier interval.
Readonlycontext
Context that this socket belongs to.
curvePublicKey
ZMQ_CURVE_PUBLICKEY
Sets the socket's long term public key. You must set this on CURVE client sockets. A server socket does not need to know its own public key. You can create a new keypair with curveKeyPair().
curveSecretKey
ZMQ_CURVE_SECRETKEY
Sets the socket's long term secret key. You must set this on both CURVE client and server sockets. You can create a new keypair with curveKeyPair().
curveServer
ZMQ_CURVE_SERVER
Defines whether the socket will act as server for CURVE security. A value of true means the socket will act as CURVE server. A value of false means the socket will not act as CURVE server, and its security role then depends on other option settings.
curveServerKey
ZMQ_CURVE_SERVERKEY
Sets the socket's long term server key. This is the public key of the CURVE server socket. You must set this on CURVE client sockets. This key must have been generated together with the server's secret key. You can create a new keypair with curveKeyPair().
Readonlyevents
Event Observer for this socket. This starts up a ØMQ monitoring socket internally that receives all socket events.
gssapiPlainText
gssapiPrincipal
gssapiPrincipalNameType
gssapiServer
gssapiServicePrincipal
gssapiServicePrincipalNameType
handshakeInterval
ZMQ_HANDSHAKE_IVL
Handshaking is the exchange of socket configuration information (socket type, identity, security) that occurs when a connection is first opened (only for connection-oriented transports). If handshaking does not complete within the configured time, the connection shall be closed. The value 0 means no handshake time limit.
heartbeatInterval
ZMQ_HEARTBEAT_IVL
Interval in milliseconds between sending ZMTP heartbeats for the specified socket. If this option is greater than 0, then a PING ZMTP command will be sent after every interval.
heartbeatTimeout
ZMQ_HEARTBEAT_TIMEOUT
How long (in milliseconds) to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic. This option is only valid if heartbeatInterval is greater than 0. The connection will time out if there is no traffic received after sending the PING command. The received traffic does not have to be a PONG command - any received traffic will cancel the timeout.
heartbeatTimeToLive
ZMQ_HEARTBEAT_TTL
The timeout in milliseconds on the remote peer for ZMTP heartbeats. If this option is greater than 0, the remote side shall time out the connection if it does not receive any more traffic within the TTL period. This option does not have any effect if heartbeatInterval is 0. Internally, this value is rounded down to the nearest decisecond, any value less than 100 will have no effect.
immediate
ZMQ_IMMEDIATE
By default queues will fill on outgoing connections even if the connection has not completed. This can lead to "lost" messages on sockets with round-robin routing (Request, Push, Dealer). If this option is set to true, messages shall be queued only to completed connections. This will cause the socket to block if there are no other connections, but will prevent queues from filling on pipes awaiting connection.
interface
ZMQ_BINDTODEVICE
Binds the socket to the given network interface (Linux only). Allows to use Linux VRF, see: https://www.kernel.org/doc/Documentation/networking/vrf.txt. Requires the program to be ran as root or with CAP_NET_RAW.
invertMatching
ZMQ_INVERT_MATCHING
Causes messages to be sent to all connected sockets except those subscribed to a prefix that matches the message.
ipv6
ZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
ReadonlylastEndpoint
ZMQ_LAST_ENDPOINT
The last endpoint bound for TCP and IPC transports.
linger
ZMQ_LINGER
Determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with close().
loopbackFastPath
ZMQ_LOOPBACK_FASTPATH
Enable faster TCP connections on loopback devices. An application can enable this option to reduce the latency and improve the performance of loopback operations on a TCP socket on Windows.
manual
ZMQ_XPUB_MANUAL
Sets the XPublisher socket subscription handling mode to manual/automatic. A value of true will change the subscription requests handling to manual.
maxMessageSize
ZMQ_MAXMSGSIZE
Limits the size of the inbound message. If a peer sends a message larger than the limit it is disconnected. Value of -1 means no limit.
multicastHops
ZMQ_MULTICAST_HOPS
Sets the time-to-live field in every multicast packet sent from this socket. The default is 1 which means that the multicast packets don't leave the local network.
multicastMaxTransportDataUnit
ZMQ_MULTICAST_MAXTPDU
Sets the maximum transport data unit size used for outbound multicast packets. This must be set at or below the minimum Maximum Transmission Unit (MTU) for all network paths over which multicast reception is required.
noDrop
ZMQ_XPUB_NODROP
Sets the socket behaviour to return an error if the high water mark is reached and the message could not be send. The default is to drop the message silently when the peer high water mark is reached.
plainPassword
ZMQ_PLAIN_PASSWORD
Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
plainServer
ZMQ_PLAIN_SERVER
Defines whether the socket will act as server for PLAIN security. A value of true means the socket will act as PLAIN server. A value of false means the socket will not act as PLAIN server, and its security role then depends on other option settings.
plainUsername
ZMQ_PLAIN_USERNAME
Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
rate
ZMQ_RATE
Maximum send or receive data rate for multicast transports such as pgm.
Readonlyreadable
Whether any messages are currently available. If true, the next call to Readable.receive() will immediately read a message from the socket. For sockets that cannot receive messsages this is always false.
receiveBufferSize
ZMQ_RCVBUF
Underlying kernel receive buffer size in bytes. A value of -1 means leave the OS default unchanged.
receiveHighWaterMark
ZMQ_RCVHWM
The high water mark is a hard limit on the maximum number of incoming messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
receiveTimeout
ZMQ_RCVTIMEO
Sets the timeout receiving messages on the socket. If the value is 0, receive() will return a rejected promise immediately if there is no message to receive. If the value is -1, it will wait asynchronously until a message is available. For all other values, it will wait for a message for that amount of time before rejecting.
reconnectInterval
ZMQ_RECONNECT_IVL
Period ØMQ shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. The value -1 means no reconnection.
reconnectMaxInterval
ZMQ_RECONNECT_IVL_MAX
Maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled until reconnectMaxInterval is reached. This allows for exponential backoff strategy. Zero (the default) means no exponential backoff is performed and reconnect interval calculations are only based on reconnectInterval.
recoveryInterval
ZMQ_RECOVERY_IVL
Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
ReadonlysecurityMechanism
ZMQ_MECHANISM
Returns the current security mechanism for the socket, if any. The security mechanism is set implictly by using any of the relevant security options. The returned value is one of:
null- No security mechanism is used."plain"- The PLAIN mechanism defines a simple username/password mechanism that lets a server authenticate a client. PLAIN makes no attempt at security or confidentiality."curve"- The CURVE mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server. CURVE is intended for use on public networks."gssapi"- The GSSAPI mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server using the Generic Security Service Application Program Interface (GSSAPI). The GSSAPI mechanism can be used on both public and private networks.
sendBufferSize
ZMQ_SNDBUF
Underlying kernel transmit buffer size in bytes. A value of -1 means leave the OS default unchanged.
sendHighWaterMark
ZMQ_SNDHWM
The high water mark is a hard limit on the maximum number of outgoing messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
sendTimeout
ZMQ_SNDTIMEO
Sets the timeout for sending messages on the socket. If the value is 0, send() will return a rejected promise immediately if the message cannot be sent. If the value is -1, it will wait asynchronously until the message is sent. For all other values, it will try to send the message for that amount of time before rejecting.
socksProxy
ZMQ_SOCKS_PROXY
The SOCKS5 proxy address that shall be used by the socket for the TCP connection(s). Does not support SOCKS5 authentication. If the endpoints are domain names instead of addresses they shall not be resolved and they shall be forwarded unchanged to the SOCKS proxy service in the client connection request message (address type 0x03 domain name).
tcpAcceptFilter
ZMQ_TCP_ACCEPT_FILTER
Assign a filter that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one filter is applied then new connection source IP should be matched. To clear all filters set to null. Filter is a string with IPv6 or IPv4 CIDR.
tcpKeepalive
ZMQ_TCP_KEEPALIVE
Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveCount
ZMQ_TCP_KEEPALIVE_CNT
Overrides TCP_KEEPCNT socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveIdle
ZMQ_TCP_KEEPALIVE_IDLE
Overrides TCP_KEEPIDLE / TCP_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveInterval
ZMQ_TCP_KEEPALIVE_INTVL
Overrides TCP_KEEPINTVL socket option (if supported by the OS). The default value of -1 leaves it to the OS default.
tcpMaxRetransmitTimeout
ZMQ_TCP_MAXRT
Sets how long before an unacknowledged TCP retransmit times out (if supported by the OS). The system normally attempts many TCP retransmits following an exponential backoff strategy. This means that after a network outage, it may take a long time before the session can be re-established. Setting this option allows the timeout to happen at a shorter interval.
ReadonlythreadSafe
ZMQ_THREAD_SAFE
Whether or not the socket is threadsafe. Currently only DRAFT sockets is thread-safe.
Readonlytype
ZMQ_TYPE
Retrieve the socket type. This is fairly useless because you can test the socket class with e.g. socket instanceof Dealer.
typeOfService
ZMQ_TOS
Sets the ToS fields (the Differentiated Services (DS) and Explicit Congestion Notification (ECN) field) of the IP header. The ToS field is typically used to specify a packet's priority. The availability of this option is dependent on intermediate network equipment that inspect the ToS field and provide a path for low-delay, high-throughput, highly-reliable service, etc.
vmciBufferMaxSize
ZMQ_VMCI_BUFFER_MAX_SIZE
Maximum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferMinSize
ZMQ_VMCI_BUFFER_MIN_SIZE
Minimum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferSize
ZMQ_VMCI_BUFFER_SIZE
The size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciConnectTimeout
ZMQ_VMCI_CONNECT_TIMEOUT
Connection timeout for the socket. For vmci:// transports only.
welcomeMessage
ZMQ_XPUB_WELCOME_MSG
Sets a welcome message that will be recieved by subscriber when connecting. Subscriber must subscribe to the welcome message before connecting. For welcome messages to work well, poll on incoming subscription messages on the XPublisher socket and handle them.
Readonlywritable
Whether any messages can be queued for sending. If true, the next call to Writable.send() will immediately queue a message on the socket. For sockets that cannot send messsages this is always false.
zapDomain
ZMQ_ZAP_DOMAIN
Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the default on all tcp:// connections), ZAP authentication only happens if you set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 for more details.
zapEnforceDomain
ZMQ_ZAP_ENFORCE_DOMAIN
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.
Accessors
verbosity
- set verbosity(value: null | "allSubs" | "allSubsUnsubs"): void
ZMQ_XPUB_VERBOSE / ZMQ_XPUB_VERBOSER
Whether to pass any duplicate subscription/unsuscription messages.
null(default) - Only unique subscribe and unsubscribe messages are visible to the caller."allSubs"- All subscribe messages (including duplicates) are visible to the caller, but only unique unsubscribe messages are visible."allSubsUnsubs"- All subscribe and unsubscribe messages (including duplicates) are visible to the caller.
Parameters
- value: null | "allSubs" | "allSubsUnsubs"
Returns void
Methods
[asyncIterator]
- "[asyncIterator]"(): AsyncIterator<Buffer[]>
Asynchronously iterate over messages becoming available on the socket. When the socket is closed with Socket.close(), the iterator will return. Returning early from the iterator will not close the socket unless it also goes out of scope.
for await (const [msg] of socket) {
// handle messages
} +Returns AsyncIterator<Buffer[]>
bind
- bind(address: string): Promise<void>
Binds the socket to the given address. During bind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.You can use
*in place of a hostname to bind on all interfaces/addresses, and you can use*in place of a port to bind to a random port (which can be retrieved with lastEndpoint later).await socket.bind("tcp://127.0.0.1:3456")
await socket.bind("tcp://*:3456") // binds on all interfaces
await socket.bind("tcp://127.0.0.1:*") // binds on random port +Parameters
- address: string
Address to bind this socket to.
Returns Promise<void>
Resolved when the socket was successfully bound.
- address: string
bindSync
- bindSync(address: string): void
Binds the socket to the given address. During bind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.You can use
*in place of a hostname to bind on all interfaces/addresses, and you can use*in place of a port to bind to a random port (which can be retrieved with lastEndpoint later).socket.bindSync("tcp://127.0.0.1:3456")
socket.bindSync("tcp://*:3456") // binds on all interfaces
socket.bindSync("tcp://127.0.0.1:*") // binds on random port +Parameters
- address: string
Address to bind this socket to.
Returns void
Resolved when the socket was successfully bound.
- address: string
close
- close(): void
Closes the socket and disposes of all resources. Any messages that are queued may be discarded or sent in the background depending on the linger setting.
After this method is called, it is no longer possible to call any other methods on this socket.
Sockets that go out of scope and have no Readable.receive() or Writable.send() operations in progress will automatically be closed. Therefore it is not necessary in most applications to call close() manually.
Calling this method on a socket that is already closed is a no-op.
Returns void
connect
disconnect
- disconnect(address: string): void
Disconnects a previously connected socket from the given address and returns immediately. Disonnection will happen asynchronously in the background.
socket.disconnect("tcp://127.0.0.1:3456") +Parameters
- address: string
The previously connected address to disconnect from.
Returns void
- address: string
ProtectedgetBoolOption
ProtectedgetInt32Option
ProtectedgetInt64Option
ProtectedgetStringOption
ProtectedgetUint32Option
ProtectedgetUint64Option
receive
- receive(): Promise<Buffer[]>
Waits for the next single or multipart message to become availeble on the socket. Reads a message immediately if possible. If no messages can be read, it will wait asynchonously. The promise will be resolved with an array containing the parts of the next message when available.
const [msg] = await socket.receive()
const [part1, part2] = await socket.receive() +Reading may fail (eventually) if the socket has been configured with a receiveTimeout.
A call to receive() is guaranteed to return with a resolved promise immediately if a message could be read from the socket directly.
Only one asynchronously blocking call to receive() can be in progress simultaneously. If you call receive() again on the same socket it will return a rejected promise with an
EBUSYerror. For example, if no messages can be read and noawaitis used:socket.receive() // -> pending promise until read is possible
socket.receive() // -> promise rejection with `EBUSY` error +Note: Due to the nature of Node.js and to avoid blocking the main thread, this method always attempts to read messages with the
ZMQ_DONTWAITflag. It polls asynchronously if reading is not currently possible. This means that all functionality related to timeouts and blocking behaviour is reimplemented in the Node.js bindings. Any differences in behaviour with the native ZMQ library is considered a bug.Returns Promise<Buffer[]>
Resolved with message parts that were successfully read.
send
- send(message: MessageLike | MessageLike[], ...options: []): Promise<void>
Sends a single message or a multipart message on the socket. Queues the message immediately if possible, and returns a resolved promise. If the message cannot be queued because the high water mark has been reached, it will wait asynchronously. The promise will be resolved when the message was queued successfully.
await socket.send("hello world")
await socket.send(["hello", "world"]) +Queueing may fail eventually if the socket has been configured with a sendTimeout.
A call to send() is guaranteed to return with a resolved promise immediately if the message could be queued directly.
Only one asynchronously blocking call to send() may be executed simultaneously. If you call send() again on a socket that is in the mute state it will return a rejected promise with an
EBUSYerror.The reason for disallowing multiple send() calls simultaneously is that it could create an implicit queue of unsendable outgoing messages. This would circumvent the socket's sendHighWaterMark. Such an implementation could even exhaust all system memory and cause the Node.js process to abort.
For most application you should not notice this implementation detail. Only in rare occasions will a call to send() that does not resolve immediately be undesired. Here are some common scenarios:
If you wish to send a message, use
await send(...). ZeroMQ socket types have been carefully designed to give you the correct blocking behaviour on the chosen socket type in almost all cases:If sending is not possible, it is often better to wait than to continue as if nothing happened. For example, on a Request socket, you can only receive a reply once a message has been sent; so waiting until a message could be queued before continuing with the rest of the program (likely to read from the socket) is required.
Certain socket types (such as Router) will always allow queueing messages and
await send(...)won't delay any code that comes after. This makes sense for routers, since typically you don't want a single send operation to stop the handling of other incoming or outgoing messages.
If you wish to send on an occasionally blocking socket (for example on a Router with the Router.mandatory option set, or on a Dealer) and you're 100% certain that dropping a message is better than blocking, then you can set the sendTimeout option to
0to effectively force send() to always resolve immediately. Be prepared to catch exceptions if sending a message is not immediately possible.If you wish to send on a socket and messages should be queued before they are dropped, you should implement a simple queue in JavaScript. Such a queue is not provided by this library because most real world applications need to deal with undeliverable messages in more complex ways - for example, they might need to reply with a status message; or first retry delivery a certain number of times before giving up.
Parameters
- message: MessageLike | MessageLike[]
Single message or multipart message to queue for sending.
- ...options: []
Any options, if applicable to the socket type (DRAFT only).
Returns Promise<void>
Resolved when the message was successfully queued.
ProtectedsetBoolOption
ProtectedsetInt32Option
ProtectedsetInt64Option
ProtectedsetStringOption
ProtectedsetUint32Option
ProtectedsetUint64Option
unbind
- unbind(address: string): Promise<void>
Unbinds the socket to the given address. During unbind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.Parameters
- address: string
Address to unbind this socket from.
Returns Promise<void>
Resolved when the socket was successfully unbound.
- address: string
unbindSync
- unbindSync(address: string): void
Unbinds the socket to the given address. During unbind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.Parameters
- address: string
Address to unbind this socket from.
Returns void
Resolved when the socket was successfully unbound.
- address: string
Class XSubscriber
Same as Subscriber, except that you subscribe by sending subscription messages to the socket. Subscription message is a byte 1 (for subscriptions) or byte 0 (for unsubscriptions) followed by the subscription body. Messages without a sub/unsub prefix may also be sent, but have no effect on subscription status.
Hierarchy (view full)
Index
Constructors
Properties
Methods
Constructors
constructor
- new XSubscriber(options?): XSubscriber
Parameters
Optionaloptions: {
affinity?: number;
backlog?: number;
connectTimeout?: number;
context?: Context;
curvePublicKey?: null | string;
curveSecretKey?: null | string;
curveServer?: boolean;
curveServerKey?: null | string;
gssapiPlainText?: boolean;
gssapiPrincipal?: null | string;
gssapiPrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
gssapiServer?: boolean;
gssapiServicePrincipal?: null | string;
gssapiServicePrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
handshakeInterval?: number;
heartbeatInterval?: number;
heartbeatTimeout?: number;
heartbeatTimeToLive?: number;
immediate?: boolean;
interface?: null | string;
ipv6?: boolean;
linger?: number;
loopbackFastPath?: boolean;
maxMessageSize?: number;
multicastHops?: number;
multicastMaxTransportDataUnit?: number;
plainPassword?: null | string;
plainServer?: boolean;
plainUsername?: null | string;
rate?: number;
receiveBufferSize?: number;
receiveHighWaterMark?: number;
receiveTimeout?: number;
reconnectInterval?: number;
reconnectMaxInterval?: number;
recoveryInterval?: number;
sendBufferSize?: number;
sendHighWaterMark?: number;
sendTimeout?: number;
socksProxy?: null | string;
tcpAcceptFilter?: null | string;
tcpKeepalive?: number;
tcpKeepaliveCount?: number;
tcpKeepaliveIdle?: number;
tcpKeepaliveInterval?: number;
tcpMaxRetransmitTimeout?: number;
typeOfService?: number;
vmciBufferMaxSize?: number;
vmciBufferMinSize?: number;
vmciBufferSize?: number;
vmciConnectTimeout?: number;
zapDomain?: null | string;
zapEnforceDomain?: boolean;
}Optionalaffinity?: numberZMQ_AFFINITY
I/O thread affinity, which determines which threads from the ØMQ I/O thread pool associated with the socket's context shall handle newly created connections.
Note: This value is a bit mask, but values higher than
Number.MAX_SAFE_INTEGERmay not be represented accurately! This currently means that configurations beyond 52 threads are unreliable.Optionalbacklog?: numberZMQ_BACKLOG
Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.
OptionalconnectTimeout ?: numberZMQ_CONNECT_TIMEOUT
Sets how long to wait before timing-out a connect() system call. The connect() system call normally takes a long time before it returns a time out error. Setting this option allows the library to time out the call at an earlier interval.
Optionalcontext?: ContextOptionalcurvePublic ?: null | stringKey ZMQ_CURVE_PUBLICKEY
Sets the socket's long term public key. You must set this on CURVE client sockets. A server socket does not need to know its own public key. You can create a new keypair with curveKeyPair().
OptionalcurveSecret ?: null | stringKey ZMQ_CURVE_SECRETKEY
Sets the socket's long term secret key. You must set this on both CURVE client and server sockets. You can create a new keypair with curveKeyPair().
OptionalcurveServer ?: booleanZMQ_CURVE_SERVER
Defines whether the socket will act as server for CURVE security. A value of
truemeans the socket will act as CURVE server. A value offalsemeans the socket will not act as CURVE server, and its security role then depends on other option settings.OptionalcurveServer ?: null | stringKey ZMQ_CURVE_SERVERKEY
Sets the socket's long term server key. This is the public key of the CURVE server socket. You must set this on CURVE client sockets. This key must have been generated together with the server's secret key. You can create a new keypair with curveKeyPair().
OptionalgssapiPlain ?: booleanText OptionalgssapiPrincipal ?: null | stringOptionalgssapiPrincipal ?: "hostBased" | "userName" | "krb5Principal"Name Type OptionalgssapiServer ?: booleanOptionalgssapiService ?: null | stringPrincipal OptionalgssapiService ?: "hostBased" | "userName" | "krb5Principal"Principal Name Type OptionalhandshakeInterval ?: numberZMQ_HANDSHAKE_IVL
Handshaking is the exchange of socket configuration information (socket type, identity, security) that occurs when a connection is first opened (only for connection-oriented transports). If handshaking does not complete within the configured time, the connection shall be closed. The value 0 means no handshake time limit.
OptionalheartbeatInterval ?: numberZMQ_HEARTBEAT_IVL
Interval in milliseconds between sending ZMTP heartbeats for the specified socket. If this option is greater than 0, then a PING ZMTP command will be sent after every interval.
OptionalheartbeatTimeout ?: numberZMQ_HEARTBEAT_TIMEOUT
How long (in milliseconds) to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic. This option is only valid if heartbeatInterval is greater than 0. The connection will time out if there is no traffic received after sending the PING command. The received traffic does not have to be a PONG command - any received traffic will cancel the timeout.
OptionalheartbeatTime ?: numberTo Live ZMQ_HEARTBEAT_TTL
The timeout in milliseconds on the remote peer for ZMTP heartbeats. If this option is greater than 0, the remote side shall time out the connection if it does not receive any more traffic within the TTL period. This option does not have any effect if heartbeatInterval is 0. Internally, this value is rounded down to the nearest decisecond, any value less than 100 will have no effect.
Optionalimmediate?: booleanZMQ_IMMEDIATE
By default queues will fill on outgoing connections even if the connection has not completed. This can lead to "lost" messages on sockets with round-robin routing (Request, Push, Dealer). If this option is set to
true, messages shall be queued only to completed connections. This will cause the socket to block if there are no other connections, but will prevent queues from filling on pipes awaiting connection.Optionalinterface?: null | stringZMQ_BINDTODEVICE
Binds the socket to the given network interface (Linux only). Allows to use Linux VRF, see: https://www.kernel.org/doc/Documentation/networking/vrf.txt. Requires the program to be ran as root or with
CAP_NET_RAW.Optionalipv6?: booleanZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
Optionallinger?: numberZMQ_LINGER
Determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with close().
OptionalloopbackFast ?: booleanPath ZMQ_LOOPBACK_FASTPATH
Enable faster TCP connections on loopback devices. An application can enable this option to reduce the latency and improve the performance of loopback operations on a TCP socket on Windows.
OptionalmaxMessage ?: numberSize ZMQ_MAXMSGSIZE
Limits the size of the inbound message. If a peer sends a message larger than the limit it is disconnected. Value of -1 means no limit.
OptionalmulticastHops ?: numberZMQ_MULTICAST_HOPS
Sets the time-to-live field in every multicast packet sent from this socket. The default is 1 which means that the multicast packets don't leave the local network.
OptionalmulticastMax ?: numberTransport Data Unit ZMQ_MULTICAST_MAXTPDU
Sets the maximum transport data unit size used for outbound multicast packets. This must be set at or below the minimum Maximum Transmission Unit (MTU) for all network paths over which multicast reception is required.
OptionalplainPassword ?: null | stringZMQ_PLAIN_PASSWORD
Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
OptionalplainServer ?: booleanZMQ_PLAIN_SERVER
Defines whether the socket will act as server for PLAIN security. A value of
truemeans the socket will act as PLAIN server. A value offalsemeans the socket will not act as PLAIN server, and its security role then depends on other option settings.OptionalplainUsername ?: null | stringZMQ_PLAIN_USERNAME
Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
Optionalrate?: numberZMQ_RATE
Maximum send or receive data rate for multicast transports such as
pgm.OptionalreceiveBuffer ?: numberSize ZMQ_RCVBUF
Underlying kernel receive buffer size in bytes. A value of -1 means leave the OS default unchanged.
OptionalreceiveHigh ?: numberWater Mark ZMQ_RCVHWM
The high water mark is a hard limit on the maximum number of incoming messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
OptionalreceiveTimeout ?: numberZMQ_RCVTIMEO
Sets the timeout receiving messages on the socket. If the value is 0, receive() will return a rejected promise immediately if there is no message to receive. If the value is -1, it will wait asynchronously until a message is available. For all other values, it will wait for a message for that amount of time before rejecting.
OptionalreconnectInterval ?: numberZMQ_RECONNECT_IVL
Period ØMQ shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. The value -1 means no reconnection.
OptionalreconnectMax ?: numberInterval ZMQ_RECONNECT_IVL_MAX
Maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled until reconnectMaxInterval is reached. This allows for exponential backoff strategy. Zero (the default) means no exponential backoff is performed and reconnect interval calculations are only based on reconnectInterval.
OptionalrecoveryInterval ?: numberZMQ_RECOVERY_IVL
Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
OptionalsendBuffer ?: numberSize ZMQ_SNDBUF
Underlying kernel transmit buffer size in bytes. A value of -1 means leave the OS default unchanged.
OptionalsendHigh ?: numberWater Mark ZMQ_SNDHWM
The high water mark is a hard limit on the maximum number of outgoing messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
OptionalsendTimeout ?: numberZMQ_SNDTIMEO
Sets the timeout for sending messages on the socket. If the value is 0, send() will return a rejected promise immediately if the message cannot be sent. If the value is -1, it will wait asynchronously until the message is sent. For all other values, it will try to send the message for that amount of time before rejecting.
OptionalsocksProxy ?: null | stringZMQ_SOCKS_PROXY
The SOCKS5 proxy address that shall be used by the socket for the TCP connection(s). Does not support SOCKS5 authentication. If the endpoints are domain names instead of addresses they shall not be resolved and they shall be forwarded unchanged to the SOCKS proxy service in the client connection request message (address type 0x03 domain name).
OptionaltcpAccept ?: null | stringFilter ZMQ_TCP_ACCEPT_FILTER
Assign a filter that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one filter is applied then new connection source IP should be matched. To clear all filters set to
null. Filter is a string with IPv6 or IPv4 CIDR.OptionaltcpKeepalive ?: numberZMQ_TCP_KEEPALIVE
Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepalive ?: numberCount ZMQ_TCP_KEEPALIVE_CNT
Overrides TCP_KEEPCNT socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepalive ?: numberIdle ZMQ_TCP_KEEPALIVE_IDLE
Overrides TCP_KEEPIDLE / TCP_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepalive ?: numberInterval ZMQ_TCP_KEEPALIVE_INTVL
Overrides TCP_KEEPINTVL socket option (if supported by the OS). The default value of -1 leaves it to the OS default.
OptionaltcpMax ?: numberRetransmit Timeout ZMQ_TCP_MAXRT
Sets how long before an unacknowledged TCP retransmit times out (if supported by the OS). The system normally attempts many TCP retransmits following an exponential backoff strategy. This means that after a network outage, it may take a long time before the session can be re-established. Setting this option allows the timeout to happen at a shorter interval.
OptionaltypeOf ?: numberService ZMQ_TOS
Sets the ToS fields (the Differentiated Services (DS) and Explicit Congestion Notification (ECN) field) of the IP header. The ToS field is typically used to specify a packet's priority. The availability of this option is dependent on intermediate network equipment that inspect the ToS field and provide a path for low-delay, high-throughput, highly-reliable service, etc.
OptionalvmciBuffer ?: numberMax Size ZMQ_VMCI_BUFFER_MAX_SIZE
Maximum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciBuffer ?: numberMin Size ZMQ_VMCI_BUFFER_MIN_SIZE
Minimum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciBuffer ?: numberSize ZMQ_VMCI_BUFFER_SIZE
The size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciConnect ?: numberTimeout ZMQ_VMCI_CONNECT_TIMEOUT
Connection timeout for the socket. For
vmci://transports only.OptionalzapDomain ?: null | stringZMQ_ZAP_DOMAIN
Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the default on all
tcp://connections), ZAP authentication only happens if you set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 for more details.OptionalzapEnforce ?: booleanDomain ZMQ_ZAP_ENFORCE_DOMAIN
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.
Returns XSubscriber
Properties
affinity
ZMQ_AFFINITY
I/O thread affinity, which determines which threads from the ØMQ I/O thread pool associated with the socket's context shall handle newly created connections.
Note: This value is a bit mask, but values higher than Number.MAX_SAFE_INTEGER may not be represented accurately! This currently means that configurations beyond 52 threads are unreliable.
backlog
ZMQ_BACKLOG
Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.
Readonlyclosed
Whether this socket was previously closed with close().
connectTimeout
ZMQ_CONNECT_TIMEOUT
Sets how long to wait before timing-out a connect() system call. The connect() system call normally takes a long time before it returns a time out error. Setting this option allows the library to time out the call at an earlier interval.
Readonlycontext
Context that this socket belongs to.
curvePublicKey
ZMQ_CURVE_PUBLICKEY
Sets the socket's long term public key. You must set this on CURVE client sockets. A server socket does not need to know its own public key. You can create a new keypair with curveKeyPair().
curveSecretKey
ZMQ_CURVE_SECRETKEY
Sets the socket's long term secret key. You must set this on both CURVE client and server sockets. You can create a new keypair with curveKeyPair().
curveServer
ZMQ_CURVE_SERVER
Defines whether the socket will act as server for CURVE security. A value of true means the socket will act as CURVE server. A value of false means the socket will not act as CURVE server, and its security role then depends on other option settings.
curveServerKey
ZMQ_CURVE_SERVERKEY
Sets the socket's long term server key. This is the public key of the CURVE server socket. You must set this on CURVE client sockets. This key must have been generated together with the server's secret key. You can create a new keypair with curveKeyPair().
Readonlyevents
Event Observer for this socket. This starts up a ØMQ monitoring socket internally that receives all socket events.
gssapiPlainText
gssapiPrincipal
gssapiPrincipalNameType
gssapiServer
gssapiServicePrincipal
gssapiServicePrincipalNameType
handshakeInterval
ZMQ_HANDSHAKE_IVL
Handshaking is the exchange of socket configuration information (socket type, identity, security) that occurs when a connection is first opened (only for connection-oriented transports). If handshaking does not complete within the configured time, the connection shall be closed. The value 0 means no handshake time limit.
heartbeatInterval
ZMQ_HEARTBEAT_IVL
Interval in milliseconds between sending ZMTP heartbeats for the specified socket. If this option is greater than 0, then a PING ZMTP command will be sent after every interval.
heartbeatTimeout
ZMQ_HEARTBEAT_TIMEOUT
How long (in milliseconds) to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic. This option is only valid if heartbeatInterval is greater than 0. The connection will time out if there is no traffic received after sending the PING command. The received traffic does not have to be a PONG command - any received traffic will cancel the timeout.
heartbeatTimeToLive
ZMQ_HEARTBEAT_TTL
The timeout in milliseconds on the remote peer for ZMTP heartbeats. If this option is greater than 0, the remote side shall time out the connection if it does not receive any more traffic within the TTL period. This option does not have any effect if heartbeatInterval is 0. Internally, this value is rounded down to the nearest decisecond, any value less than 100 will have no effect.
immediate
ZMQ_IMMEDIATE
By default queues will fill on outgoing connections even if the connection has not completed. This can lead to "lost" messages on sockets with round-robin routing (Request, Push, Dealer). If this option is set to true, messages shall be queued only to completed connections. This will cause the socket to block if there are no other connections, but will prevent queues from filling on pipes awaiting connection.
interface
ZMQ_BINDTODEVICE
Binds the socket to the given network interface (Linux only). Allows to use Linux VRF, see: https://www.kernel.org/doc/Documentation/networking/vrf.txt. Requires the program to be ran as root or with CAP_NET_RAW.
ipv6
ZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
ReadonlylastEndpoint
ZMQ_LAST_ENDPOINT
The last endpoint bound for TCP and IPC transports.
linger
ZMQ_LINGER
Determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with close().
loopbackFastPath
ZMQ_LOOPBACK_FASTPATH
Enable faster TCP connections on loopback devices. An application can enable this option to reduce the latency and improve the performance of loopback operations on a TCP socket on Windows.
maxMessageSize
ZMQ_MAXMSGSIZE
Limits the size of the inbound message. If a peer sends a message larger than the limit it is disconnected. Value of -1 means no limit.
multicastHops
ZMQ_MULTICAST_HOPS
Sets the time-to-live field in every multicast packet sent from this socket. The default is 1 which means that the multicast packets don't leave the local network.
multicastMaxTransportDataUnit
ZMQ_MULTICAST_MAXTPDU
Sets the maximum transport data unit size used for outbound multicast packets. This must be set at or below the minimum Maximum Transmission Unit (MTU) for all network paths over which multicast reception is required.
plainPassword
ZMQ_PLAIN_PASSWORD
Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
plainServer
ZMQ_PLAIN_SERVER
Defines whether the socket will act as server for PLAIN security. A value of true means the socket will act as PLAIN server. A value of false means the socket will not act as PLAIN server, and its security role then depends on other option settings.
plainUsername
ZMQ_PLAIN_USERNAME
Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
rate
ZMQ_RATE
Maximum send or receive data rate for multicast transports such as pgm.
Readonlyreadable
Whether any messages are currently available. If true, the next call to Readable.receive() will immediately read a message from the socket. For sockets that cannot receive messsages this is always false.
receiveBufferSize
ZMQ_RCVBUF
Underlying kernel receive buffer size in bytes. A value of -1 means leave the OS default unchanged.
receiveHighWaterMark
ZMQ_RCVHWM
The high water mark is a hard limit on the maximum number of incoming messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
receiveTimeout
ZMQ_RCVTIMEO
Sets the timeout receiving messages on the socket. If the value is 0, receive() will return a rejected promise immediately if there is no message to receive. If the value is -1, it will wait asynchronously until a message is available. For all other values, it will wait for a message for that amount of time before rejecting.
reconnectInterval
ZMQ_RECONNECT_IVL
Period ØMQ shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. The value -1 means no reconnection.
reconnectMaxInterval
ZMQ_RECONNECT_IVL_MAX
Maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled until reconnectMaxInterval is reached. This allows for exponential backoff strategy. Zero (the default) means no exponential backoff is performed and reconnect interval calculations are only based on reconnectInterval.
recoveryInterval
ZMQ_RECOVERY_IVL
Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
ReadonlysecurityMechanism
| null
| "plain"
| "curve"
| "gssapi"
ZMQ_MECHANISM
Returns the current security mechanism for the socket, if any. The security mechanism is set implictly by using any of the relevant security options. The returned value is one of:
null- No security mechanism is used."plain"- The PLAIN mechanism defines a simple username/password mechanism that lets a server authenticate a client. PLAIN makes no attempt at security or confidentiality."curve"- The CURVE mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server. CURVE is intended for use on public networks."gssapi"- The GSSAPI mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server using the Generic Security Service Application Program Interface (GSSAPI). The GSSAPI mechanism can be used on both public and private networks.
sendBufferSize
ZMQ_SNDBUF
Underlying kernel transmit buffer size in bytes. A value of -1 means leave the OS default unchanged.
sendHighWaterMark
ZMQ_SNDHWM
The high water mark is a hard limit on the maximum number of outgoing messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
sendTimeout
ZMQ_SNDTIMEO
Sets the timeout for sending messages on the socket. If the value is 0, send() will return a rejected promise immediately if the message cannot be sent. If the value is -1, it will wait asynchronously until the message is sent. For all other values, it will try to send the message for that amount of time before rejecting.
socksProxy
ZMQ_SOCKS_PROXY
The SOCKS5 proxy address that shall be used by the socket for the TCP connection(s). Does not support SOCKS5 authentication. If the endpoints are domain names instead of addresses they shall not be resolved and they shall be forwarded unchanged to the SOCKS proxy service in the client connection request message (address type 0x03 domain name).
tcpAcceptFilter
ZMQ_TCP_ACCEPT_FILTER
Assign a filter that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one filter is applied then new connection source IP should be matched. To clear all filters set to null. Filter is a string with IPv6 or IPv4 CIDR.
tcpKeepalive
ZMQ_TCP_KEEPALIVE
Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveCount
ZMQ_TCP_KEEPALIVE_CNT
Overrides TCP_KEEPCNT socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveIdle
ZMQ_TCP_KEEPALIVE_IDLE
Overrides TCP_KEEPIDLE / TCP_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveInterval
ZMQ_TCP_KEEPALIVE_INTVL
Overrides TCP_KEEPINTVL socket option (if supported by the OS). The default value of -1 leaves it to the OS default.
tcpMaxRetransmitTimeout
ZMQ_TCP_MAXRT
Sets how long before an unacknowledged TCP retransmit times out (if supported by the OS). The system normally attempts many TCP retransmits following an exponential backoff strategy. This means that after a network outage, it may take a long time before the session can be re-established. Setting this option allows the timeout to happen at a shorter interval.
ReadonlythreadSafe
ZMQ_THREAD_SAFE
Whether or not the socket is threadsafe. Currently only DRAFT sockets is thread-safe.
Readonlytype
ZMQ_TYPE
Retrieve the socket type. This is fairly useless because you can test the socket class with e.g. socket instanceof Dealer.
typeOfService
ZMQ_TOS
Sets the ToS fields (the Differentiated Services (DS) and Explicit Congestion Notification (ECN) field) of the IP header. The ToS field is typically used to specify a packet's priority. The availability of this option is dependent on intermediate network equipment that inspect the ToS field and provide a path for low-delay, high-throughput, highly-reliable service, etc.
vmciBufferMaxSize
ZMQ_VMCI_BUFFER_MAX_SIZE
Maximum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferMinSize
ZMQ_VMCI_BUFFER_MIN_SIZE
Minimum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferSize
ZMQ_VMCI_BUFFER_SIZE
The size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciConnectTimeout
ZMQ_VMCI_CONNECT_TIMEOUT
Connection timeout for the socket. For vmci:// transports only.
Readonlywritable
Whether any messages can be queued for sending. If true, the next call to Writable.send() will immediately queue a message on the socket. For sockets that cannot send messsages this is always false.
zapDomain
ZMQ_ZAP_DOMAIN
Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the default on all tcp:// connections), ZAP authentication only happens if you set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 for more details.
zapEnforceDomain
ZMQ_ZAP_ENFORCE_DOMAIN
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.
Methods
[asyncIterator]
- [async
Iterator] (): AsyncIterator<Buffer[], undefined, undefined> Asynchronously iterate over messages becoming available on the socket. When the socket is closed with Socket.close(), the iterator will return. Returning early from the iterator will not close the socket unless it also goes out of scope.
for await (const [msg] of socket) {
// handle messages
} -Returns AsyncIterator<Buffer[], undefined, undefined>
bind
- bind(address): Promise<void>
Binds the socket to the given address. During bind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.You can use
*in place of a hostname to bind on all interfaces/addresses, and you can use*in place of a port to bind to a random port (which can be retrieved with lastEndpoint later).await socket.bind("tcp://127.0.0.1:3456")
await socket.bind("tcp://*:3456") // binds on all interfaces
await socket.bind("tcp://127.0.0.1:*") // binds on random port -Parameters
- address: string
Address to bind this socket to.
Returns Promise<void>
Resolved when the socket was successfully bound.
- address: string
close
- close(): void
Closes the socket and disposes of all resources. Any messages that are queued may be discarded or sent in the background depending on the linger setting.
After this method is called, it is no longer possible to call any other methods on this socket.
Sockets that go out of scope and have no Readable.receive() or Writable.send() operations in progress will automatically be closed. Therefore it is not necessary in most applications to call close() manually.
Calling this method on a socket that is already closed is a no-op.
Returns void
connect
disconnect
- disconnect(address): void
Disconnects a previously connected socket from the given address and returns immediately. Disonnection will happen asynchronously in the background.
socket.disconnect("tcp://127.0.0.1:3456") -Parameters
- address: string
The previously connected address to disconnect from.
Returns void
- address: string
ProtectedgetBoolOption
ProtectedgetInt32Option
ProtectedgetInt64Option
ProtectedgetStringOption
ProtectedgetUint32Option
ProtectedgetUint64Option
receive
- receive(): Promise<Buffer[]>
Waits for the next single or multipart message to become availeble on the socket. Reads a message immediately if possible. If no messages can be read, it will wait asynchonously. The promise will be resolved with an array containing the parts of the next message when available.
const [msg] = await socket.receive()
const [part1, part2] = await socket.receive() -Reading may fail (eventually) if the socket has been configured with a receiveTimeout.
A call to receive() is guaranteed to return with a resolved promise immediately if a message could be read from the socket directly.
Only one asynchronously blocking call to receive() can be in progress simultaneously. If you call receive() again on the same socket it will return a rejected promise with an
EBUSYerror. For example, if no messages can be read and noawaitis used:socket.receive() // -> pending promise until read is possible
socket.receive() // -> promise rejection with `EBUSY` error -Note: Due to the nature of Node.js and to avoid blocking the main thread, this method always attempts to read messages with the
ZMQ_DONTWAITflag. It polls asynchronously if reading is not currently possible. This means that all functionality related to timeouts and blocking behaviour is reimplemented in the Node.js bindings. Any differences in behaviour with the native ZMQ library is considered a bug.Returns Promise<Buffer[]>
Resolved with message parts that were successfully read.
send
- send(message, ...options): Promise<void>
Sends a single message or a multipart message on the socket. Queues the message immediately if possible, and returns a resolved promise. If the message cannot be queued because the high water mark has been reached, it will wait asynchronously. The promise will be resolved when the message was queued successfully.
await socket.send("hello world")
await socket.send(["hello", "world"]) -Queueing may fail eventually if the socket has been configured with a sendTimeout.
A call to send() is guaranteed to return with a resolved promise immediately if the message could be queued directly.
Only one asynchronously blocking call to send() may be executed simultaneously. If you call send() again on a socket that is in the mute state it will return a rejected promise with an
EBUSYerror.The reason for disallowing multiple send() calls simultaneously is that it could create an implicit queue of unsendable outgoing messages. This would circumvent the socket's sendHighWaterMark. Such an implementation could even exhaust all system memory and cause the Node.js process to abort.
For most application you should not notice this implementation detail. Only in rare occasions will a call to send() that does not resolve immediately be undesired. Here are some common scenarios:
If you wish to send a message, use
await send(...). ZeroMQ socket types have been carefully designed to give you the correct blocking behaviour on the chosen socket type in almost all cases:If sending is not possible, it is often better to wait than to continue as if nothing happened. For example, on a Request socket, you can only receive a reply once a message has been sent; so waiting until a message could be queued before continuing with the rest of the program (likely to read from the socket) is required.
Certain socket types (such as Router) will always allow queueing messages and
await send(...)won't delay any code that comes after. This makes sense for routers, since typically you don't want a single send operation to stop the handling of other incoming or outgoing messages.
If you wish to send on an occasionally blocking socket (for example on a Router with the Router.mandatory option set, or on a Dealer) and you're 100% certain that dropping a message is better than blocking, then you can set the sendTimeout option to
0to effectively force send() to always resolve immediately. Be prepared to catch exceptions if sending a message is not immediately possible.If you wish to send on a socket and messages should be queued before they are dropped, you should implement a simple queue in JavaScript. Such a queue is not provided by this library because most real world applications need to deal with undeliverable messages in more complex ways - for example, they might need to reply with a status message; or first retry delivery a certain number of times before giving up.
Parameters
- message: MessageLike | MessageLike[]
Single message or multipart message to queue for sending.
Rest...options: []Any options, if applicable to the socket type (DRAFT only).
Returns Promise<void>
Resolved when the message was successfully queued.
ProtectedsetBoolOption
ProtectedsetInt32Option
ProtectedsetInt64Option
ProtectedsetStringOption
ProtectedsetUint32Option
ProtectedsetUint64Option
unbind
- unbind(address): Promise<void>
Unbinds the socket to the given address. During unbind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.Parameters
- address: string
Address to unbind this socket from.
Returns Promise<void>
Resolved when the socket was successfully unbound.
- address: string
Class XSubscriber
Same as Subscriber, except that you subscribe by sending subscription messages to the socket. Subscription message is a byte 1 (for subscriptions) or byte 0 (for unsubscriptions) followed by the subscription body. Messages without a sub/unsub prefix may also be sent, but have no effect on subscription status.
Hierarchy (View Summary)
Index
Constructors
Properties
Methods
Constructors
constructor
- new XSubscriber(
options?: {
affinity?: number;
backlog?: number;
connectTimeout?: number;
context?: Context;
curvePublicKey?: null | string;
curveSecretKey?: null | string;
curveServer?: boolean;
curveServerKey?: null | string;
gssapiPlainText?: boolean;
gssapiPrincipal?: null | string;
gssapiPrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
gssapiServer?: boolean;
gssapiServicePrincipal?: null | string;
gssapiServicePrincipalNameType?:
| "hostBased"
| "userName"
| "krb5Principal";
handshakeInterval?: number;
heartbeatInterval?: number;
heartbeatTimeout?: number;
heartbeatTimeToLive?: number;
immediate?: boolean;
interface?: null
| string;
ipv6?: boolean;
linger?: number;
loopbackFastPath?: boolean;
maxMessageSize?: number;
multicastHops?: number;
multicastMaxTransportDataUnit?: number;
plainPassword?: null | string;
plainServer?: boolean;
plainUsername?: null | string;
rate?: number;
receiveBufferSize?: number;
receiveHighWaterMark?: number;
receiveTimeout?: number;
reconnectInterval?: number;
reconnectMaxInterval?: number;
recoveryInterval?: number;
sendBufferSize?: number;
sendHighWaterMark?: number;
sendTimeout?: number;
socksProxy?: null | string;
tcpAcceptFilter?: null | string;
tcpKeepalive?: number;
tcpKeepaliveCount?: number;
tcpKeepaliveIdle?: number;
tcpKeepaliveInterval?: number;
tcpMaxRetransmitTimeout?: number;
typeOfService?: number;
vmciBufferMaxSize?: number;
vmciBufferMinSize?: number;
vmciBufferSize?: number;
vmciConnectTimeout?: number;
zapDomain?: null | string;
zapEnforceDomain?: boolean;
},
): XSubscriber Parameters
Optionaloptions: {
affinity?: number;
backlog?: number;
connectTimeout?: number;
context?: Context;
curvePublicKey?: null | string;
curveSecretKey?: null | string;
curveServer?: boolean;
curveServerKey?: null | string;
gssapiPlainText?: boolean;
gssapiPrincipal?: null | string;
gssapiPrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
gssapiServer?: boolean;
gssapiServicePrincipal?: null | string;
gssapiServicePrincipalNameType?: "hostBased" | "userName" | "krb5Principal";
handshakeInterval?: number;
heartbeatInterval?: number;
heartbeatTimeout?: number;
heartbeatTimeToLive?: number;
immediate?: boolean;
interface?: null | string;
ipv6?: boolean;
linger?: number;
loopbackFastPath?: boolean;
maxMessageSize?: number;
multicastHops?: number;
multicastMaxTransportDataUnit?: number;
plainPassword?: null | string;
plainServer?: boolean;
plainUsername?: null | string;
rate?: number;
receiveBufferSize?: number;
receiveHighWaterMark?: number;
receiveTimeout?: number;
reconnectInterval?: number;
reconnectMaxInterval?: number;
recoveryInterval?: number;
sendBufferSize?: number;
sendHighWaterMark?: number;
sendTimeout?: number;
socksProxy?: null | string;
tcpAcceptFilter?: null | string;
tcpKeepalive?: number;
tcpKeepaliveCount?: number;
tcpKeepaliveIdle?: number;
tcpKeepaliveInterval?: number;
tcpMaxRetransmitTimeout?: number;
typeOfService?: number;
vmciBufferMaxSize?: number;
vmciBufferMinSize?: number;
vmciBufferSize?: number;
vmciConnectTimeout?: number;
zapDomain?: null | string;
zapEnforceDomain?: boolean;
}Optionalaffinity?: numberZMQ_AFFINITY
I/O thread affinity, which determines which threads from the ØMQ I/O thread pool associated with the socket's context shall handle newly created connections.
Note: This value is a bit mask, but values higher than
Number.MAX_SAFE_INTEGERmay not be represented accurately! This currently means that configurations beyond 52 threads are unreliable.Optionalbacklog?: numberZMQ_BACKLOG
Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.
OptionalconnectTimeout?: numberZMQ_CONNECT_TIMEOUT
Sets how long to wait before timing-out a connect() system call. The connect() system call normally takes a long time before it returns a time out error. Setting this option allows the library to time out the call at an earlier interval.
Optionalcontext?: ContextOptionalcurvePublicKey?: null | stringZMQ_CURVE_PUBLICKEY
Sets the socket's long term public key. You must set this on CURVE client sockets. A server socket does not need to know its own public key. You can create a new keypair with curveKeyPair().
OptionalcurveSecretKey?: null | stringZMQ_CURVE_SECRETKEY
Sets the socket's long term secret key. You must set this on both CURVE client and server sockets. You can create a new keypair with curveKeyPair().
OptionalcurveServer?: booleanZMQ_CURVE_SERVER
Defines whether the socket will act as server for CURVE security. A value of
truemeans the socket will act as CURVE server. A value offalsemeans the socket will not act as CURVE server, and its security role then depends on other option settings.OptionalcurveServerKey?: null | stringZMQ_CURVE_SERVERKEY
Sets the socket's long term server key. This is the public key of the CURVE server socket. You must set this on CURVE client sockets. This key must have been generated together with the server's secret key. You can create a new keypair with curveKeyPair().
OptionalgssapiPlainText?: booleanOptionalgssapiPrincipal?: null | stringOptionalgssapiPrincipalNameType?: "hostBased" | "userName" | "krb5Principal"OptionalgssapiServer?: booleanOptionalgssapiServicePrincipal?: null | stringOptionalgssapiServicePrincipalNameType?: "hostBased" | "userName" | "krb5Principal"OptionalhandshakeInterval?: numberZMQ_HANDSHAKE_IVL
Handshaking is the exchange of socket configuration information (socket type, identity, security) that occurs when a connection is first opened (only for connection-oriented transports). If handshaking does not complete within the configured time, the connection shall be closed. The value 0 means no handshake time limit.
OptionalheartbeatInterval?: numberZMQ_HEARTBEAT_IVL
Interval in milliseconds between sending ZMTP heartbeats for the specified socket. If this option is greater than 0, then a PING ZMTP command will be sent after every interval.
OptionalheartbeatTimeout?: numberZMQ_HEARTBEAT_TIMEOUT
How long (in milliseconds) to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic. This option is only valid if heartbeatInterval is greater than 0. The connection will time out if there is no traffic received after sending the PING command. The received traffic does not have to be a PONG command - any received traffic will cancel the timeout.
OptionalheartbeatTimeToLive?: numberZMQ_HEARTBEAT_TTL
The timeout in milliseconds on the remote peer for ZMTP heartbeats. If this option is greater than 0, the remote side shall time out the connection if it does not receive any more traffic within the TTL period. This option does not have any effect if heartbeatInterval is 0. Internally, this value is rounded down to the nearest decisecond, any value less than 100 will have no effect.
Optionalimmediate?: booleanZMQ_IMMEDIATE
By default queues will fill on outgoing connections even if the connection has not completed. This can lead to "lost" messages on sockets with round-robin routing (Request, Push, Dealer). If this option is set to
true, messages shall be queued only to completed connections. This will cause the socket to block if there are no other connections, but will prevent queues from filling on pipes awaiting connection.Optionalinterface?: null | stringZMQ_BINDTODEVICE
Binds the socket to the given network interface (Linux only). Allows to use Linux VRF, see: https://www.kernel.org/doc/Documentation/networking/vrf.txt. Requires the program to be ran as root or with
CAP_NET_RAW.Optionalipv6?: booleanZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
Optionallinger?: numberZMQ_LINGER
Determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with close().
OptionalloopbackFastPath?: booleanZMQ_LOOPBACK_FASTPATH
Enable faster TCP connections on loopback devices. An application can enable this option to reduce the latency and improve the performance of loopback operations on a TCP socket on Windows.
OptionalmaxMessageSize?: numberZMQ_MAXMSGSIZE
Limits the size of the inbound message. If a peer sends a message larger than the limit it is disconnected. Value of -1 means no limit.
OptionalmulticastHops?: numberZMQ_MULTICAST_HOPS
Sets the time-to-live field in every multicast packet sent from this socket. The default is 1 which means that the multicast packets don't leave the local network.
OptionalmulticastMaxTransportDataUnit?: numberZMQ_MULTICAST_MAXTPDU
Sets the maximum transport data unit size used for outbound multicast packets. This must be set at or below the minimum Maximum Transmission Unit (MTU) for all network paths over which multicast reception is required.
OptionalplainPassword?: null | stringZMQ_PLAIN_PASSWORD
Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
OptionalplainServer?: booleanZMQ_PLAIN_SERVER
Defines whether the socket will act as server for PLAIN security. A value of
truemeans the socket will act as PLAIN server. A value offalsemeans the socket will not act as PLAIN server, and its security role then depends on other option settings.OptionalplainUsername?: null | stringZMQ_PLAIN_USERNAME
Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
Optionalrate?: numberZMQ_RATE
Maximum send or receive data rate for multicast transports such as
pgm.OptionalreceiveBufferSize?: numberZMQ_RCVBUF
Underlying kernel receive buffer size in bytes. A value of -1 means leave the OS default unchanged.
OptionalreceiveHighWaterMark?: numberZMQ_RCVHWM
The high water mark is a hard limit on the maximum number of incoming messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
OptionalreceiveTimeout?: numberZMQ_RCVTIMEO
Sets the timeout receiving messages on the socket. If the value is 0, receive() will return a rejected promise immediately if there is no message to receive. If the value is -1, it will wait asynchronously until a message is available. For all other values, it will wait for a message for that amount of time before rejecting.
OptionalreconnectInterval?: numberZMQ_RECONNECT_IVL
Period ØMQ shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. The value -1 means no reconnection.
OptionalreconnectMaxInterval?: numberZMQ_RECONNECT_IVL_MAX
Maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled until reconnectMaxInterval is reached. This allows for exponential backoff strategy. Zero (the default) means no exponential backoff is performed and reconnect interval calculations are only based on reconnectInterval.
OptionalrecoveryInterval?: numberZMQ_RECOVERY_IVL
Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
OptionalsendBufferSize?: numberZMQ_SNDBUF
Underlying kernel transmit buffer size in bytes. A value of -1 means leave the OS default unchanged.
OptionalsendHighWaterMark?: numberZMQ_SNDHWM
The high water mark is a hard limit on the maximum number of outgoing messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
OptionalsendTimeout?: numberZMQ_SNDTIMEO
Sets the timeout for sending messages on the socket. If the value is 0, send() will return a rejected promise immediately if the message cannot be sent. If the value is -1, it will wait asynchronously until the message is sent. For all other values, it will try to send the message for that amount of time before rejecting.
OptionalsocksProxy?: null | stringZMQ_SOCKS_PROXY
The SOCKS5 proxy address that shall be used by the socket for the TCP connection(s). Does not support SOCKS5 authentication. If the endpoints are domain names instead of addresses they shall not be resolved and they shall be forwarded unchanged to the SOCKS proxy service in the client connection request message (address type 0x03 domain name).
OptionaltcpAcceptFilter?: null | stringZMQ_TCP_ACCEPT_FILTER
Assign a filter that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one filter is applied then new connection source IP should be matched. To clear all filters set to
null. Filter is a string with IPv6 or IPv4 CIDR.OptionaltcpKeepalive?: numberZMQ_TCP_KEEPALIVE
Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepaliveCount?: numberZMQ_TCP_KEEPALIVE_CNT
Overrides TCP_KEEPCNT socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepaliveIdle?: numberZMQ_TCP_KEEPALIVE_IDLE
Overrides TCP_KEEPIDLE / TCP_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
OptionaltcpKeepaliveInterval?: numberZMQ_TCP_KEEPALIVE_INTVL
Overrides TCP_KEEPINTVL socket option (if supported by the OS). The default value of -1 leaves it to the OS default.
OptionaltcpMaxRetransmitTimeout?: numberZMQ_TCP_MAXRT
Sets how long before an unacknowledged TCP retransmit times out (if supported by the OS). The system normally attempts many TCP retransmits following an exponential backoff strategy. This means that after a network outage, it may take a long time before the session can be re-established. Setting this option allows the timeout to happen at a shorter interval.
OptionaltypeOfService?: numberZMQ_TOS
Sets the ToS fields (the Differentiated Services (DS) and Explicit Congestion Notification (ECN) field) of the IP header. The ToS field is typically used to specify a packet's priority. The availability of this option is dependent on intermediate network equipment that inspect the ToS field and provide a path for low-delay, high-throughput, highly-reliable service, etc.
OptionalvmciBufferMaxSize?: numberZMQ_VMCI_BUFFER_MAX_SIZE
Maximum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciBufferMinSize?: numberZMQ_VMCI_BUFFER_MIN_SIZE
Minimum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciBufferSize?: numberZMQ_VMCI_BUFFER_SIZE
The size of the underlying buffer for the socket. Used during negotiation before the connection is established. For
vmci://transports only.OptionalvmciConnectTimeout?: numberZMQ_VMCI_CONNECT_TIMEOUT
Connection timeout for the socket. For
vmci://transports only.OptionalzapDomain?: null | stringZMQ_ZAP_DOMAIN
Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the default on all
tcp://connections), ZAP authentication only happens if you set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 for more details.OptionalzapEnforceDomain?: booleanZMQ_ZAP_ENFORCE_DOMAIN
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.
Returns XSubscriber
Properties
affinity
ZMQ_AFFINITY
I/O thread affinity, which determines which threads from the ØMQ I/O thread pool associated with the socket's context shall handle newly created connections.
Note: This value is a bit mask, but values higher than Number.MAX_SAFE_INTEGER may not be represented accurately! This currently means that configurations beyond 52 threads are unreliable.
backlog
ZMQ_BACKLOG
Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.
Readonlyclosed
Whether this socket was previously closed with close().
connectTimeout
ZMQ_CONNECT_TIMEOUT
Sets how long to wait before timing-out a connect() system call. The connect() system call normally takes a long time before it returns a time out error. Setting this option allows the library to time out the call at an earlier interval.
Readonlycontext
Context that this socket belongs to.
curvePublicKey
ZMQ_CURVE_PUBLICKEY
Sets the socket's long term public key. You must set this on CURVE client sockets. A server socket does not need to know its own public key. You can create a new keypair with curveKeyPair().
curveSecretKey
ZMQ_CURVE_SECRETKEY
Sets the socket's long term secret key. You must set this on both CURVE client and server sockets. You can create a new keypair with curveKeyPair().
curveServer
ZMQ_CURVE_SERVER
Defines whether the socket will act as server for CURVE security. A value of true means the socket will act as CURVE server. A value of false means the socket will not act as CURVE server, and its security role then depends on other option settings.
curveServerKey
ZMQ_CURVE_SERVERKEY
Sets the socket's long term server key. This is the public key of the CURVE server socket. You must set this on CURVE client sockets. This key must have been generated together with the server's secret key. You can create a new keypair with curveKeyPair().
Readonlyevents
Event Observer for this socket. This starts up a ØMQ monitoring socket internally that receives all socket events.
gssapiPlainText
gssapiPrincipal
gssapiPrincipalNameType
gssapiServer
gssapiServicePrincipal
gssapiServicePrincipalNameType
handshakeInterval
ZMQ_HANDSHAKE_IVL
Handshaking is the exchange of socket configuration information (socket type, identity, security) that occurs when a connection is first opened (only for connection-oriented transports). If handshaking does not complete within the configured time, the connection shall be closed. The value 0 means no handshake time limit.
heartbeatInterval
ZMQ_HEARTBEAT_IVL
Interval in milliseconds between sending ZMTP heartbeats for the specified socket. If this option is greater than 0, then a PING ZMTP command will be sent after every interval.
heartbeatTimeout
ZMQ_HEARTBEAT_TIMEOUT
How long (in milliseconds) to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic. This option is only valid if heartbeatInterval is greater than 0. The connection will time out if there is no traffic received after sending the PING command. The received traffic does not have to be a PONG command - any received traffic will cancel the timeout.
heartbeatTimeToLive
ZMQ_HEARTBEAT_TTL
The timeout in milliseconds on the remote peer for ZMTP heartbeats. If this option is greater than 0, the remote side shall time out the connection if it does not receive any more traffic within the TTL period. This option does not have any effect if heartbeatInterval is 0. Internally, this value is rounded down to the nearest decisecond, any value less than 100 will have no effect.
immediate
ZMQ_IMMEDIATE
By default queues will fill on outgoing connections even if the connection has not completed. This can lead to "lost" messages on sockets with round-robin routing (Request, Push, Dealer). If this option is set to true, messages shall be queued only to completed connections. This will cause the socket to block if there are no other connections, but will prevent queues from filling on pipes awaiting connection.
interface
ZMQ_BINDTODEVICE
Binds the socket to the given network interface (Linux only). Allows to use Linux VRF, see: https://www.kernel.org/doc/Documentation/networking/vrf.txt. Requires the program to be ran as root or with CAP_NET_RAW.
ipv6
ZMQ_IPV6
Enable or disable IPv6. When IPv6 is enabled, the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts.
ReadonlylastEndpoint
ZMQ_LAST_ENDPOINT
The last endpoint bound for TCP and IPC transports.
linger
ZMQ_LINGER
Determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with close().
loopbackFastPath
ZMQ_LOOPBACK_FASTPATH
Enable faster TCP connections on loopback devices. An application can enable this option to reduce the latency and improve the performance of loopback operations on a TCP socket on Windows.
maxMessageSize
ZMQ_MAXMSGSIZE
Limits the size of the inbound message. If a peer sends a message larger than the limit it is disconnected. Value of -1 means no limit.
multicastHops
ZMQ_MULTICAST_HOPS
Sets the time-to-live field in every multicast packet sent from this socket. The default is 1 which means that the multicast packets don't leave the local network.
multicastMaxTransportDataUnit
ZMQ_MULTICAST_MAXTPDU
Sets the maximum transport data unit size used for outbound multicast packets. This must be set at or below the minimum Maximum Transmission Unit (MTU) for all network paths over which multicast reception is required.
plainPassword
ZMQ_PLAIN_PASSWORD
Sets the password for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
plainServer
ZMQ_PLAIN_SERVER
Defines whether the socket will act as server for PLAIN security. A value of true means the socket will act as PLAIN server. A value of false means the socket will not act as PLAIN server, and its security role then depends on other option settings.
plainUsername
ZMQ_PLAIN_USERNAME
Sets the username for outgoing connections over TCP or IPC. If you set this to a non-null value, the security mechanism used for connections shall be PLAIN.
rate
ZMQ_RATE
Maximum send or receive data rate for multicast transports such as pgm.
Readonlyreadable
Whether any messages are currently available. If true, the next call to Readable.receive() will immediately read a message from the socket. For sockets that cannot receive messsages this is always false.
receiveBufferSize
ZMQ_RCVBUF
Underlying kernel receive buffer size in bytes. A value of -1 means leave the OS default unchanged.
receiveHighWaterMark
ZMQ_RCVHWM
The high water mark is a hard limit on the maximum number of incoming messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
receiveTimeout
ZMQ_RCVTIMEO
Sets the timeout receiving messages on the socket. If the value is 0, receive() will return a rejected promise immediately if there is no message to receive. If the value is -1, it will wait asynchronously until a message is available. For all other values, it will wait for a message for that amount of time before rejecting.
reconnectInterval
ZMQ_RECONNECT_IVL
Period ØMQ shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. The value -1 means no reconnection.
reconnectMaxInterval
ZMQ_RECONNECT_IVL_MAX
Maximum period ØMQ shall wait between attempts to reconnect. On each reconnect attempt, the previous interval shall be doubled until reconnectMaxInterval is reached. This allows for exponential backoff strategy. Zero (the default) means no exponential backoff is performed and reconnect interval calculations are only based on reconnectInterval.
recoveryInterval
ZMQ_RECOVERY_IVL
Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
ReadonlysecurityMechanism
ZMQ_MECHANISM
Returns the current security mechanism for the socket, if any. The security mechanism is set implictly by using any of the relevant security options. The returned value is one of:
null- No security mechanism is used."plain"- The PLAIN mechanism defines a simple username/password mechanism that lets a server authenticate a client. PLAIN makes no attempt at security or confidentiality."curve"- The CURVE mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server. CURVE is intended for use on public networks."gssapi"- The GSSAPI mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server using the Generic Security Service Application Program Interface (GSSAPI). The GSSAPI mechanism can be used on both public and private networks.
sendBufferSize
ZMQ_SNDBUF
Underlying kernel transmit buffer size in bytes. A value of -1 means leave the OS default unchanged.
sendHighWaterMark
ZMQ_SNDHWM
The high water mark is a hard limit on the maximum number of outgoing messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
sendTimeout
ZMQ_SNDTIMEO
Sets the timeout for sending messages on the socket. If the value is 0, send() will return a rejected promise immediately if the message cannot be sent. If the value is -1, it will wait asynchronously until the message is sent. For all other values, it will try to send the message for that amount of time before rejecting.
socksProxy
ZMQ_SOCKS_PROXY
The SOCKS5 proxy address that shall be used by the socket for the TCP connection(s). Does not support SOCKS5 authentication. If the endpoints are domain names instead of addresses they shall not be resolved and they shall be forwarded unchanged to the SOCKS proxy service in the client connection request message (address type 0x03 domain name).
tcpAcceptFilter
ZMQ_TCP_ACCEPT_FILTER
Assign a filter that will be applied for each new TCP transport connection on a listening socket. If no filters are applied, then the TCP transport allows connections from any IP address. If at least one filter is applied then new connection source IP should be matched. To clear all filters set to null. Filter is a string with IPv6 or IPv4 CIDR.
tcpKeepalive
ZMQ_TCP_KEEPALIVE
Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveCount
ZMQ_TCP_KEEPALIVE_CNT
Overrides TCP_KEEPCNT socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveIdle
ZMQ_TCP_KEEPALIVE_IDLE
Overrides TCP_KEEPIDLE / TCP_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.
tcpKeepaliveInterval
ZMQ_TCP_KEEPALIVE_INTVL
Overrides TCP_KEEPINTVL socket option (if supported by the OS). The default value of -1 leaves it to the OS default.
tcpMaxRetransmitTimeout
ZMQ_TCP_MAXRT
Sets how long before an unacknowledged TCP retransmit times out (if supported by the OS). The system normally attempts many TCP retransmits following an exponential backoff strategy. This means that after a network outage, it may take a long time before the session can be re-established. Setting this option allows the timeout to happen at a shorter interval.
ReadonlythreadSafe
ZMQ_THREAD_SAFE
Whether or not the socket is threadsafe. Currently only DRAFT sockets is thread-safe.
Readonlytype
ZMQ_TYPE
Retrieve the socket type. This is fairly useless because you can test the socket class with e.g. socket instanceof Dealer.
typeOfService
ZMQ_TOS
Sets the ToS fields (the Differentiated Services (DS) and Explicit Congestion Notification (ECN) field) of the IP header. The ToS field is typically used to specify a packet's priority. The availability of this option is dependent on intermediate network equipment that inspect the ToS field and provide a path for low-delay, high-throughput, highly-reliable service, etc.
vmciBufferMaxSize
ZMQ_VMCI_BUFFER_MAX_SIZE
Maximum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferMinSize
ZMQ_VMCI_BUFFER_MIN_SIZE
Minimum size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciBufferSize
ZMQ_VMCI_BUFFER_SIZE
The size of the underlying buffer for the socket. Used during negotiation before the connection is established. For vmci:// transports only.
vmciConnectTimeout
ZMQ_VMCI_CONNECT_TIMEOUT
Connection timeout for the socket. For vmci:// transports only.
Readonlywritable
Whether any messages can be queued for sending. If true, the next call to Writable.send() will immediately queue a message on the socket. For sockets that cannot send messsages this is always false.
zapDomain
ZMQ_ZAP_DOMAIN
Sets the domain for ZAP (ZMQ RFC 27) authentication. For NULL security (the default on all tcp:// connections), ZAP authentication only happens if you set a non-empty domain. For PLAIN and CURVE security, ZAP requests are always made, if there is a ZAP handler present. See http://rfc.zeromq.org/spec:27 for more details.
zapEnforceDomain
ZMQ_ZAP_ENFORCE_DOMAIN
The ZAP (ZMQ RFC 27) authentication protocol specifies that a domain must always be set. Older versions of libzmq did not follow the spec and allowed an empty domain to be set. This option can be used to enabled or disable the stricter, backward incompatible behaviour. For now it is disabled by default, but in a future version it will be enabled by default.
Methods
[asyncIterator]
- "[asyncIterator]"(): AsyncIterator<Buffer[]>
Asynchronously iterate over messages becoming available on the socket. When the socket is closed with Socket.close(), the iterator will return. Returning early from the iterator will not close the socket unless it also goes out of scope.
for await (const [msg] of socket) {
// handle messages
} +Returns AsyncIterator<Buffer[]>
bind
- bind(address: string): Promise<void>
Binds the socket to the given address. During bind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.You can use
*in place of a hostname to bind on all interfaces/addresses, and you can use*in place of a port to bind to a random port (which can be retrieved with lastEndpoint later).await socket.bind("tcp://127.0.0.1:3456")
await socket.bind("tcp://*:3456") // binds on all interfaces
await socket.bind("tcp://127.0.0.1:*") // binds on random port +Parameters
- address: string
Address to bind this socket to.
Returns Promise<void>
Resolved when the socket was successfully bound.
- address: string
bindSync
- bindSync(address: string): void
Binds the socket to the given address. During bind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.You can use
*in place of a hostname to bind on all interfaces/addresses, and you can use*in place of a port to bind to a random port (which can be retrieved with lastEndpoint later).socket.bindSync("tcp://127.0.0.1:3456")
socket.bindSync("tcp://*:3456") // binds on all interfaces
socket.bindSync("tcp://127.0.0.1:*") // binds on random port +Parameters
- address: string
Address to bind this socket to.
Returns void
Resolved when the socket was successfully bound.
- address: string
close
- close(): void
Closes the socket and disposes of all resources. Any messages that are queued may be discarded or sent in the background depending on the linger setting.
After this method is called, it is no longer possible to call any other methods on this socket.
Sockets that go out of scope and have no Readable.receive() or Writable.send() operations in progress will automatically be closed. Therefore it is not necessary in most applications to call close() manually.
Calling this method on a socket that is already closed is a no-op.
Returns void
connect
disconnect
- disconnect(address: string): void
Disconnects a previously connected socket from the given address and returns immediately. Disonnection will happen asynchronously in the background.
socket.disconnect("tcp://127.0.0.1:3456") +Parameters
- address: string
The previously connected address to disconnect from.
Returns void
- address: string
ProtectedgetBoolOption
ProtectedgetInt32Option
ProtectedgetInt64Option
ProtectedgetStringOption
ProtectedgetUint32Option
ProtectedgetUint64Option
receive
- receive(): Promise<Buffer[]>
Waits for the next single or multipart message to become availeble on the socket. Reads a message immediately if possible. If no messages can be read, it will wait asynchonously. The promise will be resolved with an array containing the parts of the next message when available.
const [msg] = await socket.receive()
const [part1, part2] = await socket.receive() +Reading may fail (eventually) if the socket has been configured with a receiveTimeout.
A call to receive() is guaranteed to return with a resolved promise immediately if a message could be read from the socket directly.
Only one asynchronously blocking call to receive() can be in progress simultaneously. If you call receive() again on the same socket it will return a rejected promise with an
EBUSYerror. For example, if no messages can be read and noawaitis used:socket.receive() // -> pending promise until read is possible
socket.receive() // -> promise rejection with `EBUSY` error +Note: Due to the nature of Node.js and to avoid blocking the main thread, this method always attempts to read messages with the
ZMQ_DONTWAITflag. It polls asynchronously if reading is not currently possible. This means that all functionality related to timeouts and blocking behaviour is reimplemented in the Node.js bindings. Any differences in behaviour with the native ZMQ library is considered a bug.Returns Promise<Buffer[]>
Resolved with message parts that were successfully read.
send
- send(message: MessageLike | MessageLike[], ...options: []): Promise<void>
Sends a single message or a multipart message on the socket. Queues the message immediately if possible, and returns a resolved promise. If the message cannot be queued because the high water mark has been reached, it will wait asynchronously. The promise will be resolved when the message was queued successfully.
await socket.send("hello world")
await socket.send(["hello", "world"]) +Queueing may fail eventually if the socket has been configured with a sendTimeout.
A call to send() is guaranteed to return with a resolved promise immediately if the message could be queued directly.
Only one asynchronously blocking call to send() may be executed simultaneously. If you call send() again on a socket that is in the mute state it will return a rejected promise with an
EBUSYerror.The reason for disallowing multiple send() calls simultaneously is that it could create an implicit queue of unsendable outgoing messages. This would circumvent the socket's sendHighWaterMark. Such an implementation could even exhaust all system memory and cause the Node.js process to abort.
For most application you should not notice this implementation detail. Only in rare occasions will a call to send() that does not resolve immediately be undesired. Here are some common scenarios:
If you wish to send a message, use
await send(...). ZeroMQ socket types have been carefully designed to give you the correct blocking behaviour on the chosen socket type in almost all cases:If sending is not possible, it is often better to wait than to continue as if nothing happened. For example, on a Request socket, you can only receive a reply once a message has been sent; so waiting until a message could be queued before continuing with the rest of the program (likely to read from the socket) is required.
Certain socket types (such as Router) will always allow queueing messages and
await send(...)won't delay any code that comes after. This makes sense for routers, since typically you don't want a single send operation to stop the handling of other incoming or outgoing messages.
If you wish to send on an occasionally blocking socket (for example on a Router with the Router.mandatory option set, or on a Dealer) and you're 100% certain that dropping a message is better than blocking, then you can set the sendTimeout option to
0to effectively force send() to always resolve immediately. Be prepared to catch exceptions if sending a message is not immediately possible.If you wish to send on a socket and messages should be queued before they are dropped, you should implement a simple queue in JavaScript. Such a queue is not provided by this library because most real world applications need to deal with undeliverable messages in more complex ways - for example, they might need to reply with a status message; or first retry delivery a certain number of times before giving up.
Parameters
- message: MessageLike | MessageLike[]
Single message or multipart message to queue for sending.
- ...options: []
Any options, if applicable to the socket type (DRAFT only).
Returns Promise<void>
Resolved when the message was successfully queued.
ProtectedsetBoolOption
ProtectedsetInt32Option
ProtectedsetInt64Option
ProtectedsetStringOption
ProtectedsetUint32Option
ProtectedsetUint64Option
unbind
- unbind(address: string): Promise<void>
Unbinds the socket to the given address. During unbind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.Parameters
- address: string
Address to unbind this socket from.
Returns Promise<void>
Resolved when the socket was successfully unbound.
- address: string
unbindSync
- unbindSync(address: string): void
Unbinds the socket to the given address. During unbind() the socket cannot be used. Do not call any other methods until the returned promise resolves. Make sure to use
await.Parameters
- address: string
Address to unbind this socket from.
Returns void
Resolved when the socket was successfully unbound.
- address: string
Function curveKeyPair
- curve
Key (): {Pair
publicKey: string;
secretKey: string;
} Returns a new random key pair to be used with the CURVE security mechanism.
To correctly connect two sockets with this mechanism:
- Generate a client keypair with curveKeyPair().
- Assign the private and public key on the client socket with Socket.curveSecretKey and Socket.curvePublicKey.
- Generate a server keypair with curveKeyPair().
- Assign the private key on the server socket with Socket.curveSecretKey.
- Assign the public key on the client socket with Socket.curveServerKey. The server does not need to know its own public key. Key distribution is not handled by the CURVE security mechanism.
Returns {
publicKey: string;
secretKey: string;
}An object with a
publicKeyand asecretKeyproperty, each being a 40 character Z85-encoded string.public
Key : stringsecret
Key : string
- Generate a client keypair with curveKeyPair().
Function curveKeyPair
- curveKeyPair(): { publicKey: string; secretKey: string }
Returns a new random key pair to be used with the CURVE security mechanism.
To correctly connect two sockets with this mechanism:
- Generate a client keypair with curveKeyPair().
- Assign the private and public key on the client socket with Socket.curveSecretKey and Socket.curvePublicKey.
- Generate a server keypair with curveKeyPair().
- Assign the private key on the server socket with Socket.curveSecretKey.
- Assign the public key on the client socket with Socket.curveServerKey. The server does not need to know its own public key. Key distribution is not handled by the CURVE security mechanism.
Returns { publicKey: string; secretKey: string }
An object with a
publicKeyand asecretKeyproperty, each being a 40 character Z85-encoded string.- Generate a client keypair with curveKeyPair().
zeromq.js
ZeroMQ.js Next Generation
ØMQ bindings for Node.js. The goals of this library are:
- Semantically similar to the native ØMQ library, while sticking to JavaScript idioms.
- Use modern JavaScript and Node.js features such as
async/awaitand async iterators. - High performance.
- Fully usable with TypeScript (3+).
- Compatible with Zeromq 4/5 via "zeromq/v5-compat"
Useful links
- ZeroMQ.js API reference.
- ZeroMQ project documentation.
- Note: The Node.js examples on zeromq.org do not yet reflect the new API, but the Guide in particular is still a good introduction to ZeroMQ for new users.
Table of contents
- ZeroMQ.js Next Generation
Installation
Install ZeroMQ.js with prebuilt binaries:
npm install zeromq
-Supported versions:
- Node.js v12 (requires a N-API)
Prebuilt binaries
The following platforms have a prebuilt binary available:
Windows on x86/x86-64
Zeromq binaries on Windows 10 or older need Visual C++ Redistributable to be installed.
Linux on x86-64 with libstdc++.so.6.0.21+ (glibc++ 3.4.21+), for example:
- Debian 9+ (Stretch or later)
- Ubuntu 16.04+ (Xenial or later)
- CentOS 8+
Linux on x86-64 with musl, for example:
- Alpine 3.3+
MacOS 10.9+ on x86-64
If a prebuilt binary is not available for your platform, installing will attempt to start a build from source.
Building from source
If a prebuilt binary is unavailable or if you want to pass certain options during build, you can build this package from source.
Make sure you have the following installed before attempting to build from source:
- Node.js 12+ or Electron
- A working C++17 compiler toolchain with make
- Python 3 with Node 12+ (or legacy Python 2.7)
- CMake 2.8+
- curl
To install from source, specify build_from_source=true in a .npmrc file
build_from_source=true
-When building from source, you can also specify additional build options in a .npmrc file in your project:
Available Build Options
👉🏻 Options
Curve support
Enables CURVE security for encrypted communications. To enable CURVE support, add the following to your .npmrc:
zmq_curve="true"
-Libsodium for Curve
Enable libsodium for CURVE security instead of the built-in tweetnacl implementation. This can provide better performance for CURVE operations. To use libsodium, add the following to your .npmrc:
zmq_sodium="true"
-Draft support
By default libzmq is built with support for Draft patterns (e.g. server-client, radio-dish, scatter-gather). If you want to build libzmq without support for Draft, you can specify the following in .npmrc:
zmq_draft=false
-Websocket support
Enables WebSocket transport, allowing ZeroMQ to communicate over WebSockets. To enable WebSocket support, add the following to your .npmrc:
zmq_websockets="true"
-Secure Websocket support
Enables WebSocket transport with TLS (wss), providing secure WebSocket communications. To enable secure WebSocket support, add the following to your .npmrc:
zmq_websockets_secure="true"
-Not Synchronous Resolve
Enables immediate send/receive on the socket without synchronous resolution. This option can improve performance in certain scenarios by allowing operations to proceed without waiting for synchronous resolution. To enable this feature, add the following to your .npmrc:
zmq_no_sync_resolve="true"
-MacOS Deployment Target
Specifies the minimum macOS version that the binary will be compatible with. This is particularly useful when building for different macOS versions. To set this, add the following to your .npmrc, replacing 10.15 with your desired minimum macOS version:
macosx_deployment_target="10.15"
-Examples
Here some examples of different features are provided. More examples can be found in the examples directory.
You can also browse the API reference documentation to see all socket types, methods & options as well as more detailed information about how to apply them.
Note: If you are new to ZeroMQ, please start with the ZeroMQ documentation.
Basic Usage
ES modules:
import {Request} from "zeromq"
// or as namespace
import * as zmq from "zeromq"
const reqSock = new Request()
//...
const repSock = new zmq.Reply()
+zeromq.js zeromq.js
ZeroMQ.js Next Generation
ØMQ bindings for Node.js. The goals of this library are:
- Semantically similar to the native ØMQ library, while sticking to JavaScript idioms.
- Use modern JavaScript and Node.js features such as
async/await and async iterators. - High performance.
- Fully usable with TypeScript (3+).
- Compatible with Zeromq 4/5 via "zeromq/v5-compat"
- Secure Curve protocol with Libsodium
- Zeromq Draft API support
Useful links
- ZeroMQ.js API reference.
- ZeroMQ project documentation.
- Note: The Node.js examples on zeromq.org do not yet reflect the new API, but the Guide in particular is still a good introduction to ZeroMQ for new users.
Table of contents
- ZeroMQ.js Next Generation
Installation
Install ZeroMQ.js with prebuilt binaries:
npm install zeromq
+
Supported versions:
- Node.js v12 (requires a N-API)
Prebuilt binaries
The following platforms have a prebuilt binary available:
Windows on x86/x86-64
Zeromq binaries on Windows 10 or older need Visual C++ Redistributable to be installed.
Linux on x86-64 with libstdc++.so.6.0.21+ (glibc++ 3.4.21+), for example:
- Debian 9+ (Stretch or later)
- Ubuntu 16.04+ (Xenial or later)
- CentOS 8+
Linux on x86-64 with musl, for example:
- Alpine 3.3+
MacOS 10.9+ on x86-64
If a prebuilt binary is not available for your platform, installing will attempt to start a build from source.
Building from source
If a prebuilt binary is unavailable, or if you want to pass certain options during build, you can build this package from source.
Make sure you have the following installed before attempting to build from source:
- Node.js 10+ or Electron
- C++17 compiler toolchain (e.g. LLVM, GCC, MSVC)
- Python 3
- CMake 3.16+
- vcpkg dependencies (e.g. on Linux it needs curl, unzip, zip, tar, git, pkg-config)
For Curve:
- automake
- autoconf
- libtool
To install from source, specify build_from_source=true in a .npmrc file
build_from_source=true
+
When building from source, you can also specify additional build options in a .npmrc file in your project:
Available Build Options
👉🏻 Options
Curve with Libsodium support
(Enabled by default)
Enables CURVE security for encrypted communications. Zeromq uses libsodium for CURVE security. To enable CURVE support, add the following to your .npmrc:
zmq_curve="true"
+zmq_sodium="true"
+
Building libsodium requires these dependencies on Linux/MacOS: autoconf automake libtool, which can be installed via apt-get or brew, etc.
Draft support
(Enabled by default)
By default libzmq is built with support for Draft patterns (e.g. server-client, radio-dish, scatter-gather). If you want to build libzmq without support for Draft, you can specify the following in .npmrc:
zmq_draft=false
+
Websocket support
Enables WebSocket transport, allowing ZeroMQ to communicate over WebSockets. To enable WebSocket support, add the following to your .npmrc:
zmq_websockets="true"
+
Secure Websocket support
Enables WebSocket transport with TLS (wss), providing secure WebSocket communications. To enable secure WebSocket support, add the following to your .npmrc:
zmq_websockets_secure="true"
+
Not Synchronous Resolve
Enables immediate send/receive on the socket without synchronous resolution. This option can improve performance in certain scenarios by allowing operations to proceed without waiting for synchronous resolution. To enable this feature, add the following to your .npmrc:
zmq_no_sync_resolve="true"
+
MacOS Deployment Target
Specifies the minimum macOS version that the binary will be compatible with. This is particularly useful when building for different macOS versions. To set this, add the following to your .npmrc, replacing 10.15 with your desired minimum macOS version:
macosx_deployment_target="10.15"
+
Examples
Here some examples of different features are provided. More examples can be found in the examples directory.
You can also browse the API reference documentation to see all socket types, methods & options as well as more detailed information about how to apply them.
Note: If you are new to ZeroMQ, please start with the ZeroMQ documentation.
Basic Usage
ES modules:
import {Request} from "zeromq"
// or as namespace
import * as zmq from "zeromq"
const reqSock = new Request()
//...
const repSock = new zmq.Reply()
Commonjs:
const zmq = require("zeromq")
const reqSock = new zmq.Request()
//...
const repSock = new zmq.Reply()
-
Push/Pull
This example demonstrates how a producer pushes information onto a socket and how a worker pulls information from the socket.
producer.js
Creates a producer to push information onto a socket.
import * as zmq from "zeromq"
async function run() {
const sock = new zmq.Push()
await sock.bind("tcp://127.0.0.1:3000")
console.log("Producer bound to port 3000")
while (true) {
await sock.send("some work")
await new Promise(resolve => {
setTimeout(resolve, 500)
})
}
}
run()
-
worker.js
Creates a worker to pull information from the socket.
import * as zmq from "zeromq"
async function run() {
const sock = new zmq.Pull()
sock.connect("tcp://127.0.0.1:3000")
console.log("Worker connected to port 3000")
for await (const [msg] of sock) {
console.log("work: %s", msg.toString())
}
}
run()
-
Pub/Sub
This example demonstrates using zeromq in a classic Pub/Sub, Publisher/Subscriber, application.
publisher.js
Create the publisher which sends messages.
import * as zmq from "zeromq"
async function run() {
const sock = new zmq.Publisher()
await sock.bind("tcp://127.0.0.1:3000")
console.log("Publisher bound to port 3000")
while (true) {
console.log("sending a multipart message envelope")
await sock.send(["kitty cats", "meow!"])
await new Promise(resolve => {
setTimeout(resolve, 500)
})
}
}
run()
-
subscriber.js
Create a subscriber to connect to a publisher's port to receive messages.
import * as zmq from "zeromq"
async function run() {
const sock = new zmq.Subscriber()
sock.connect("tcp://127.0.0.1:3000")
sock.subscribe("kitty cats")
console.log("Subscriber connected to port 3000")
for await (const [topic, msg] of sock) {
console.log(
"received a message related to:",
topic,
"containing message:",
msg,
)
}
}
run()
-
Req/Rep
This example illustrates a request from a client and a reply from a server.
client.js
import * as zmq from "zeromq"
async function run() {
const sock = new zmq.Request()
sock.connect("tcp://127.0.0.1:3000")
console.log("Producer bound to port 3000")
await sock.send("4")
const [result] = await sock.receive()
console.log(result)
}
run()
-
server.js
import * as zmq from "zeromq"
async function run() {
const sock = new zmq.Reply()
await sock.bind("tcp://127.0.0.1:3000")
for await (const [msg] of sock) {
await sock.send((2 * parseInt(msg.toString(), 10)).toString())
}
}
run()
-
Zeromq 4 and 5 Compatibility layer
The next generation version of the library features a compatibility layer for ZeroMQ.js versions 4 and 5. This is recommended for users upgrading from previous versions.
Example:
const zmq = require("zeromq/v5-compat")
const pub = zmq.socket("pub")
const sub = zmq.socket("sub")
pub.bind("tcp://*:3456", err => {
if (err) throw err
sub.connect("tcp://127.0.0.1:3456")
pub.send("message")
sub.on("message", msg => {
// Handle received message...
})
})
-
TypeScript
This library provides typings for TypeScript version 3.0.x and later.
Requirements
- For TypeScript version >= 3:
- For TypeScript version < 3.6:
- either set
compilerOptions.target to esnext or later (e.g. es2018) - or add the following, or similar, libraries to
compilerOptions.lib (and include their corresponding polyfills if needed): es2015, ESNext.AsyncIterable
Contribution
If you are interested in making contributions to this project, please read the following sections.
Dependencies
In order to develop and test the library, you'll need the tools required to build from source (see above).
Additionally, having clang-format is strongly recommended.
Defining new options
Socket and context options can be set at runtime, even if they are not implemented by this library. By design, this requires no recompilation if the built version of ZeroMQ has support for them. This allows library users to test and use options that have been introduced in recent versions of ZeroMQ without having to modify this library. Of course we'd love to include support for new options in an idiomatic way.
Options can be set as follows:
const {Dealer} = require("zeromq")
/* This defines an accessor named 'sendHighWaterMark', which corresponds to
the constant ZMQ_SNDHWM, which is defined as '23' in zmq.h. The option takes
integers. The accessor name has been converted to idiomatic JavaScript.
Of course, this particular option already exists in this library. */
class MyDealer extends Dealer {
get sendHighWaterMark(): number {
return this.getInt32Option(23)
}
set sendHighWaterMark(value: number) {
this.setInt32Option(23, value)
}
}
const sock = new MyDealer({sendHighWaterMark: 456})
-
When submitting pull requests for new socket/context options, please consider the following:
- The option is documented in the TypeScript interface.
- The option is only added to relevant socket types, and if the ZMQ_ constant has a prefix indicating which type it applies to, it is stripped from the name as it is exposed in JavaScript.
- The name as exposed in this library is idiomatic for JavaScript, spelling out any abbreviations and using proper
camelCase naming conventions. - The option is a value that can be set on a socket, and you don't think it should actually be a method.
Testing
The test suite can be run with:
npm install
npm run build
npm run test
-
The test suite will validate and fix the coding style, run all unit tests and verify the validity of the included TypeScript type definitions.
Some tests are not enabled by default:
- API Compatibility tests from ZeroMQ 5.x have been disabled by default. You can include the tests with
INCLUDE_COMPAT_TESTS=1 npm run test - Some transports are not reliable on some older versions of ZeroMQ, the relevant tests will be skipped for those versions automatically.
Publishing
To publish a new version, run:
npm version <new version>
git push && git push --tags
-
Wait for continuous integration to finish. Prebuilds will be generated for all supported platforms and attached to a Github release. Documentation is automatically generated and committed to gh-pages. Finally, a new NPM package version will be automatically released.
History
Version 6+ is a complete rewrite of previous versions of ZeroMQ.js in order to be more reliable, correct, and usable in modern JavaScript & TypeScript code as first outlined in this issue. Previous versions of ZeroMQ.js were based on zmq and a fork that included prebuilt binaries.
See detailed changes in the CHANGELOG.
\ No newline at end of file
+Push/Pull
This example demonstrates how a producer pushes information onto a socket and how a worker pulls information from the socket.
producer.js
Creates a producer to push information onto a socket.
import * as zmq from "zeromq"
async function run() {
const sock = new zmq.Push()
await sock.bind("tcp://127.0.0.1:3000")
console.log("Producer bound to port 3000")
while (true) {
await sock.send("some work")
await new Promise(resolve => {
setTimeout(resolve, 500)
})
}
}
run()
+worker.js
Creates a worker to pull information from the socket.
import * as zmq from "zeromq"
async function run() {
const sock = new zmq.Pull()
sock.connect("tcp://127.0.0.1:3000")
console.log("Worker connected to port 3000")
for await (const [msg] of sock) {
console.log("work: %s", msg.toString())
}
}
run()
+Pub/Sub
This example demonstrates using zeromq in a classic Pub/Sub, Publisher/Subscriber, application.
publisher.js
Create the publisher which sends messages.
import * as zmq from "zeromq"
async function run() {
const sock = new zmq.Publisher()
await sock.bind("tcp://127.0.0.1:3000")
console.log("Publisher bound to port 3000")
while (true) {
console.log("sending a multipart message envelope")
await sock.send(["kitty cats", "meow!"])
await new Promise(resolve => {
setTimeout(resolve, 500)
})
}
}
run()
+subscriber.js
Create a subscriber to connect to a publisher's port to receive messages.
import * as zmq from "zeromq"
async function run() {
const sock = new zmq.Subscriber()
sock.connect("tcp://127.0.0.1:3000")
sock.subscribe("kitty cats")
console.log("Subscriber connected to port 3000")
for await (const [topic, msg] of sock) {
console.log(
"received a message related to:",
topic,
"containing message:",
msg,
)
}
}
run()
+Req/Rep
This example illustrates a request from a client and a reply from a server.
client.js
import * as zmq from "zeromq"
async function run() {
const sock = new zmq.Request()
sock.connect("tcp://127.0.0.1:3000")
console.log("Producer bound to port 3000")
await sock.send("4")
const [result] = await sock.receive()
console.log(result)
}
run()
+server.js
import * as zmq from "zeromq"
async function run() {
const sock = new zmq.Reply()
await sock.bind("tcp://127.0.0.1:3000")
for await (const [msg] of sock) {
await sock.send((2 * parseInt(msg.toString(), 10)).toString())
}
}
run()
+Zeromq 4 and 5 Compatibility layer
The next generation version of the library features a compatibility layer for ZeroMQ.js versions 4 and 5. This is recommended for users upgrading from previous versions.
Example:
const zmq = require("zeromq/v5-compat")
const pub = zmq.socket("pub")
const sub = zmq.socket("sub")
pub.bind("tcp://*:3456", err => {
if (err) throw err
sub.connect("tcp://127.0.0.1:3456")
pub.send("message")
sub.on("message", msg => {
// Handle received message...
})
})
+TypeScript
This library provides typings for TypeScript version 3.0.x and later.
Requirements
- For TypeScript version >= 3:
- For TypeScript version < 3.6:
- either set
compilerOptions.targettoesnextor later (e.g.es2018) - or add the following, or similar, libraries to
compilerOptions.lib(and include their corresponding polyfills if needed):es2015,ESNext.AsyncIterable
- either set
Contribution
If you are interested in making contributions to this project, please read the following sections.
Dependencies
In order to develop and test the library, you'll need the tools required to build from source (see above).
Additionally, having clang-format is strongly recommended.
Defining new options
Socket and context options can be set at runtime, even if they are not implemented by this library. By design, this requires no recompilation if the built version of ZeroMQ has support for them. This allows library users to test and use options that have been introduced in recent versions of ZeroMQ without having to modify this library. Of course we'd love to include support for new options in an idiomatic way.
Options can be set as follows:
const {Dealer} = require("zeromq")
/* This defines an accessor named 'sendHighWaterMark', which corresponds to
the constant ZMQ_SNDHWM, which is defined as '23' in zmq.h. The option takes
integers. The accessor name has been converted to idiomatic JavaScript.
Of course, this particular option already exists in this library. */
class MyDealer extends Dealer {
get sendHighWaterMark(): number {
return this.getInt32Option(23)
}
set sendHighWaterMark(value: number) {
this.setInt32Option(23, value)
}
}
const sock = new MyDealer({sendHighWaterMark: 456})
+When submitting pull requests for new socket/context options, please consider the following:
- The option is documented in the TypeScript interface.
- The option is only added to relevant socket types, and if the ZMQ_ constant has a prefix indicating which type it applies to, it is stripped from the name as it is exposed in JavaScript.
- The name as exposed in this library is idiomatic for JavaScript, spelling out any abbreviations and using proper
camelCasenaming conventions. - The option is a value that can be set on a socket, and you don't think it should actually be a method.
Testing
The test suite can be run with:
npm install
npm run build
npm run test
+The test suite will validate and fix the coding style, run all unit tests and verify the validity of the included TypeScript type definitions.
Some tests are not enabled by default:
- API Compatibility tests from ZeroMQ 5.x have been disabled by default. You can include the tests with
INCLUDE_COMPAT_TESTS=1 npm run test - Some transports are not reliable on some older versions of ZeroMQ, the relevant tests will be skipped for those versions automatically.
Publishing
To publish a new version, run:
npm version <new version>
git push && git push --tags
+Wait for continuous integration to finish. Prebuilds will be generated for all supported platforms and attached to a Github release. Documentation is automatically generated and committed to gh-pages. Finally, a new NPM package version will be automatically released.
History
Version 6+ is a complete rewrite of previous versions of ZeroMQ.js in order to be more reliable, correct, and usable in modern JavaScript & TypeScript code as first outlined in this issue. Previous versions of ZeroMQ.js were based on zmq and a fork that included prebuilt binaries.
See detailed changes in the CHANGELOG.
Interface EventSubscriber
off<E>(type: E, listener: ((data: EventOfType<E>) => void)): EventSubscriber;
on<E>(type: E, listener: ((data: EventOfType<E>) => void)): EventSubscriber;
}
Hierarchy (view full)
- EventSubscriber
Methods
off
- off<E>(type, listener): EventSubscriber
Removes the specified listener function from the list of functions to call when the given event is observed.
Type Parameters
Parameters
- type: E
The type of event that the listener was listening for.
- listener: ((data: EventOfType<E>) => void)
The previously registered listener function.
- (data): void
Parameters
- data: EventOfType<E>
Returns void
Returns EventSubscriber
- type: E
on
- on<E>(type, listener): EventSubscriber
Adds a listener function which will be invoked when the given event type is observed. Calling this method will convert the Observer to event emitter mode, which will make it impossible to call Observer.receive() at the same time.
socket.events.on("bind", event => {
console.log(`Socket bound to ${event.address}`)
// ...
}) -Type Parameters
Parameters
- type: E
The type of event to listen for.
- listener: ((data: EventOfType<E>) => void)
The listener function that will be called with all event data when the event is observed.
- (data): void
Parameters
- data: EventOfType<E>
Returns void
Returns EventSubscriber
- type: E
Interface EventSubscriber
off<
E extends
| "unknown"
| "connect"
| "disconnect"
| "close"
| "end"
| "accept"
| "accept:error"
| "bind"
| "bind:error"
| "connect:delay"
| "connect:retry"
| "close:error"
| "handshake"
| "handshake:error:protocol"
| "handshake:error:auth"
| "handshake:error:other",
>(
type: E,
listener: (data: EventOfType<E>) => void,
): EventSubscriber;
on<
E extends
| "unknown"
| "connect"
| "disconnect"
| "close"
| "end"
| "accept"
| "accept:error"
| "bind"
| "bind:error"
| "connect:delay"
| "connect:retry"
| "close:error"
| "handshake"
| "handshake:error:protocol"
| "handshake:error:auth"
| "handshake:error:other",
>(
type: E,
listener: (data: EventOfType<E>) => void,
): EventSubscriber;
}
Hierarchy (View Summary)
- EventSubscriber
Methods
off
- off<
E extends
| "unknown"
| "connect"
| "disconnect"
| "close"
| "end"
| "accept"
| "accept:error"
| "bind"
| "bind:error"
| "connect:delay"
| "connect:retry"
| "close:error"
| "handshake"
| "handshake:error:protocol"
| "handshake:error:auth"
| "handshake:error:other",
>(
type: E,
listener: (data: EventOfType<E>) => void,
): EventSubscriber Removes the specified listener function from the list of functions to call when the given event is observed.
Type Parameters
Parameters
- type: E
The type of event that the listener was listening for.
- listener: (data: EventOfType<E>) => void
The previously registered listener function.
Returns EventSubscriber
- type: E
on
- on<
E extends
| "unknown"
| "connect"
| "disconnect"
| "close"
| "end"
| "accept"
| "accept:error"
| "bind"
| "bind:error"
| "connect:delay"
| "connect:retry"
| "close:error"
| "handshake"
| "handshake:error:protocol"
| "handshake:error:auth"
| "handshake:error:other",
>(
type: E,
listener: (data: EventOfType<E>) => void,
): EventSubscriber Adds a listener function which will be invoked when the given event type is observed. Calling this method will convert the Observer to event emitter mode, which will make it impossible to call Observer.receive() at the same time.
socket.events.on("bind", event => {
console.log(`Socket bound to ${event.address}`)
// ...
}) +Type Parameters
Parameters
- type: E
The type of event to listen for.
- listener: (data: EventOfType<E>) => void
The listener function that will be called with all event data when the event is observed.
Returns EventSubscriber
- type: E
Interface Readable<M>
Describes sockets that can receive messages.
receiveBufferSize: number;
receiveHighWaterMark: number;
receiveTimeout: number;
[asyncIterator](): AsyncIterator<M, undefined, undefined>;
receive(): Promise<M>;
}
Type Parameters
- M extends object[] = Message[]
Hierarchy (view full)
Index
Properties
Methods
Properties
receiveBufferSize
ZMQ_RCVBUF
Underlying kernel receive buffer size in bytes. A value of -1 means leave the OS default unchanged.
receiveHighWaterMark
ZMQ_RCVHWM
The high water mark is a hard limit on the maximum number of incoming messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
receiveTimeout
ZMQ_RCVTIMEO
Sets the timeout receiving messages on the socket. If the value is 0, receive() will return a rejected promise immediately if there is no message to receive. If the value is -1, it will wait asynchronously until a message is available. For all other values, it will wait for a message for that amount of time before rejecting.
Methods
[asyncIterator]
- [async
Iterator] (): AsyncIterator<M, undefined, undefined> Asynchronously iterate over messages becoming available on the socket. When the socket is closed with Socket.close(), the iterator will return. Returning early from the iterator will not close the socket unless it also goes out of scope.
for await (const [msg] of socket) {
// handle messages
} -Returns AsyncIterator<M, undefined, undefined>
receive
- receive(): Promise<M>
Waits for the next single or multipart message to become availeble on the socket. Reads a message immediately if possible. If no messages can be read, it will wait asynchonously. The promise will be resolved with an array containing the parts of the next message when available.
const [msg] = await socket.receive()
const [part1, part2] = await socket.receive() -Reading may fail (eventually) if the socket has been configured with a receiveTimeout.
A call to receive() is guaranteed to return with a resolved promise immediately if a message could be read from the socket directly.
Only one asynchronously blocking call to receive() can be in progress simultaneously. If you call receive() again on the same socket it will return a rejected promise with an
EBUSYerror. For example, if no messages can be read and noawaitis used:socket.receive() // -> pending promise until read is possible
socket.receive() // -> promise rejection with `EBUSY` error -Note: Due to the nature of Node.js and to avoid blocking the main thread, this method always attempts to read messages with the
ZMQ_DONTWAITflag. It polls asynchronously if reading is not currently possible. This means that all functionality related to timeouts and blocking behaviour is reimplemented in the Node.js bindings. Any differences in behaviour with the native ZMQ library is considered a bug.Returns Promise<M>
Resolved with message parts that were successfully read.
Interface Readable<M>
Describes sockets that can receive messages.
receiveBufferSize: number;
receiveHighWaterMark: number;
receiveTimeout: number;
"[asyncIterator]"(): AsyncIterator<M>;
receive(): Promise<M>;
}
Type Parameters
- M extends object[] = Message[]
Hierarchy (View Summary)
Index
Properties
Methods
Properties
receiveBufferSize
ZMQ_RCVBUF
Underlying kernel receive buffer size in bytes. A value of -1 means leave the OS default unchanged.
receiveHighWaterMark
ZMQ_RCVHWM
The high water mark is a hard limit on the maximum number of incoming messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
receiveTimeout
ZMQ_RCVTIMEO
Sets the timeout receiving messages on the socket. If the value is 0, receive() will return a rejected promise immediately if there is no message to receive. If the value is -1, it will wait asynchronously until a message is available. For all other values, it will wait for a message for that amount of time before rejecting.
Methods
[asyncIterator]
- "[asyncIterator]"(): AsyncIterator<M>
Asynchronously iterate over messages becoming available on the socket. When the socket is closed with Socket.close(), the iterator will return. Returning early from the iterator will not close the socket unless it also goes out of scope.
for await (const [msg] of socket) {
// handle messages
} +Returns AsyncIterator<M>
receive
- receive(): Promise<M>
Waits for the next single or multipart message to become availeble on the socket. Reads a message immediately if possible. If no messages can be read, it will wait asynchonously. The promise will be resolved with an array containing the parts of the next message when available.
const [msg] = await socket.receive()
const [part1, part2] = await socket.receive() +Reading may fail (eventually) if the socket has been configured with a receiveTimeout.
A call to receive() is guaranteed to return with a resolved promise immediately if a message could be read from the socket directly.
Only one asynchronously blocking call to receive() can be in progress simultaneously. If you call receive() again on the same socket it will return a rejected promise with an
EBUSYerror. For example, if no messages can be read and noawaitis used:socket.receive() // -> pending promise until read is possible
socket.receive() // -> promise rejection with `EBUSY` error +Note: Due to the nature of Node.js and to avoid blocking the main thread, this method always attempts to read messages with the
ZMQ_DONTWAITflag. It polls asynchronously if reading is not currently possible. This means that all functionality related to timeouts and blocking behaviour is reimplemented in the Node.js bindings. Any differences in behaviour with the native ZMQ library is considered a bug.Returns Promise<M>
Resolved with message parts that were successfully read.
Interface RouterConnectOptions
Index
Properties
Interface RouterConnectOptions
Index
Properties
Interface StreamConnectOptions
Index
Properties
Interface StreamConnectOptions
Index
Properties
Interface Writable<M, O>
Describes sockets that can send messages.
multicastHops: number;
sendBufferSize: number;
sendHighWaterMark: number;
sendTimeout: number;
send(message: M, ...options: O): Promise<void>;
}
Type Parameters
- M extends MessageLike | MessageLike[] = MessageLike | MessageLike[]
- O extends [...object[]] = []
Hierarchy (view full)
Index
Properties
Methods
Properties
multicastHops
ZMQ_MULTICAST_HOPS
Sets the time-to-live field in every multicast packet sent from this socket. The default is 1 which means that the multicast packets don't leave the local network.
sendBufferSize
ZMQ_SNDBUF
Underlying kernel transmit buffer size in bytes. A value of -1 means leave the OS default unchanged.
sendHighWaterMark
ZMQ_SNDHWM
The high water mark is a hard limit on the maximum number of outgoing messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
sendTimeout
ZMQ_SNDTIMEO
Sets the timeout for sending messages on the socket. If the value is 0, send() will return a rejected promise immediately if the message cannot be sent. If the value is -1, it will wait asynchronously until the message is sent. For all other values, it will try to send the message for that amount of time before rejecting.
Methods
send
- send(message, ...options): Promise<void>
Sends a single message or a multipart message on the socket. Queues the message immediately if possible, and returns a resolved promise. If the message cannot be queued because the high water mark has been reached, it will wait asynchronously. The promise will be resolved when the message was queued successfully.
await socket.send("hello world")
await socket.send(["hello", "world"]) -Queueing may fail eventually if the socket has been configured with a sendTimeout.
A call to send() is guaranteed to return with a resolved promise immediately if the message could be queued directly.
Only one asynchronously blocking call to send() may be executed simultaneously. If you call send() again on a socket that is in the mute state it will return a rejected promise with an
EBUSYerror.The reason for disallowing multiple send() calls simultaneously is that it could create an implicit queue of unsendable outgoing messages. This would circumvent the socket's sendHighWaterMark. Such an implementation could even exhaust all system memory and cause the Node.js process to abort.
For most application you should not notice this implementation detail. Only in rare occasions will a call to send() that does not resolve immediately be undesired. Here are some common scenarios:
If you wish to send a message, use
await send(...). ZeroMQ socket types have been carefully designed to give you the correct blocking behaviour on the chosen socket type in almost all cases:If sending is not possible, it is often better to wait than to continue as if nothing happened. For example, on a Request socket, you can only receive a reply once a message has been sent; so waiting until a message could be queued before continuing with the rest of the program (likely to read from the socket) is required.
Certain socket types (such as Router) will always allow queueing messages and
await send(...)won't delay any code that comes after. This makes sense for routers, since typically you don't want a single send operation to stop the handling of other incoming or outgoing messages.
If you wish to send on an occasionally blocking socket (for example on a Router with the Router.mandatory option set, or on a Dealer) and you're 100% certain that dropping a message is better than blocking, then you can set the sendTimeout option to
0to effectively force send() to always resolve immediately. Be prepared to catch exceptions if sending a message is not immediately possible.If you wish to send on a socket and messages should be queued before they are dropped, you should implement a simple queue in JavaScript. Such a queue is not provided by this library because most real world applications need to deal with undeliverable messages in more complex ways - for example, they might need to reply with a status message; or first retry delivery a certain number of times before giving up.
Parameters
Returns Promise<void>
Resolved when the message was successfully queued.
Interface Writable<M, O>
Describes sockets that can send messages.
M extends MessageLike
| MessageLike[] = MessageLike | MessageLike[],
O extends [...object[]] = [],
> {
multicastHops: number;
sendBufferSize: number;
sendHighWaterMark: number;
sendTimeout: number;
send(message: M, ...options: O): Promise<void>;
}
Type Parameters
- M extends MessageLike | MessageLike[] = MessageLike | MessageLike[]
- O extends [...object[]] = []
Hierarchy (View Summary)
Index
Properties
Methods
Properties
multicastHops
ZMQ_MULTICAST_HOPS
Sets the time-to-live field in every multicast packet sent from this socket. The default is 1 which means that the multicast packets don't leave the local network.
sendBufferSize
ZMQ_SNDBUF
Underlying kernel transmit buffer size in bytes. A value of -1 means leave the OS default unchanged.
sendHighWaterMark
ZMQ_SNDHWM
The high water mark is a hard limit on the maximum number of outgoing messages ØMQ shall queue in memory for any single peer that the specified socket is communicating with. A value of zero means no limit.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, ØMQ shall take appropriate action such as blocking or dropping sent messages.
sendTimeout
ZMQ_SNDTIMEO
Sets the timeout for sending messages on the socket. If the value is 0, send() will return a rejected promise immediately if the message cannot be sent. If the value is -1, it will wait asynchronously until the message is sent. For all other values, it will try to send the message for that amount of time before rejecting.
Methods
send
- send(message: M, ...options: O): Promise<void>
Sends a single message or a multipart message on the socket. Queues the message immediately if possible, and returns a resolved promise. If the message cannot be queued because the high water mark has been reached, it will wait asynchronously. The promise will be resolved when the message was queued successfully.
await socket.send("hello world")
await socket.send(["hello", "world"]) +Queueing may fail eventually if the socket has been configured with a sendTimeout.
A call to send() is guaranteed to return with a resolved promise immediately if the message could be queued directly.
Only one asynchronously blocking call to send() may be executed simultaneously. If you call send() again on a socket that is in the mute state it will return a rejected promise with an
EBUSYerror.The reason for disallowing multiple send() calls simultaneously is that it could create an implicit queue of unsendable outgoing messages. This would circumvent the socket's sendHighWaterMark. Such an implementation could even exhaust all system memory and cause the Node.js process to abort.
For most application you should not notice this implementation detail. Only in rare occasions will a call to send() that does not resolve immediately be undesired. Here are some common scenarios:
If you wish to send a message, use
await send(...). ZeroMQ socket types have been carefully designed to give you the correct blocking behaviour on the chosen socket type in almost all cases:If sending is not possible, it is often better to wait than to continue as if nothing happened. For example, on a Request socket, you can only receive a reply once a message has been sent; so waiting until a message could be queued before continuing with the rest of the program (likely to read from the socket) is required.
Certain socket types (such as Router) will always allow queueing messages and
await send(...)won't delay any code that comes after. This makes sense for routers, since typically you don't want a single send operation to stop the handling of other incoming or outgoing messages.
If you wish to send on an occasionally blocking socket (for example on a Router with the Router.mandatory option set, or on a Dealer) and you're 100% certain that dropping a message is better than blocking, then you can set the sendTimeout option to
0to effectively force send() to always resolve immediately. Be prepared to catch exceptions if sending a message is not immediately possible.If you wish to send on a socket and messages should be queued before they are dropped, you should implement a simple queue in JavaScript. Such a queue is not provided by this library because most real world applications need to deal with undeliverable messages in more complex ways - for example, they might need to reply with a status message; or first retry delivery a certain number of times before giving up.
Parameters
Returns Promise<void>
Resolved when the message was successfully queued.
zeromq.js
Index
Classes
Interfaces
Type Aliases
Variables
Functions
zeromq.js
Classes
Variables
Functions
Type Alias Event
| EventFor<"accept", EventAddress>
| EventFor<"accept:error", EventAddress & EventError>
| EventFor<"bind", EventAddress>
| EventFor<"bind:error", EventAddress & EventError>
| EventFor<"connect", EventAddress>
| EventFor<"connect:delay", EventAddress>
| EventFor<"connect:retry", EventAddress & EventInterval>
| EventFor<"close", EventAddress>
| EventFor<"close:error", EventAddress & EventError>
| EventFor<"disconnect", EventAddress>
| EventFor<"end">
| EventFor<"handshake", EventAddress>
| EventFor<"handshake:error:protocol", EventAddress & EventError<ProtoError>>
| EventFor<"handshake:error:auth", EventAddress & EventError<AuthError>>
| EventFor<"handshake:error:other", EventAddress & EventError>
| EventFor<"unknown">
A union type that represents all possible even types and the associated data. Events always have a type property with an EventType value.
The following socket events can be generated. This list may be different depending on the ZeroMQ version that is used.
Note that the error event is avoided by design, since this has a special behaviour in Node.js causing an exception to be thrown if it is unhandled.
Other error names are adjusted to be as close to possible as other networking related event names in Node.js and/or to the corresponding ZeroMQ.js method call. Events (including any errors) that correspond to a specific operation are namespaced with a colon :, e.g. bind:error or connect:retry.
accept - ZMQ_EVENT_ACCEPTED The socket has accepted a connection from a remote peer.
accept:error - ZMQ_EVENT_ACCEPT_FAILED The socket has rejected a connection from a remote peer.
The following additional details will be included with this event:
error- An error object that describes the specific error that occurred.
bind - ZMQ_EVENT_LISTENING The socket was successfully bound to a network interface.
bind:error - ZMQ_EVENT_BIND_FAILED The socket could not bind to a given interface.
The following additional details will be included with this event:
error- An error object that describes the specific error that occurred.
connect - ZMQ_EVENT_CONNECTED The socket has successfully connected to a remote peer.
connect:delay - ZMQ_EVENT_CONNECT_DELAYED A connect request on the socket is pending.
connect:retry - ZMQ_EVENT_CONNECT_RETRIED A connection attempt is being handled by reconnect timer. Note that the reconnect interval is recalculated at each retry.
The following additional details will be included with this event:
interval- The current reconnect interval.
close - ZMQ_EVENT_CLOSED The socket was closed.
close:error - ZMQ_EVENT_CLOSE_FAILED The socket close failed. Note that this event occurs only on IPC transports..
The following additional details will be included with this event:
error- An error object that describes the specific error that occurred.
disconnect - ZMQ_EVENT_DISCONNECTED The socket was disconnected unexpectedly.
handshake - ZMQ_EVENT_HANDSHAKE_SUCCEEDED The ZMTP security mechanism handshake succeeded. NOTE: This event may still be in DRAFT statea and not yet available in stable releases.
handshake:error:protocol - ZMQ_EVENT_HANDSHAKE_FAILED_PROTOCOL The ZMTP security mechanism handshake failed due to some mechanism protocol error, either between the ZMTP mechanism peers, or between the mechanism server and the ZAP handler. This indicates a configuration or implementation error in either peer resp. the ZAP handler. NOTE: This event may still be in DRAFT state and not yet available in stable releases.
handshake:error:auth - ZMQ_EVENT_HANDSHAKE_FAILED_AUTH The ZMTP security mechanism handshake failed due to an authentication failure. NOTE: This event may still be in DRAFT state and not yet available in stable releases.
handshake:error:other - ZMQ_EVENT_HANDSHAKE_FAILED_NO_DETAIL Unspecified error during handshake. NOTE: This event may still be in DRAFT state and not yet available in stable releases.
end - ZMQ_EVENT_MONITOR_STOPPED Monitoring on this socket ended.
unknown An event was generated by ZeroMQ that the Node.js library could not interpret. Please submit a pull request for new event types if they are not yet included.
Type Alias Event
| EventFor<"accept", EventAddress>
| EventFor<"accept:error", EventAddress & EventError>
| EventFor<"bind", EventAddress>
| EventFor<"bind:error", EventAddress & EventError>
| EventFor<"connect", EventAddress>
| EventFor<"connect:delay", EventAddress>
| EventFor<"connect:retry", EventAddress & EventInterval>
| EventFor<"close", EventAddress>
| EventFor<"close:error", EventAddress & EventError>
| EventFor<"disconnect", EventAddress>
| EventFor<"end">
| EventFor<"handshake", EventAddress>
| EventFor<
"handshake:error:protocol",
EventAddress & EventError<ProtoError>,
>
| EventFor<"handshake:error:auth", EventAddress & EventError<AuthError>>
| EventFor<"handshake:error:other", EventAddress & EventError>
| EventFor<"unknown">
A union type that represents all possible even types and the associated data. Events always have a type property with an EventType value.
The following socket events can be generated. This list may be different depending on the ZeroMQ version that is used.
Note that the error event is avoided by design, since this has a special behaviour in Node.js causing an exception to be thrown if it is unhandled.
Other error names are adjusted to be as close to possible as other networking related event names in Node.js and/or to the corresponding ZeroMQ.js method call. Events (including any errors) that correspond to a specific operation are namespaced with a colon :, e.g. bind:error or connect:retry.
accept - ZMQ_EVENT_ACCEPTED The socket has accepted a connection from a remote peer.
accept:error - ZMQ_EVENT_ACCEPT_FAILED The socket has rejected a connection from a remote peer.
The following additional details will be included with this event:
error- An error object that describes the specific error that occurred.
bind - ZMQ_EVENT_LISTENING The socket was successfully bound to a network interface.
bind:error - ZMQ_EVENT_BIND_FAILED The socket could not bind to a given interface.
The following additional details will be included with this event:
error- An error object that describes the specific error that occurred.
connect - ZMQ_EVENT_CONNECTED The socket has successfully connected to a remote peer.
connect:delay - ZMQ_EVENT_CONNECT_DELAYED A connect request on the socket is pending.
connect:retry - ZMQ_EVENT_CONNECT_RETRIED A connection attempt is being handled by reconnect timer. Note that the reconnect interval is recalculated at each retry.
The following additional details will be included with this event:
interval- The current reconnect interval.
close - ZMQ_EVENT_CLOSED The socket was closed.
close:error - ZMQ_EVENT_CLOSE_FAILED The socket close failed. Note that this event occurs only on IPC transports..
The following additional details will be included with this event:
error- An error object that describes the specific error that occurred.
disconnect - ZMQ_EVENT_DISCONNECTED The socket was disconnected unexpectedly.
handshake - ZMQ_EVENT_HANDSHAKE_SUCCEEDED The ZMTP security mechanism handshake succeeded. NOTE: This event may still be in DRAFT statea and not yet available in stable releases.
handshake:error:protocol - ZMQ_EVENT_HANDSHAKE_FAILED_PROTOCOL The ZMTP security mechanism handshake failed due to some mechanism protocol error, either between the ZMTP mechanism peers, or between the mechanism server and the ZAP handler. This indicates a configuration or implementation error in either peer resp. the ZAP handler. NOTE: This event may still be in DRAFT state and not yet available in stable releases.
handshake:error:auth - ZMQ_EVENT_HANDSHAKE_FAILED_AUTH The ZMTP security mechanism handshake failed due to an authentication failure. NOTE: This event may still be in DRAFT state and not yet available in stable releases.
handshake:error:other - ZMQ_EVENT_HANDSHAKE_FAILED_NO_DETAIL Unspecified error during handshake. NOTE: This event may still be in DRAFT state and not yet available in stable releases.
end - ZMQ_EVENT_MONITOR_STOPPED Monitoring on this socket ended.
unknown An event was generated by ZeroMQ that the Node.js library could not interpret. Please submit a pull request for new event types if they are not yet included.
Type Alias Message
A type representing the messages that are returned inside promises by Readable.receive().
Type Alias Message
A type representing the messages that are returned inside promises by Readable.receive().
Type Alias MessageLike
| ArrayBufferView
| ArrayBuffer
| SharedArrayBuffer
| string
| null
Union type representing all message types that are accepted by Writable.send().
Type Alias MessageLike
| ArrayBufferView
| ArrayBuffer
| SharedArrayBuffer
| string
| number
| null
Union type representing all message types that are accepted by Writable.send().
Type Alias SocketOptions<S>
Represents the options that can be assigned in the constructor of a given socket type, for example new Dealer({...}). Readonly options for the particular socket will be omitted.
Type Parameters
- S extends Socket
Type Alias SocketOptions<S>
Represents the options that can be assigned in the constructor of a given socket type, for example new Dealer({...}). Readonly options for the particular socket will be omitted.
Type Parameters
- S extends Socket
Variable capabilityConst
curve: boolean;
draft: boolean;
gssapi: boolean;
ipc: boolean;
norm: boolean;
pgm: boolean;
tipc: boolean;
}>
Exposes some of the optionally available ØMQ capabilities, which may depend on the library version and platform.
This is an object with keys corresponding to supported ØMQ features and transport protocols. Available capabilities will be set to true. Unavailable capabilities will be absent or set to false.
Possible keys include:
ipc- Support for theipc://protocol.pgm- Support for thepgm://protocol.tipc- Support for thetipc://protocol.norm- Support for thenorm://protocol.curve- Support for the CURVE security mechanism.gssapi- Support for the GSSAPI security mechanism.draft- Wether the library is built with support for DRAFT sockets.
Variable capabilityConst
{
curve: boolean;
draft: boolean;
gssapi: boolean;
ipc: boolean;
norm: boolean;
pgm: boolean;
tipc: boolean;
},
>
Exposes some of the optionally available ØMQ capabilities, which may depend on the library version and platform.
This is an object with keys corresponding to supported ØMQ features and transport protocols. Available capabilities will be set to true. Unavailable capabilities will be absent or set to false.
Possible keys include:
ipc- Support for theipc://protocol.pgm- Support for thepgm://protocol.tipc- Support for thetipc://protocol.norm- Support for thenorm://protocol.curve- Support for the CURVE security mechanism.gssapi- Support for the GSSAPI security mechanism.draft- Wether the library is built with support for DRAFT sockets.
Variable versionConst
The version of the ØMQ library the bindings were built with. Formatted as (major).(minor).(patch). For example: "4.3.2".
Variable versionConst
The version of the ØMQ library the bindings were built with. Formatted as (major).(minor).(patch). For example: "4.3.2".
A ØMQ context. Contexts manage the background I/O to send and receive messages of their associated sockets.
It is usually not necessary to instantiate a new context - the global context is used for new sockets by default. The global context is the only context that is shared between threads (when using worker_threads). Custom contexts can only be used in the same thread.
Note: By default all contexts (including the global context) will prevent the process from terminating if there are any messages in an outgoing queue, even if the associated socket was closed. For some applications this is unnecessary or unwanted. Consider setting Context.blocky to
falseor setting Socket.linger for each new socket.