Raw Socket API

Table of Contents

• 1. Introduction
• 2. Conformance
• 3. Terminology
• 4. Security and privacy considerations
• 5. Interface UDPSocket
  • 5.1 Attributes
  • 5.2 Methods
  • 5.3 Event handlers
• 6. Interface TCPSocket
  • 6.1 Attributes
  • 6.2 Methods
  • 6.3 Event handlers
• 7. Interface TCPServerSocket
  • 7.1 Attributes
  • 7.2 Methods
  • 7.3 Event handlers
• 8. Interface UDPMessageEvent
  • 8.1 Attributes
• 9. Interface ConnectEvent
  • 9.1 Attributes
• 10. Interface ErrorEvent
  • 10.1 Attributes
• 11. Dictionary UDPOptions
  • 11.1 Dictionary UDPOptions Members
• 12. Dictionary TCPOptions
  • 12.1 Dictionary TCPOptions Members
• 13. Dictionary TCPServerOptions
  • 13.1 Dictionary TCPServerOptions Members
• 14. Enums
  • 14.1 ReadyState
• A. Acknowledgements
• B. References
  • B.1 Normative references

2. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this specification are to be interpreted as described in [RFC2119].

This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.

Implementations that use ECMAScript to implement the APIs defined in this specification MUST implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [WEBIDL], as this specification uses that specification and terminology.

3. Terminology

The EventHandler interface represents a callback used for event handlers as defined in [HTML5].

The concepts queue a task and fire a simple event are defined in [HTML5].

The terms event handler and event handler event types are defined in [HTML5].

4. Security and privacy considerations

This API must be only exposed to trusted content.

5. Interface UDPSocket

The UDPSocket interface defines attributes and methods for UDP communication

// 
// This example shows a simple implementation of UPnP-SSDP M-SEARCH discovery 
// using a multicast UDPSocket 
//

// Create a UDP socket
var mySocket = new UDPSocket (); 

// Build an SSDP M-SEARCH multicast message
var MSearch = "M-SEARCH * HTTP/1.1\r\n" +
"ST: " + ServiceType + "\r\n" +
"MAN: \"ssdp:discover\"\r\n" +
"HOST: 239.255.255.250:1900\r\n" +
"MX: 10\r\n\r\n";

var SSDPMulticastAddress = "239.255.255.250";
var SSDPMulticastPort = 1900;

// Join multicast group
mySocket.joinMulticastGroup (SSDPMulticastAddress);

try {
  // Send SSDP M-SEARCH multicast message
  var moreBufferingOK = mySocket.send(MSearch, SSDPMulticastAddress, 
                                      SSDPMulticastPort);
  console.log('M-SEARCH Sent!'); 
}        
catch(err) {  
  // Sending failed      
  console.error('Sending M-SEARCH failed: ' + err.name);
}       

// Receive M-SEARCH responses          
mysocket.onmessage = function (udpMessageEvent) { 
  // Convert received data from ArrayBuffer to string
  var data = arrayBufferToString (udpMessageEvent.data);    
  console.log("Remote address: " + udpMessageEvent.remoteAddress + 
              " Remote port: " + udpMessageEvent.remotePort +  
              " Received data" + data);
};       

// 
// This example shows a a simple implementation of reception of UPnP-SSDP 
// NOTIFY multicast messages 
//

var SSDPMulticastAddress = "239.255.255.250";
var SSDPMulticastPort = 1900;           

// Create a UDP socket and bind it to the IP-address of the default 
// local interface and to the SSDP local port
var mySocket = new UDPSocket ({"localPort":SSDPMulticastPort});   

// Join multicast group
mySocket.joinMulticastGroup (SSDPMulticastAddress);         

// Receive SSDP NOTFIY         
mysocket.onmessage = function (UDPMessageEvent) { 
  // Convert received data from ArrayBuffer to string
  var data = arrayBufferToString (UDPMessageEvent.data);    
  console.log("Remote address: " + UDPMessageEvent.remoteAddress + 
              " Remote port: " + UDPMessageEvent.remotePort +  
              " Received data" + data);
};  

