nanomsg/deps/nanomsg/rfc/sp-ipc-mapping-01.txt

Node bindings for nanomsg

Internet Engineering Task Force                          G. D'Amore, Ed.
Internet-Draft
Intended status: Informational                                M. Sustrik
Expires: October 14, 2016
                                                          April 12, 2016


                 IPC Mapping for Scalability Protocols
                           sp-ipc-mapping-01

Abstract

   This document defines the IPC mapping for scalability protocols.  It
   deals with how IPC (inter-process communication) should be
   implemented on POSIX-compliant platforms.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at http://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on October 14, 2016.

Copyright Notice

   Copyright (c) 2016 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (http://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.




D'Amore & Sustrik       Expires October 14, 2016                [Page 1]

Internet-Draft             IPC mapping for SPs                April 2016


1.  Underlying protocol

   This mapping should be layered directly on the top of AF_UNIX sockets
   of type SOCK_STREAM.  On the platforms where AF_UNIX sockets are not
   available IPC mapping may be done in a platform-specific way and
   SHOULD be described in a separate RFC.

   There's no fixed file to use for SP communication.  Instead,
   filenames are assigned to individual services by the user.

2.  Connection initiation

   Before binding the AF_UNIX socket the implementation SHOULD check
   whether there's another process bound to the address.  If not so it
   SHOULD try to delete the associated file, if present.  This measure
   will prevent subsequent bind from failing if there's a leftover file
   from the previous runs of the application.

   The check can be performed in a platform-specific way, however, a
   generic way to implement it is to try to connect to the address and
   close the connection immediately if successful.

   After establishing underlying AF_UNIX connection, both parties MUST
   send the protocol header immediately.  Both endpoints MUST then wait
   for the protocol header from the peer before proceeding on.

   The protocol header is 8 bytes long and looks like this:

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |      0x00     |      0x53     |      0x50     |    version    |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |             type              |           reserved            |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   First four bytes of the protocol header are used to make sure that
   the peer's protocol is compatible with the protocol used by the local
   endpoint.

   First four bytes of the protocol header MUST be set to 0x00, 0x53,
   0x50 and 0x00 respectively.  If the protocol header received from the
   peer differs, the TCP connection MUST be closed immediately.

   The fact that the first byte of the protocol header is binary zero
   eliminates any text-based protocols that were accidentally connected
   to the endpoint.  Subsequent two bytes make the check even more
   rigorous.  At the same time they can be used as a debugging hint to



D'Amore & Sustrik       Expires October 14, 2016                [Page 2]

Internet-Draft             IPC mapping for SPs                April 2016


   indicate that the connection is supposed to use one of the
   scalability protocols -- ASCII representation of these bytes is 'SP'.
   Finally, the fourth byte rules out any incompatible versions of this
   protocol.

   Fifth and sixth bytes of the header form a 16-bit unsigned integer in
   network byte order representing the type of SP endpoint on the layer
   above.  The value SHOULD NOT be interpreted by the mapping, rather
   the interpretation should be delegated to the scalability protocol
   above the mapping.  For informational purposes, it should be noted
   that the field encodes information such as SP protocol ID, protocol
   version and the role of endpoint within the protocol.  Individual
   values are assigned by IANA.

   Finally, the last two bytes of the protocol header are reserved for
   future use and must be set to binary zeroes.  If the protocol header
   from the peer contains anything else than zeroes in this field, the
   implementation MUST close the underlying TCP connection.

3.  Message header

   Once the protocol header is accepted, endpoint can send and receive
   messages.  Every message starts with a message header consisting of
   of a single byte called 'message type'.

   The only value of this field that is currently allowed is 0x1, which
   means "in-band" message, i.e. message whose body is passed as a
   stream of bytes via the AF_UNIX socket.

   The intent of this field is to eventually allow out-of-band transfer
   of the message bodies, e.g. via shared memory.

   The in-band message type MUST be implemented.

4.  In-band messages

   For in-band messages, message header is immediately followed by
   64-bit unsigned integer in network byte order representing the
   payload size, in bytes.  Thus, the message payload can be from 0 to
   2^64-1 bytes long.  The payload of the specified size follows
   directly after the size field:

   +-----------+------------+-----------------+
   | type (8b) | size (64b) |     payload     |
   +-----------+------------+-----------------+






D'Amore & Sustrik       Expires October 14, 2016                [Page 3]

Internet-Draft             IPC mapping for SPs                April 2016


5.  IANA Considerations

   This memo includes no request to IANA.

6.  Security Considerations

   The mapping isn't intended to provide any additional security in
   addition to what AF_UNIX does.

Authors' Addresses

   Garrett D'Amore (editor)

   Email: garrett@damore.org


   Martin Sustrik

   Email: sustrik@250bpm.com
































D'Amore & Sustrik       Expires October 14, 2016                [Page 4]