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)

Constructors

constructor

Properties

affinity backlog closed connectTimeout context curvePublicKey curveSecretKey curveServer curveServerKey events gssapiPlainText gssapiPrincipal gssapiPrincipalNameType gssapiServer gssapiServicePrincipal gssapiServicePrincipalNameType handshakeInterval heartbeatInterval heartbeatTimeout heartbeatTimeToLive immediate interface ipv6 lastEndpoint linger loopbackFastPath maxMessageSize multicastMaxTransportDataUnit plainPassword plainServer plainUsername rate readable reconnectInterval reconnectMaxInterval recoveryInterval securityMechanism socksProxy tcpAcceptFilter tcpKeepalive tcpKeepaliveCount tcpKeepaliveIdle tcpKeepaliveInterval tcpMaxRetransmitTimeout threadSafe type typeOfService vmciBufferMaxSize vmciBufferMinSize vmciBufferSize vmciConnectTimeout writable zapDomain zapEnforceDomain

Methods

bind close connect disconnect getBoolOption getInt32Option getInt64Option getStringOption getUint32Option getUint64Option setBoolOption setInt32Option setInt64Option setStringOption setUint32Option setUint64Option unbind

Constructors

Protectedconstructor

  • new Socket(type, options?): Socket

  • Creates a new socket of the specified type. Subclasses are expected to provide the correct socket type.

    Parameters

    • type: SocketType

      The socket type.

    • Optionaloptions: {}

      Any options to set during construction.

      Returns Socket

    Properties

    affinity

    affinity: number

    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

    backlog: number

    ZMQ_BACKLOG

    Maximum length of the queue of outstanding peer connections for the specified socket. This only applies to connection-oriented transports.

    Readonlyclosed

    closed: boolean

    Whether this socket was previously closed with close().

    connectTimeout

    connectTimeout: number

    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: Context

    Context that this socket belongs to.

    curvePublicKey

    curvePublicKey: null | string

    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

    curveSecretKey: null | string

    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

    curveServer: boolean

    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

    curveServerKey: null | string

    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

    events: Observer

    Event Observer for this socket. This starts up a ØMQ monitoring socket internally that receives all socket events.

    gssapiPlainText

    gssapiPlainText: boolean

    gssapiPrincipal

    gssapiPrincipal: null | string

    gssapiPrincipalNameType

    gssapiPrincipalNameType: "hostBased" | "userName" | "krb5Principal"

    gssapiServer

    gssapiServer: boolean

    gssapiServicePrincipal

    gssapiServicePrincipal: null | string

    gssapiServicePrincipalNameType

    gssapiServicePrincipalNameType: "hostBased" | "userName" | "krb5Principal"

    handshakeInterval

    handshakeInterval: number

    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

    heartbeatInterval: number

    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

    heartbeatTimeout: number

    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

    heartbeatTimeToLive: number

    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

    immediate: boolean

    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

    interface: null | string

    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

    ipv6: boolean

    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

    lastEndpoint: null | string

    ZMQ_LAST_ENDPOINT

    The last endpoint bound for TCP and IPC transports.

    linger

    linger: number

    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

    loopbackFastPath: boolean

    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.

    Windows

    maxMessageSize

    maxMessageSize: number

    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

    multicastMaxTransportDataUnit: number

    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

    plainPassword: null | string

    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

    plainServer: boolean

    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

    plainUsername: null | string

    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

    rate: number

    ZMQ_RATE

    Maximum send or receive data rate for multicast transports such as pgm.

    Readonlyreadable

    readable: boolean

    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

    reconnectInterval: number

    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

    reconnectMaxInterval: number

    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

    recoveryInterval: number

    ZMQ_RECOVERY_IVL

    Maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.

    ReadonlysecurityMechanism

    securityMechanism:
        | 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

    socksProxy: null | string

    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

    tcpAcceptFilter: null | string

    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

    tcpKeepalive: number

    ZMQ_TCP_KEEPALIVE

    Override SO_KEEPALIVE socket option (if supported by OS). The default value of -1 leaves it to the OS default.

    tcpKeepaliveCount

    tcpKeepaliveCount: number

    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

    tcpKeepaliveIdle: number

    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

    tcpKeepaliveInterval: number

    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

    tcpMaxRetransmitTimeout: number

    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

    threadSafe: boolean

    ZMQ_THREAD_SAFE

    Whether or not the socket is threadsafe. Currently only DRAFT sockets is thread-safe.

    Readonlytype

    type: SocketType

    ZMQ_TYPE

    Retrieve the socket type. This is fairly useless because you can test the socket class with e.g. socket instanceof Dealer.

    typeOfService

    typeOfService: number

    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

    vmciBufferMaxSize: number

    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

    vmciBufferMinSize: number

    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

    vmciBufferSize: number

    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

    vmciConnectTimeout: number

    ZMQ_VMCI_CONNECT_TIMEOUT

    Connection timeout for the socket. For vmci:// transports only.

    Readonlywritable

    writable: boolean

    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

    zapDomain: null | string

    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

    zapEnforceDomain: boolean

    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.

    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): void

    • Connects to the socket at the given remote address and returns immediately. The connection will be made asynchronously in the background.

      socket.connect("tcp://127.0.0.1:3456")

      Parameters

      • address: string

        The address to connect to.

      Returns void

    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

    ProtectedgetBoolOption

    • getBoolOption(option): boolean

    • Parameters

      • option: number

      Returns boolean

    ProtectedgetInt32Option

    • getInt32Option(option): number

    • Parameters

      • option: number

      Returns number

    ProtectedgetInt64Option

    • getInt64Option(option): number

    • Parameters

      • option: number

      Returns number

    ProtectedgetStringOption

    • getStringOption(option): null | string

    • Parameters

      • option: number

      Returns null | string

    ProtectedgetUint32Option

    • getUint32Option(option): number

    • Parameters

      • option: number

      Returns number

    ProtectedgetUint64Option

    • getUint64Option(option): number

    • Parameters

      • option: number

      Returns number

    ProtectedsetBoolOption

    • setBoolOption(option, value): void

    • Parameters

      • option: number
      • value: boolean

      Returns void

    ProtectedsetInt32Option

    • setInt32Option(option, value): void

    • Parameters

      • option: number
      • value: number

      Returns void

    ProtectedsetInt64Option

    • setInt64Option(option, value): void

    • Parameters

      • option: number
      • value: number

      Returns void

    ProtectedsetStringOption

    • setStringOption(option, value): void

    • Parameters

      • option: number
      • value: null | string | Buffer

      Returns void

    ProtectedsetUint32Option

    • setUint32Option(option, value): void

    • Parameters

      • option: number
      • value: number

      Returns void

    ProtectedsetUint64Option

    • setUint64Option(option, value): void

    • Parameters

      • option: number
      • value: number

      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.

    Settings

    Member Visibility

    On This Page

    Constructors
    Properties
    Methods