[Constructor (optional UDPOptions options)]
interface UDPSocket : EventTarget {
    readonly    attribute DOMString       localAddress;
    readonly    attribute unsigned short  localPort;
    readonly    attribute DOMString?      remoteAddress;
    readonly    attribute unsigned short? remotePort;
    readonly    attribute boolean         addressReuse;
    readonly    attribute boolean         loopback;
    readonly    attribute unsigned long   bufferedAmount;
    readonly    attribute ReadyState      readyState;;
                attribute EventHandler    ondrain;
                attribute EventHandler    onerror;
                attribute EventHandler    onmessage;
    void    close ();
    void    suspend ();
    void    resume ();
    void    joinMulticastGroup (DOMString multicastGroupAddress);
    void    leaveMulticastGroup (DOMString multicastGroupAddress);
    boolean send ((DOMString or Blob or ArrayBuffer or ArrayBufferView) data, optional DOMString? remoteAddress, optional unsigned short? remotePort);
};

When the UDPSocket constructor is invoked, the User Agent MUST run the following steps:

1. If the options.localAddress argument is absent then bind the socket to the IPv4/6 address of the default local interface. Otherwise, if the requested local address is free or if it is in use and the options.addressReuse attribute is true or absent then bind the socket to the IPv4/6 address of the requested local interface. Else, throw an InvalidAccessError exception and abort these steps.
2. If the options.localPort argument is absent bind then the socket to any available local port. Otherwise, if the requested local port is free or if it is in use and the options.addressReuse attribute is true or absent then bind the socket to the requested local port. Else, throw an InvalidAccessError exception and abort these steps.
3. If the options.remoteAddress field is present then set the default remote address attribute of the socket to the requested address.
4. If the options.remotePort field is present then set the default remote port attribute to the requested port.
5. Create a new UDPSocket object and if the constructor's options argument is present set the corresponding attributes to the values of the fields that are present in the options argument, else set the corresponding attributes to the default values.
6. Set the readyState attribute to "open".
7. Set the bufferedAmount attribute to 0.
8. Return the newly created UDPSocket object to the application.

The send method when invoked MUST run the following steps:

1. If readyState is "closed" throw DOMException InvalidStateError and abort these steps.
2. If the type of the data is not compatible any expected type, DOMString, Blob, ArraYBuffer or ArrayBufferView, then throw DOMException InvalidAccessError and abort these steps.
3. If no default remote address and port was specified in the UDPSocket's constructor options.remoteAddress and options.remotePort arguments and the send method arguments remoteAddress and remotePort are not present or null then throw DOMException InvalidAccessError and abort these steps.
4. If the data cannot be sent, e.g. because it would need to be buffered but the buffer is full or because the data is too long to pass atomically through the underlying protocol, the user agent MUST:
   1. Create a new instance of ErrorEvent.
   2. Set the error.name attribute of the ErrorEvent object to "NetworkError".
   3. queue a task to fire an event named error with the newly created ErrorEvent instance at the UDPSocket object.
   4. Close the UDP socket and set the readyState attribute to "closed".
   5. Abort these steps.
5. Make a request to the system to send UDP data with data passed in the data parameter. If the send method arguments remoteAddress and remotePort are present use these as destination, else use the default address and port of the recipient as stated by the UDPSocket object constructor's options.remoteAddress and options.remotePort fields.
6. When the request has been completed set the return value of the method to true or false as a hint to the caller that they may either continue sending more data immediately, or should want to wait until the transport layer has transmitted buffered data that already have been written to the socket before buffering more. When less than an implementation specific value has been buffered and it's safe to immediately write more set the return value to true. When more than an implementation specific value has been buffered set the return value to false. This means that the caller should wait before buffering more data by more calls to send until the ondrain event handler has been called.
7. Any invocation of this method that does not throw an exception must increase the bufferedAmount attribute.
   • If the send data argument is DOMString the bufferedAmount attribute is increased by the number of bytes needed to express the argument as UTF-8. [UNICODE] [UTF-8]
   • If the send data argument is Blob the bufferedAmount attribute is increased by the size of the Blob object's raw data, in bytes. [FILE-API]
   • If the send data argument is ArrayBuffer the bufferedAmount attribute is increased by the length of the ArrayBuffer in bytes. [TYPED-ARRAYS]
   • If the send data argument is ArrayBufferView the bufferedAmount attribute is increased by the length of the ArrayBufferView in bytes. [TYPED-ARRAYS]

The close method when invoked MUST run the following steps:

1. Close the socket, meaning that it can not be used to send and receive data any more, and set the readyState attribute to "closed".

Upon a new UDP datagram being received, the user agent MUST run the following steps:

1. If it is not possible to convert the received UDP data to ArrayBuffer, [TYPED-ARRAYS], then:
   1. Create a new instance of ErrorEvent.
   2. Set the error.name attribute of the ErrorEvent object to "NetworkError".
   3. queue a task to fire an event named error with the newly created ErrorEvent instance at the UDPSocket object.
   4. Abort these steps.
2. Create a new instance of UDPMessageEvent.
3. Initialize the UDPMessageEvent object's data attribute to a new read-only ArrayBuffer object whose contents are the received UDP data [TYPED-ARRAYS].
4. Set the remoteAddress attribute of the UDPMessageEvent object to the source address of the received UDP datagram.
5. Set the remotePort attribute of the UDPMessageEvent object to the source port of the received UDP datagram.
6. queue a task to fire an event named message with the newly created UDPMessageEvent instance at the UDPSocket object.

In the process of sending UDP data, upon a detection that previously-buffered data has been written to the network and it is possible to buffer more data received from the application, the user agent MUST:

1. queue a task to fire an event named drain at the UDPSocket object.

6. Interface TCPSocket

The TCPSocket interface defines attributes and methods for TCP communication

// 
 // This example shows a simple TCP echo client. 
 // The client will send "Hello World" to the server on port 6789 and log 
 // what has been received from the server.
 //        
 try {
 
   //  Create a new TCP client socket and connect to remote host
   var mySocket = new TCPSocket ("127.0.0.1", 6789);  
   mySocket.onopen = function() {                    
     try {
       // Send data to server
       var moreBufferingOK = mySocket.send("Hello World");
       console.log('Data sent to server!'); 
       
       // Receive response from server
       mySocket.onmessage = function (messageEvent) {
         // Convert received data from ArrayBuffer to string
         var data = arrayBufferToString (messageEvent.data);  
         console.log('Data received from server: ' + data);
         
         // Close the connection
         mySocket.close();                               
       }
       
     }        
     catch(err) {  
       // Sending failed      
       console.error('Sending failed: ' + err.name);
     }                     
   }  
   
   // Connection has been closed 
   mySocket.onclose = function {
     console.log('Connection has been closed');
   }  
   
   // Handle errors
   mySocket.onerror = function(err) {
     console.error('Error: ' + err.name);
   }             
   
 }        
   catch(err) {  
   
   // Handle runtime exception    
   console.error('Could not create a TCP socket: ' + err.name);
 }     

[Constructor (DOMString remoteAddress, unsigned short remotePort, 
                 optional TCPOptions options)]
interface TCPSocket : EventTarget {
    readonly    attribute DOMString      remoteAddress;
    readonly    attribute DOMString      remotePort;
    readonly    attribute DOMString      localAddress;
    readonly    attribute unsigned short localPort;
    readonly    attribute unsigned long  bufferedAmount;
    readonly    attribute ReadyState     readyState;;
                attribute EventHandler   ondrain;
                attribute EventHandler   onopen;
                attribute EventHandler   onclose;
                attribute EventHandler   onhalfclose;
                attribute EventHandler   onerror;
                attribute EventHandler   onmessage;
    void    close ();
    void    halfclose ();
    void    suspend ();
    void    resume ();
    boolean send ((DOMString or Blob or ArrayBuffer or ArrayBufferView) data);
};

When the TCPSocket constructor is invoked, the User Agent MUST run the following steps:

1. If the remoteAddress argument is not a valid IPv4/6 address or the remotePort argument is not a valid port number then throw an InvalidAccessError exception and abort these steps, else set the remoteAddress and remotePort attributes to the requested values.
2. If the options.localAddress argument is absent bind the socket to the IPv4/6 address of the default local interface. Otherwise, if the requested local address is free then bind the socket to the IPv4/6 address of the requested local interface. Else, throw an InvalidAccessError exception and abort these steps.
3. If the options.localPort argument is absent bind then the socket to any available local port. Otherwise, if the requested local port is free bind the socket to the requested local port. Else, throw an InvalidAccessError exception and abort these steps.
4. Set the localAddress and localPort attributes to the selected values according to above.
5. Set the readyState attribute to "connecting".
6. Set the bufferedAmount attribute to 0.
7. Attempt to connect to the requested address and port in the background (without blocking scripts).
8. Return the newly created TCPSocket object to the application.

The send method when invoked MUST run the following steps:

1. If readyState is not "open" throw DOMException InvalidStateError and abort these steps.
2. If the type of the data is not compatible any expected type, DOMString, Blob, ArraYBuffer or ArrayBufferView, then throw DOMException InvalidAccessError and abort these steps.
3. If the data cannot be sent, e.g. because it would need to be buffered but the buffer is full or because the data is too long to pass atomically through the underlying protocol, the user agent MUST:
   1. Change the readyState attribute's value to "closed".
   2. Create a new instance of ErrorEvent.
   3. Set the error.name attribute of the ErrorEvent object to "NetworkError".
   4. queue a task to fire an event named error with the newly created ErrorEvent instance at the TCPSocket object.
   5. queue a task to fire an event named close at the TCPSocket object.
   6. Abort these steps.
4. Make a request to the system to send TCP data with data passed in the data parameter to the address and port of the recipient as stated by the TCPSocket object constructor's remoteAddress and remotePort fields.
5. When the requests has been completed set the return value of the method to true or false as a hint to the caller that they may either continue sending more data immediately, or should want to wait until the transport layer has transmitted buffered data that already have been written to the socket before buffering more. When less than an implementation specific value has been buffered and it's safe to immediately write more set the return value to true. When more than an implementation specific value has been buffered set the return value to false. This means that the caller should wait before buffering more data by more calls to send until the ondrain event handler has been called.
6. Any invocation of this method that does not throw an exception must increase the bufferedAmount attribute.
   • If the send data argument is DOMString the bufferedAmount attribute is increased by the number of bytes needed to express the argument as UTF-8. [UNICODE] [UTF-8]
   • If the send data argument is Blob the bufferedAmount attribute is increased by the size of the Blob object's raw data, in bytes. [FILE-API]
   • If the send data argument is ArrayBuffer the bufferedAmount attribute is increased by the length of the ArrayBuffer in bytes. [TYPED-ARRAYS]
   • If the send data argument is ArrayBufferView the bufferedAmount attribute is increased by the length of the ArrayBufferView in bytes. [TYPED-ARRAYS]

The close method when invoked MUST run the following steps:

1. If readyState is "closing" or "closed" then do nothing.
2. If readyState is "connecting" then fail the connection attempt and set the readyState attribute to "closing".
3. If readyState is "open" close the connection and set the readyState attribute to "closing".

The halfclose method when invoked MUST run the following steps:

1. If readyState is "closing" or "closed" then do nothing.
2. If readyState is "connecting" then complete the connection attempt. If succesful send FIN and set the readyState attribute to "halfclosed".
3. If readyState is "open" then send FIN and set the readyState attribute to "halfclosed".

When a new TCP connection has been successfully established the user agent MUST run the following steps:

1. Change the readyState attribute's value to "open".
2. queue a task to fire an event named open at the TCPSocket object.

When the attempt to establish a new TCP connection (readyState is "connecting") has failed the user agent MUST run the following steps:

1. Change the readyState attribute's value to "closed".
2. Create a new instance of ErrorEvent.
3. Set the error.name attribute of the ErrorEvent object to "NetworkError".
4. queue a task to fire an event named error with the newly created ErrorEvent instance at the TCPSocket object.

When an established TCP connection (readyState is "open") is lost the user agent MUST run the following steps:

1. Change the readyState attribute's value to "closed".
2. Create a new instance of ErrorEvent.
3. Set the error.name attribute of the ErrorEvent object to "NetworkError".
4. queue a task to fire an event named error with the newly created ErrorEvent instance at the TCPSocket object.
5. queue a task to fire an event named close at the TCPSocket object.

Upon a new TCP message being received, the user agent MUST run the following steps:

1. If it is not possible to convert the received TCP data to ArrayBuffer, [TYPED-ARRAYS], then:
   1. Create a new instance of ErrorEvent.
   2. Set the error.name attribute of the ErrorEvent object to "NetworkError".
   3. queue a task to fire an event named error with the newly created ErrorEvent instance at the UDPSocket object.
   4. Abort these steps.
2. Create a new instance of MessageEvent, [POSTMSG].
3. Initialize the MessageEvent object's data attribute to a new read-only ArrayBuffer object whose contents are the received TCP data [TYPED-ARRAYS].
4. queue a task to fire an event named message with the newly created MessageEvent instance at the TCPSocket object.

Note: It is up to the implementation the define how often the message event will be issued and how much data that will be delivered to the application with each MessageEvent instance.

In the process of sending TCP data, upon a detection that previously-buffered data has been written to the network and it is possible to buffer more data received from the application, the user agent MUST:

1. queue a task to fire an event named drain at the TCPSocket object.

When a TCP connection has been closed cleanly, either by the server, or by the client calling close() the user agent MUST run the following steps:

1. Set the readyState attribute's value to "closed".
2. queue a task to fire an event named close at the TCPSocket object.

7. Interface TCPServerSocket

The TCPServerSocket interface supports TCP server sockets that listens to connection attempts from TCP clients

// 
// This example shows a simple TCP echo server. 
// The server will listen on port 6789 and respond back with what ever 
// has been sent to the server.
//        
try {
  //  Create a new server socket that listens on port 6789
  var myServerSocket = new TCPServerSocket ({"localPort":6789});
  
  myServerSocket.onconnect = function (connectEvent) { 
    var connectedSocket = connectEvent.connectedSocket;
    // Read the data
    connectedSocket.onmessage = function (messageEvent) {
       var data = messageEvent.data;               
       try {
         // Send data back to client
         var moreBufferingOK = connectedSocket.send(data);
         console.log('Response sent to client!'); 
       }        
         catch(err) {  
         // Sending failed      
         console.error('Sending failed: ' + err.name);
       }                                                            
    }  
    
    // Connection has been closed 
    connectedSocket.onclose = function {
      console.log('Connection has been closed');
    }        
  
  }
}        
catch(err) {  
  // Handle runtime exception    
  console.error('Could not create a TCP server socket: ' + err.name);
}      

[Constructor (optional TCPServerOptions options)]
interface TCPServerSocket : EventTarget {
    readonly    attribute DOMString      localAddress;
    readonly    attribute unsigned short localPort;
    readonly    attribute ReadyState     readyState;;
                attribute EventHandler   onconnect;
                attribute EventHandler   onerror;
    void close ();
    void suspend ();
    void resume ();
};

When the TCPServerSocket constructor is invoked, the User Agent MUST run the following steps:

1. If any input argument is invalid throw an InvalidAccessError exception and abort these steps.
2. If the options.localAddress argument is absent then listen to the IPv4/6 address of the default local interface. Otherwise, if the requested local address is free then listen to the IPv4/6 address of the requested local interface. Else, throw an InvalidAccessError exception and abort these steps.
3. If the options.localPort argument is absent then bind the socket to any available local port. Otherwise, if the requested local port is free then bind the socket to the requested local port. Else, throw an InvalidAccessError exception and abort these steps.
4. Create a new TCPServerSocket object and set the localAddress and localPort attributes to selected values accoring to above.
5. Set the readyState attribute to "open".
6. Start listening for for connections on the specified port and address.
7. Return the newly created TCPServerSocket object to the application.

The close method when invoked MUST run the following steps:

1. If a TCP connection setup is in progress the connection setup is finalized according to the descriptions below.
2. Stop listening to further connection attempts from clients.
3. Set the readyState attribute to "closed".

Upon a new successful connection to the TCP server socket the user agent MUST run the following steps:

1. Create a new instance of ConnectEvent.
2. Let socket be a new instance of TCPSocket.
3. set the remoteAddress attribute of socket to the IPv4/6 address of the peer.
4. set the remotePort attribute of socket to the source port of the of the peer.
5. set the localAddress attribute of socket to the used local IPv4/6 address.
6. set the localPort attribute of socket to the used local source port.
7. set the readyState attribute of socket to "open".
8. set the bufferedAmount attribute of socket to 0.
9. set the connectedSocket attribute of the ConnectEvent object to socket.
10. queue a task to fire an event named connect with the newly created ConnectEvent instance at the TCPServerSocket object.

Upon a new connection attempt to the TCP server socket that can not be served, e.g. due to max number of open connections, the user agent MUST run the following steps:

1. Create a new instance of ErrorEvent.
2. Set the error.name attribute of the ErrorEvent object to "NetworkError".
3. queue a task to fire an event named error with the newly created ErrorEvent instance at the TCPServerSocket object.

8. Interface UDPMessageEvent

The UDPMessageEvent interface represents events related to received UDP data. This interface extends the MessageEvent interface, [POSTMSG]

The event's data attribute is intialized to a new read-only ArrayBuffer object whose contents are the recieved UDP data, [TYPED-ARRAYS]

[NoInterfaceObject]
interface UDPMessageEvent : MessageEvent {
    readonly    attribute DOMString      remoteAddress;
    readonly    attribute unsigned short remotePort;
};

9. Interface ConnectEvent

The ConnectEvent interface represents events related to accepted connections to a TCP server socket.

[NoInterfaceObject]
interface ConnectEvent : Event {
    readonly    attribute TCPSocket connectedSocket;
};

10. Interface ErrorEvent

The ErrorEvent interface represents events related to TCP connection errors.

[NoInterfaceObject]
interface ErrorEvent : Event {
    readonly    attribute DOMError error;
};

11. Dictionary UDPOptions

States the options for the UDPSocket. An instance of this dictionary can optionally be used in the constructor of the UDPSocket object, where all fields are optional.

dictionary UDPOptions {
    DOMString      localAddress;
    unsigned short localPort;
    DOMString      remoteAddress;
    unsigned short remotePort;
    boolean        addressReuse;
    boolean        loopback;
};

12. Dictionary TCPOptions

States the options for the TCPSocket. An instance of this dictionary can optionally be used in the constructor of the TCPSocket object, where all fields are optional.

dictionary TCPOptions {
    DOMString      localAddress;
    unsigned short localPort;
    boolean        useSecureTransport;
};

13. Dictionary TCPServerOptions

States the options for the TCPServerSocket. An instance of this dictionary can optionally be used in the constructor of the TCPServerSocket object, where all fields are optional.

dictionary TCPServerOptions {
    DOMString      localAddress;
    unsigned short localPort;
    boolean        useSecureTransport;
};

14. Enums

enum ReadyState {
    "connecting",
    "open",
    "closing",
    "closed",
    "halfclosed"
};