International    Virtual    Observatory Alliance

SAMP - Simple Application Messaging Protocol

Abstract

Status of this Document

Contents

1  Introduction

1.1  Non-Technical Preamble and Position in IVOA Architecture

Figure 1: IVOA Architecture diagram [1]. The SAMP protocol appears in the "Using" region.

1.2  History

1.3  Requirements and Scope

1.4  Types of Messaging

Publish/Subscribe Messaging:

A publish/subscribe (pub/sub) messaging system supports an event driven model where information producers and consumers participate in message passing. SAMP applications "publish" a message, while consumer applications "subscribe" to messages of interest and consume events. The underlying messaging system routes messages from producers to consumers based on the message types in which an application has registered an interest.

Point-to-Point Messaging:

In point to point messaging systems, messages are routed to an individual consumer which maintains a queue of "incoming" messages. In a traditional message queue, applications send messages to a specified queue and clients retrieve them. In SAMP, the message system manages the delivery and routing of messages, but also permits the concept of a directed message meant for delivery to a specific application. SAMP does not, however, guarantee the order of message delivery as with a traditional message queue.

Event-based Messaging:

Event-based systems are systems in which producers generate events, and in which messaging middleware delivers events to consumers based upon a previously specified interest. One typical usage pattern of these systems is the publish/subscribe paradigm, however these systems are also widely used for integrating loosely coupled application components. SAMP allows for the concept that an "event" occurred in the system and that these message types may have requirements different from messages where the sender is trying to invoke some action in the network of applications.

Synchronous vs. Asynchronous Messaging:

As the term is used in this document, a "synchronous" message is one which blocks the sending application from further processing until a reply is received. However, SAMP messaging is based on "asynchronous" message and response in that the delivery of a message and its subsequent response are handled as separate activities by the underlying system. With the exception of the synchronous message pattern supported by the system, sending or replying to a message using SAMP allows an application to return to other processing while the details of the delivery are handled separately.

1.5  About this Document

2  Architectural Overview

2.1  Nomenclature

Hub:

A broker service for routing SAMP Messages.

Client:

An application that talks to a Hub using SAMP. May be a Sender, Recipient, or both.

Sender:

A Client that sends a SAMP Message to one or more Recipients via the Hub.

Recipient:

A Client that receives a SAMP Message from the Hub. This may have originated from another Client or be from the Hub itself.

Message:

A communication sent from a Sender to a Recipient via a SAMP Hub. Contains an MType and zero or more named parameters. May or may not provoke a Response.

Response:

A communication which may be returned from a Recipient to a Sender in reply to a previous Message. A Response may contain returned values and/or error information. In the terminology of this document, a Response is not itself a Message. A Response is also known as a Reply in this document.

MType:

A string defining the semantics of a Message and of its arguments and return values (if any). Every Message contains exactly one MType, and a Message is only delivered to Clients subscribed to that MType.

Subscription:

A Client is said to be Subscribed to a given MType if it has declared to the Hub that it is prepared to receive Messages with that MType.

Callable Client:

A Client to which the Hub is capable of performing callbacks. Clients are not obliged to be Callable, but only Callable Clients are able to receive Messages or asynchronous Responses.

Broadcast:

To send a SAMP Message to all Subscribed Clients excluding the Sender.

Profile:

A set of rules which map the abstract API defined by SAMP to a set of I/O operations which may be used by Clients to send and receive actual Messages.

2.2  Messaging Topology

Figure 2: The SAMP hub architecture

2.3  The Lifecycle of a Client

1. Determine whether a hub is running by using the appropriate hub discovery mechanism.
2. If so, use the hub discovery mechanism to work out how to communicate with the hub.
3. Register with the hub.
4. Store metadata such as client name, description and icon in the hub.
5. Subscribe to a list of MTypes to define messages which may be received.
6. Interrogate the hub for metadata of other clients.
7. Send and/or receive messages to/from other clients via the hub.
8. Unregister with the hub.

2.4  The Lifecycle of a Hub

1. Locate any existing hub by using the appropriate hub discovery mechanism.
   1. Check whether the existing hub is alive.
   2. If so, exit.
2. If no hub is running, or a hub is found but is not functioning, write/overwrite the hub discovery record and start up.
3. Await client registrations. When a client makes a legal registration, assign it a public ID, and add the application to the table of registered clients under the public ID. Broadcast a message announcing the registration of a new client.
4. When a client stores metadata in the hub, broadcast a message announcing the change and make the metadata available.
5. When a client updates its list of subscribed MTypes, broadcast a message announcing the change and make the subscription information available
6. When the hub receives a message for relaying, pass it on to appropriate recipients which are subscribed to the message's MType. Broadcast messages are sent to all subscribed clients except the sender, messages with a specified recipient are sent to that recipient if it is subscribed.
7. Await client unregistrations. When a client unregisters, broadcast a message announcing the unregistration and remove the client from the table of registered clients.
8. If the hub is unable to communicate with a client, it may unregister it as described in phase 7.
9. When the hub is about to shutdown, broadcast a message to all subscribed clients.
10. Delete the hub discovery record.

2.5  Message Delivery Patterns

1. Notification
2. Asynchronous Call/Response
3. Synchronous Call/Response

2.6  Extensible Vocabularies

2.7  Use of Profiles

1. By describing exactly what bytes are to be sent using what wire protocols for each SAMP interface operation
2. By providing one or more language-specific libraries with calls which correspond to those of the SAMP interface

3  Abstract APIs and Data Types

3.1  Hub Discovery Mechanism

3.2  Communicating with the Hub

3.3  SAMP Data Types

1. string - a scalar value consisting of a sequence of characters; each character is an ASCII character with hex code 09, 0a, 0d or 20-7f
2. list - an ordered array of data items
3. map - an unordered associative array of key-value pairs, in which each key is a string and each value is a data item

3.4  Scalar Type Encoding Conventions

  <digit>        ::= "0" | "1" | "2" | "3" | "4" | "5" | "6"
                   | "7" | "8" | "9"
  <digits>       ::= <digit> | <digits> <digit>
  <float-digits> ::= <digits> | <digits> "." | "." <digits>
                   | <digits> "." <digits>
  <sign>         ::= "+" | "-"

• <SAMP int> ::= [ <sign> ] <digits>
  An integer value is encoded using its decimal representation with an OPTIONAL preceding sign and with no leading, trailing or embedded whitespace. There is no guarantee about the largest or smallest values which can be represented, since this will depend on the processing environment at decode time.
  
• <SAMP float> ::= [ <sign> ] <float-digits>
                   [ "e" | "E" [ <sign> ] <digits> ]
  A floating point value is encoded as a mantissa with an OPTIONAL preceding sign followed by an OPTIONAL exponent part introduced with the character "e" or "E". There is no guarantee about the largest or smallest values which can be represented or about the number of digits of precision which are significant, since these will depend on the processing environment at decode time.
  
• <SAMP boolean> ::= "0" | "1"
  A boolean value is represented as an integer: zero represents false, and any other value represents true. 1 is the RECOMMENDED value to represent true.

3.5  Registering with the Hub

1. establish communication with the hub
2. advertise its presence to the hub and to other clients
3. obtain registration information

samp.hub-id

- The client ID which is used by the hub when it sends messages itself (rather than forwarding them from other senders). For instance, this ID will be used when the hub sends the samp.hub.event.shutdown message.

samp.self-id

- The client ID which identifies the registering client.

• supply the hub with metadata about itself, using the declareMetadata() call
• tell the hub how it wishes the hub to communicate with it, if at all (the mechanism for this is profile-dependent, and it may be implicit in registration)
• inform the hub which MTypes it wishes to subscribe to, using the declareSubscriptions() call

3.6  Application Metadata

samp.name

- A one word title for the application.

samp.description.text

- A short description of the application, in plain text.

samp.description.html

- A description of the application, in HTML.

samp.icon.url

- The URL of an icon in png, gif or jpeg format.

samp.documentation.url

- The URL of a documentation web page.

3.7  MType Subscriptions

  <mchar>  ::= [0-9a-z] | "-" | "_"
  <atom>   ::= <mchar> | <atom> <mchar>
  <mtype>  ::= <atom> | <mtype> "." <atom>

  <msub>   ::= "*" | <mtype> "." "*"

3.8  Message Encoding

samp.mtype

- A string giving the MType which defines the meaning of the message. The MType also, via external documentation, defines the names, types and meanings of any parameters and return values. MTypes are discussed in more detail in Section 6.

samp.params

- A map containing the values for the message's named parameters. These give the data required for the receiver to act on the message, for instance the URL of a given file. The names, types and semantics of these parameters are determined by the MType. Each key in this map is the name of a parameter, and the corresponding value is that parameter's value.

3.9  Response Encoding

samp.status

(REQUIRED) - A string summarising the result of the processing. It may take one of the following defined values:

samp.ok:

Processing successful. The samp.result, but not the samp.error entry SHOULD be present.

samp.warning:

Processing partially successful. Both samp.result and samp.error entries SHOULD be present.

samp.error:

Processing failed. The samp.error, but not the samp.result entry SHOULD be present.

These values form the basis of an extensible vocabulary as explained in Section 2.6.

samp.result

(REQUIRED in case of full or partial success) - A map containing the values for the message's named return values. The names, types and semantics of these returns are determined by the MType. Each key in this map is the name of a return value, and the corresponding value is the actual value. Note that even for MTypes which define no return values, the value of this entry MUST still be a map (typically an empty one).

samp.error

(REQUIRED in case of full or partial error) - A map containing error information. The following keys are defined for this map:

samp.errortxt

(REQUIRED) - A short string describing what went wrong. This will typically be delivered to the user of the sender application.

samp.usertxt

(OPTIONAL) - A free-form string containing any additional text an application wishes to return. This may be a more verbose error description meant to be appended to the samp.errortxt string, however it is undefined how this string should be handled when received.

samp.debugtxt

(OPTIONAL) - A longer string which may contain more detail on what went wrong. This is typically intended for debugging purposes, and may for instance be a stack trace.

samp.code

(OPTIONAL) - A string containing a numeric or textual code identifying the error, perhaps intended to be parsable by software.

These keys form the basis of an extensible vocabulary as explained in Section 2.6.

3.10  Sending and Receiving Messages

Notification:

In the notification pattern, communication is only in one direction:

1. The sender sends a message to the hub for delivery to one or more recipients.
2. The hub forwards the message to those requested recipients which are subscribed.
3. No reply from the recipients is expected or possible.

Notifications can be sent to a given recipient or broadcast to all recipients. The notification pattern for a single recipient is illustrated in Figure 3. Figure 3: Notification pattern

Asynchronous Call/Response:

In the asynchronous call pattern, message tags and message identifiers are used to tie together messages and their replies:

1. The sender sends a message to the hub for delivery to one or more recipients, supplying along with the message a tag string of its own choice, msg-tag . In return it receives a unique identifier string, msg-id .
2. The hub forwards the message to the appropriate recipients, supplying along with the message an identifier string, msg-id .
3. Each recipient processes the message, and sends its response back to the hub along with the ID string msg-id .
4. Using a callback, the hub passes the response back to the original sender along with the ID string msg-tag .

The sender is free to use any value for the msg-tag . There is no requirement on the form of the hub-generated msg-id (it is not intended to be parsed by the recipient), but it MUST be sufficient for the hub to pair messages with their responses reliably, and to pass the correct msg-tag back with the response to the sender¹. In most cases the sender will not require the msg-id , since the msg-tag is sufficient to match calls with responses. For this reason, the sender need not retain the msg-id and indeed need not wait for it, avoiding a hub round trip at send time. The only case in which the sender may require the msg-id is if it needs to communicate later with the recipient about the message that was sent, for instance as part of a progress report. Asynchronous calls may be sent to a given recipient or broadcast to all recipients. In the latter case, the sender SHOULD be prepared to deal with multiple responses to the same call. The asynchronous pattern is illustrated in Figure 4. Figure 4: Asynchronous Call/Response pattern

Synchronous Call/Response

A synchronous utility method is provided by the hub, mainly for the convenience of environments where dealing with asynchronicity might be a problem. The hub will provide synchronous behaviour to the sender, interacting with the receiver in exactly the same way as for the asynchronous case above.

1. The sender sends a message to the hub for delivery to a given recipient, optionally specifying as well a maximum time it is prepared to wait. The sender's call blocks until a response is available.
2. The hub forwards the message to the recipient, supplying along with the message an ID string, msg-id .
3. The recipient processes the message, and sends its response back to the hub along with the ID string msg-id .
4. The hub passes back the response as the return value from the original blocking call made by the sender. If no response is received within the sender's specified timeout the blocking call will terminate with an error. The hub is not guaranteed to wait indefinitely; it MAY in effect impose its own timeout.

There is no broadcast counterpart for the synchronous call. This pattern is illustrated in Figure 5. Figure 5: Synchronous Call/Response pattern

3.11  Operations a Hub Must Support

• map reg-info = register()
  Method called by a client wishing to register with the hub. The form of reg-info is given in Section 3.5. Note that the form of this call may vary according to the requirements of the particular Profile in use. For instance authentication tokens may be passed in one or both directions to complete registration.
  
• unregister()
  Method called by a client wishing to unregister from the hub
  
• declareMetadata(map metadata)
  Method called by a client to declare its metadata. May be called zero or more times to update hub state; the most recent call is the one which defines the client's currently declared metadata. The form of the metadata map is given in Section 3.6.
  
• map metadata = getMetadata(string client-id)
  Returns the metadata information for the client whose public ID is client-id. The form of the metadata map is given in Section 3.6.
  
• declareSubscriptions(map subscriptions)
  Method called by a callable client to declare the MTypes it wishes to subscribe to. May be called zero or more times to update hub state; the most recent call is the one which defines the client's currently subscribed MTypes. The form of the subscriptions map is given in Section 3.7.
  
• map subscriptions = getSubscriptions(string client-id)
  Returns the subscribed MTypes for the client whose public ID is client-id. The form of the subscriptions map is given in Section 3.7.
  
• list client-ids = getRegisteredClients()
  Returns the list of public ids of all other registered clients. The caller's ID (samp.self-id from Section 3.5) is not included, but the hub's ID (samp.hub-id from Section 3.5) is.
  
• map client-subs = getSubscribedClients(string mtype)
  Returns a map with an entry for all other registered clients which are subscribed to the MType mtype. The key for each entry is a subscribed client ID, and the value is a (possibly empty) map providing further information on its subscription to mtype as described in Section 3.7. An entry for the caller is not included, even if it is subscribed. mtype MUST NOT include wildcards.
  
• notify(string recipient-id, map message)
  Sends a message using the Notification pattern to a given recipient. The form of the message map is given in Section 3.8. An error results if the recipient is not subscribed to the message's MType.
  
• list recipient-ids = notifyAll(map message)
  Sends a message using the Notification pattern to all other clients which are subscribed to the message's MType. The form of the message map is given in Section 3.8. The return value is a list of the client IDs of the clients to which an attempt to send the message is made.
  
• string msg-id = call(string recipient-id, string msg-tag,
                       map message)
  Sends a message using the Asynchronous Call/Response pattern to a given recipient. The form of the message map is given in Section 3.8. An error results if the recipient is not subscribed to the message's MType, or if the invoking client is not Callable.
  
• map calls = callAll(string msg-tag, map message)
  Sends a message using the Asynchronous Call/Response pattern to all other clients which are subscribed to the message's MType. The form of the message map is given in Section 3.8. The returned value is a map in which the keys are the client IDs of clients to which an attempt to send the message is made, and the values are the associated msg-id strings. An error results if the invoking client is not Callable.
  
• map response = callAndWait(string recipient-id,
                             map message, string timeout)
  Sends a message using the Synchronous Call/Response pattern to a given recipient. The forms of the message and response maps are given in Sections 3.8 and 3.9. The timeout parameter is interpreted as a SAMP int (Section 3.4) giving the maximum number of seconds the client wishes to wait. If the response takes longer than that to arrive this method SHOULD terminate anyway with an error (it MUST not return a response indicating error). Any response arriving from the recipient after that will be discarded. If timeout < =0 then no artificial timeout is imposed. An error results if the recipient is not subscribed to the message's MType.
  
• reply(string msg-id, map response)
  Method called by a client to send its response to a given message. The form of the response map is given in Section 3.9.

3.12  Operations a Callable Client Must Support

• receiveNotification(string sender-id, map message)
  Method called by the hub when dispatching a notification to its recipient. The form of the message map is given in Section 3.8.
  
• receiveCall(string sender-id, string msg-id, map message)
  Method called by the hub when dispatching a call to its recipient. The client MUST at some later time make a matching call to reply() on the hub. The form of the message map is given in Section 3.8.
  
• receiveResponse(string responder-id, string msg-tag,
                  map response)
  Method used by the hub to dispatch to the sender the response of an earlier asynchronous call. The form of the response map is given in Section 3.9.

3.13  Error Processing

4  Standard Profile

4.1  Data Type Mappings

4.2  API Mappings

1. The XML-RPC method names (i.e. the contents of the XML-RPC <methodName> elements) are formed by prefixing the hub and client abstract API operation names with "samp.hub." or "samp.client." respectively.
2. The register() operation takes the following form:
   • map reg-info = register(string samp-secret)
   The argument is the samp-secret value read from the lockfile (see Section 4.3). The returned reg-info map contains an additional entry with key samp.private-key whose value is a string generated by the hub.
3. All other hub and client methods take the private-key as their first argument.
4. A new method, setXmlrpcCallback() is added to the hub API.
   • setXmlrpcCallback(string private-key, string url)
   This informs the hub of the XML-RPC endpoint on which the client is listening for calls from the hub. The client is not considered Callable unless and until it has invoked this method.
5. Another new method, ping() is added to the hub API. This may be called by registered or unregistered applications (as a special case the private-key argument may be omitted), and can be used to determine whether the hub is responding to requests. Any non-error return indicates that the hub is running.

4.3  Lockfile and Hub Discovery

1. Determine where to find the lockfile (4.3.1)
2. Read the lockfile to obtain the hub connection parameters (4.3.2)

4.3.1  Lockfile Location

   <samphub-value>  ::=  <hub-location>
   <hub-location>   ::=  <stdlock-prefix> <stdlock-url>
   <lockurl-prefix> ::=  "std-lockurl:"
   <stdlock-url>    ::=  (any URL)

   SAMP_HUB=std-lockurl:file:///tmp/samp1

4.3.2  Lockfile Content

   <file>          ::=   <lines>
   <lines>         ::=   <line> | <lines> <line>
   <line>          ::=   <line-content> <EOL> | <EOL>
   <line-content>  ::=   <comment> | <assignment>
   <comment>       ::=   "#" <any-string>
   <assignment>    ::=   <name> "=" <any-string>
   <name>          ::=   <token-string>
   <token-string>  ::=   <token-char> | <token-string> <token-char>
   <any-string>    ::=   <any-char> | <any-string> <any-char>
   <EOL>           ::=   "\r" | "\n" | "\r" "\n"
   <token-char>    ::=   [a-zA-Z0-9] | "-" | "_" | "."
   <any-char>      ::=   [\x20-\x7f]

samp.secret

- An opaque text string which must be passed to the hub to permit registration.

samp.hub.xmlrpc.url

- The XML-RPC endpoint for communication with the hub.

samp.profile.version

- The version of the SAMP Standard Profile implemented by the hub ("1.3" for the version described by this document).

# SAMP lockfile written 2008-29-02T17:45:01
# Required keys:
samp.secret=734144fdaab8400a1ec2
samp.hub.xmlrpc.url=http://andromeda.star.bris.ac.uk:8001/xmlrpc
samp.profile.version=1.3
# Info stored by hub for some private reason:
com.yoyodyne.hubid=c80995f1

4.3.3  Hub Discovery Sequences

• Client startup:
  • Determine hub existence as above
  • If no hub, client MAY start its own hub
  • Acquire samp.secret value from lockfile
  • If pre-existing or own hub is running, call register() and zero or more of setXmlrpcCallback(), declareMetadata(), declareSubscriptions()
• Hub startup:
  • Determine hub existence as above
  • If hub is running, exit
  • Otherwise, start up XML-RPC server
  • Write lockfile with mandatory assignments including XML-RPC endpoint
• Hub shutdown:
  • Remove lockfile (it is RECOMMENDED to first check that this is the lockfile written by self)
  • Notify candidate clients that shutdown will occur
  • Shut down services

4.4  Examples

   # Locate and read the lockfile.
   string hubvar-value = readEnvironmentVariable("SAMP_HUB");
   string lock-location = getLockfileLocation(hubvar-value);
   map lock-info = readLockfile(lock-location);

   # Extract information from lockfile to locate and register with hub.
   string hub-url = lock-info.getValue("samp.hub.xmlprc.url");
   string samp-secret = lock-info.getValue("samp.secret");

   # Establish XML-RPC connection with hub
   # (uses some generic XML-RPC library)
   xmlrpcServer hub = xmlrpcConnect(hub-url);

   # Register with hub.
   map reg-info = hub.xmlrpcCall("samp.hub.register", samp-secret);
   string private-key = reg-info.getValue("samp.private-key");

   # Store metadata in hub for use by other applications.
   map metadata = ("samp.name" -> "dummy",
                   "samp.description.text" -> "Test Application",
                   "dummy.version" -> "0.1-3");
   hub.xmlrpcCall("samp.hub.declareMetadata", private-key, metadata);

   # Send a message requesting file load to all other 
   # registered clients, not wanting any response.
   map loadParams = ("filename" -> "/tmp/foo.bar");
   map loadMsg = ("samp.mtype" -> "file.load",
                  "samp.params" -> loadParams);
   hub.xmlrpcCall("samp.hub.notifyAll", private-key, loadMsg);

   # Unregister
   hub.xmlrpcCall("samp.hub.unregister", private-key);

   POST /xmlrpc HTTP/1.0
   User-Agent: Java/1.5.0_10
   Content-Type: text/xml
   Content-Length: 189

   <?xml version="1.0"?>
   <methodCall>
     <methodName>samp.hub.register</methodName>
     <params>
       <param><value><string>734144fdaab8400a1ec2</string></value></param>
     </params>
   </methodCall>

   HTTP/1.1 200 OK
   Connection: close
   Content-Type: text/xml
   Content-Length: 464

   <?xml version="1.0"?>
   <methodResponse>
     <params><param><value><struct>
       <member>
         <name>samp.private-key</name>
         <value><string>client-key:1a52fdf</string></value>
       </member>
       <member>
         <name>samp.hub-id</name>
         <value><string>client-id:0</string></value>
       </member>
       <member>
         <name>samp.self-id</name>
         <value><string>client-id:4</string></value>
       </member>
     </struct></value></param></params>
   </methodResponse>

   POST /xmlrpc HTTP/1.0
   User-Agent: Java/1.5.0_10
   Content-Type: text/xml
   Content-Length: 600

   <?xml version="1.0"?>
   <methodCall>
     <methodName>samp.hub.declareMetadata</methodName>
     <params>
       <param><value><string>app-id:1a52fdf-2</string></value></param>
       <param><value><struct>
         <member>
           <name>samp.name</name>
           <value><string>dummy</string></value>
         </member>
         <member>
           <name>samp.description.text</name>
           <value><string>Test application</string></value>
         </member>
         <member>
           <name>dummy.version</name>
           <value><string>0.1-3</string></value>
         </member>
       </struct></value></param>
     </params>
   </methodCall>

   POST /xmlrpc HTTP/1.0
   User-Agent: Java/1.5.0_10
   Content-Type: text/xml
   Content-Length: 523

   <?xml version="1.0"?>
   <methodCall>
     <methodName>samp.hub.notifyAll</methodName>
     <params>
       <param><value><string>app-id:1a52fdf-2</string></value></param>
       <param><value><struct>
         <member>
           <name>samp.mtype</name>
           <value>file.load</value>
         </member>
         <member>
           <name>samp.params</name>
           <value><struct>
             <name>filename</name>
             <value>/tmp/foo.bar</value>
           </struct></value>
         </member>
       </struct></value></param>
     </params>
   </methodCall>

5  Web Profile

5.1  Overview and Comparison with Standard Profile

5.1.1  Hub Discovery

5.1.2  Outward Communications

5.1.3  Inward Communications

5.1.4  Third-Party URLs

5.2  Hub Behaviour

5.2.1  Data Type Mappings

5.2.2  API Mappings

1. The XML-RPC method names (i.e. the contents of the XML-RPC <methodName> elements) are formed by prefixing the hub abstract API operation names with "samp.webhub.". For brevity, this prefix is not written in the rest of this document, but it is to be understood on all hub API XML-RPC calls.
2. The register() operation takes the following form:
   • map reg-info = register(string app-name)
   The app-name is a short string supplied by the registering application to indicate its identity. This SHOULD be presented by the hub to the user when the user's consent is requested for registration.
3. The reg-info map returned from the register method MUST contain two entries additional to those mandated by the hub API:

   samp.private-key:

   used as the first argument of all hub API XML-RPC calls

   samp.url-translator:

   used for translation of foreign URLs for cross-origin accessibility
4. All hub methods other than register take the private-key as their first argument, except where otherwise noted (ping). For brevity, this argument is not written in the rest of this document, but it is to be understood on all hub API calls.
5. Two new methods are added to the hub API to support reversed callbacks (Section 5.2.5):
   • void allowReverseCallbacks(string allow)
   • map pullCallbacks(string timeout)
6. Another new method is added to the hub API:
   • void ping()
   This may be called by registered or unregistered applications (as a special case the private-key argument may be omitted), and can be used to determine whether the hub is responding to requests. Any non-error return indicates that the hub is running.

5.2.3  Hub HTTP Server

Cross-Origin Resource Sharing:

CORS [11] is a W3C standard which works by manipulation of the HTTP Origin header and related headers by the browser runtime environment and the HTTP server allowing the HTTP server to grant cross-domain access from clients with some or all Origins. CORS forms part of the XmlHttpRequest Level 2 standard [12], which is implemented by Chrome v2.0+, Firefox v3.5+ and Safari v4.0+. Microsoft's IE8+ implements CORS via its own non-standard XDomainRequest object. This standard belongs to the loose HTML5 family of technologies, and it is likely that support will become wider in the future. A Web Profile hub HTTP server can grant unrestricted access to CORS-aware web applications by following the instructions in the CORS standard to enable both simple and preflight requests from clients with any Origin.

Flash cross-domain policy:

Adobe's Flash browser plugin makes use of a resource named "crossdomain.xml", which, if present on an external HTTP server, is taken to indicate willingness to serve cross-domain requests [13]. This has emerged as something of a de facto standard, and the crossdomain file is honoured by Silverlight and unsigned Java Applets/WebStart applications for Java v1.6.0_10 and later (Java bug report #6676256). A Web Profile hub HTTP server can grant unrestricted access to to Flash-like web applications by serving a resource named "/crossdomain.xml" with a Content-Type header of "text/x-cross-domain-policy" and content like:

   <?xml version="1.0"?>
   <!DOCTYPE cross-domain-policy
             SYSTEM "http://www.adobe.com/xml/dtds/cross-domain-policy.dtd">
   <cross-domain-policy>
     <site-control permitted-cross-domain-policies="all"/>
     <allow-access-from domain="*"/>
     <allow-http-request-headers-from domain="*" headers="*"/>
   </cross-domain-policy>

Silverlight cross-domain policy:

Microsoft's Silverlight environment will take note of Flash-style crossdomain.xml files, so the above measure ought to permit Silverlight clients to access a compliant HTTP server. However, Silverlight has its own cross-domain policy mechanism, [14] so it may be implemented in addition. A Web Profile hub HTTP server can grant unrestricted access to Silverlight web applications by serving a resource named "/clientaccesspolicy.xml" with a Content-Type header of "text/xml" and content like:

   <?xml version="1.0"?>
   <access-policy>
     <cross-domain-access>
       <policy>
         <allow-from>
           <domain uri="http://*"/>
         </allow-from>
         <grant-to>
           <resource path="/" include-subpaths="true"/>
         </grant-to>
       </policy>
     </cross-domain-access>
   </access-policy>

5.2.4  Registration

   map register(string appName)

samp.private-key:

The value of this key is a string which identifies the registered client. This string SHOULD be difficult for third parties to guess. This arrangement is the same as for the Standard Profile (Section 4.2)

samp.url-translator:

The value of this key is a string which forms the base for a URL proxying service, used as described in Section 5.2.6

5.2.5  Callable Clients

• void allowReverseCallbacks(string allow)
• list pullCallbacks(string timeout-secs)

samp.methodName

- The client API method name for the callback. Its value is a string taking one of the values "receiveNotification", "receiveCall" or "receiveResponse".

samp.params

- A list of the parameters taken by the client API method in question, as documented in Section 3.12.

POST /
Host: localhost:21012
User-Agent: Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.9.2.11)
 Gecko/20101028 Red Hat/3.6-2.el5 Firefox/3.6.11
Referer: http://www.star.bris.ac.uk/~mbt/websamp/sample.html
Content-Length: 284
Content-Type: text/plain; charset=UTF-8
Origin: http://www.star.bris.ac.uk

<?xml version='1.0'?>
<methodCall>
  <methodName>samp.webhub.pullCallbacks</methodName>
  <params>
    <param>
      <value><string>wk:1_fjlyrdtwtigfqhnwkqokqpbq</string></value>
    </param>
    <param>
      <value><string>600</string></value>
    </param>
  </params>
</methodCall>

200 OK
Content-Length: 1444
Content-Type: text/xml
Access-Control-Allow-Origin: http://www.star.bris.ac.uk

<?xml version='1.0' encoding='UTF-8'?>
<methodResponse>
  <params>
    <param>
      <value>
        <array>
          <data>
            <value>
              <struct>
                <member>
                  <name>samp.methodName</name>
                  <value>samp.webclient.receiveCall</value>
                </member>
                <member>
                  <name>samp.params</name>
                  <value>
                    <array>
                      <data>
                        <value>hub</value>
                        <value>hub_A_cc55_Ping-tag</value>
                        <value>
                          <struct>
                            <member>
                              <name>samp.mtype</name>
                              <value>samp.app.ping</value>
                            </member>
                            <member>
                              <name>samp.params</name>
                              <value>
                                <struct>
                                </struct>
                              </value>
                            </member>
                          </struct>
                        </value>
                      </data>
                    </array>
                  </value>
                </member>
              </struct>
            </value>
          </data>
        </array>
      </value>
    </param>
  </params>
</methodResponse>

5.2.6  URL Translation

   var url_trans = reg_info["samp.url-translator"];
   var u1 = msg["samp.params"]["url"];   // base URL received from message
   var u2 = url_trans + u1;              // URL ready for retrieval

http://localhost:21012/translator/client-private-key ?

5.3  Client Behaviour

1. Prepare to make XML-RPC communications with the XML-RPC endpoint http://localhost:21012/. Web applications will need to do this using a client which supports one of the cross-origin workarounds described in Section 5.2.3 and supported by the Web Profile hub.
2. Call the register XML-RPC method with a short application name as the sole argument. If this succeeds (returns a non-Fault XML-RPC response), the client is registered.
3. If the client wishes to receive as well as send communications (to be Callable ), first call allowReverseCallbacks and then periodically call pullCallbacks. Call declareSubscriptions as required.
4. Act on retrieved callbacks as required. If any MType argument or return value is a URL, prefix it with the value of the samp.url-translator entry from the registration map before dereferencing it.
5. Send SAMP messages etc as required.
6. Unregister when no further SAMP activity is required, either because the user requests disconnection or on page unload or a similar event.

5.4  Security Mechanisms

1. Restrict to local host:

only registration requests originating from the local host should be permitted

2. Require user confirmation:

registration should only be permitted if explicitly authorised on a per-request basis by the user

3. Attempt client authentication:

under some circumstances it may be possible to perform authentication of the owner of the server from which the web application has been downloaded; such an authenticated identity can be used to decide whether registration will be accepted

5.4.1  Local Host Restriction

5.4.2  User Confirmation

Name:

as declared by the application as part of the registration call. This provides no security, since the application can call itself anything at all, including something misleading This is always present.

Origin:

the location of the web server from which the web application was downloaded [18]. If the web application has contacted the server using the CORS cross-origin workaround, this value will be present and reliable (the application cannot lie about it). However, if one of the other cross-origin workarounds (Flash or Silverlight) is in use, this value will be absent (or perhaps even even be present but forged in some versions of those platforms, needs investigation).

5.4.3  Client Authentication

• If the Origin's protocol is https, then the Hub can authenticate the server by making an HTTPS request to any resource on the same server, for instance a HEAD request to the server root. This reliably acquires a certificate associated with the server. This mechanism requires that the web application be served from an HTTPS server, but no additional client implementation effort. It may or may not be easy to implement for a Hub depending on language/library support for HTTPS/TLS.
• The application may present a signed message for which the signed text is the Origin. The certificate contained in such a signature would be reliably associated with the origin, hence the server. This could be done by the application presenting at registration time (using an adjustment to the register() method) the static URL of an appropriate XML digital signature document constructed as per [17]. This mechanism could, with suitable tool support, be made easy for the client even in absence of an HTTPS server, It may or may not be easy to implement for a Hub depending on language/library support for the relevant digital signature standard.

5.4.4  Hub Configuration in Practice

6  MTypes: Message Semantics and Vocabulary

6.1  The Form of an MType

6.2  The Description of an MType

1. The MType string itself
2. A list of zero or more named parameters
3. A list of zero or more named returned values
4. A description of the meaning of the message

• name
• data type (map, list or string as described in Section 3.3) and if appropriate scalar sub-type (see Section 3.4)
• meaning
• whether it is OPTIONAL (considered REQUIRED unless stated otherwise)
• OPTIONAL parameters MAY specify what default will be used if the value is not supplied

6.3  MType Vocabulary: Extensibility and Process

6.4  Core MTypes

6.4.1  Hub Administrative Messages

samp.hub.event.shutdown:

Arguments:

none

Return Values:

none

Description:

The hub SHOULD broadcast this message just before it exits. The hub SHOULD make every effort to broadcast this message even in case of an exit due to an error condition.

samp.hub.event.register:

Arguments:

id (string) -

Public ID of newly registered client

Return Values:

none

Description:

The hub SHOULD broadcast this message every time a client successfully registers.

samp.hub.event.unregister:

Arguments:

id (string) -

public ID of unregistered client

Return Values:

none

Description:

The hub SHOULD broadcast this message every time a client unregisters.

samp.hub.event.metadata:

Arguments:

id (string) -

public ID of client declaring metadata

metadata (map) -

new metadata declared by client

Return Values:

none

Description:

The hub SHOULD broadcast this message every time a client declares its metadata. The metadata argument is exactly as passed using the declareMetadata() method.

samp.hub.event.subscriptions:

Arguments:

id (string) -

public ID of subscribing client

subscriptions (map) -

new subscriptions declared by client

Return Values:

none

Description:

The hub SHOULD broadcast this message every time a client declares its subscriptions. The subscriptions argument is exactly as passed using the declareSubscriptions() method, and hence may contain wildcarded MType strings.

samp.hub.disconnect:

Arguments:

reason (string) -

(OPTIONAL) Short text message indicating the reason that the disconnection is being forced

Return Values:

none

Description:

The hub SHOULD send this message to a client if the hub intends to disconnect that client forcibly. This indicates that no further communication from that client is welcome, and any such attempts may be expected to fail. The hub may wish to disconnect clients forcibly as a result of some hub timeout policy or for other reasons.

6.4.2  Client Administrative Messages

samp.app.ping:

Arguments:

none

Return Values:

none

Description:

Diagnostic used to indicate whether an application is currently responding. No "status"-like return value is defined, since in general any response will indicate aliveness, and the normal samp.status key in the response may be used to indicate any abnormal state.

samp.app.status:

Arguments:

txt (string) -

Textual indication of status

Return Values:

none

Description:

General purpose message to indicate application status.

samp.app.event.shutdown:

Arguments:

none

Return Values:

none

Description:

Indicates that the sending application is going to shut down. Note that sending this message is not a substitute for unregistering with the hub - registered clients about to shut down SHOULD always explicitly unregister.

samp.msg.progress:

Arguments:

msgid (string) -

Message ID of a previously received message

txt (string) -

Textual indication of progress

percent (string) -

(OPTIONAL) SAMP float value giving the approximate percentage progress

timeLeft (string) -

(OPTIONAL) SAMP float value giving the estimated time to completion in seconds

Return Values:

none

Description:

Reports on progress of a message previously received by the sender of this message. Such progress reports MAY be sent at intervals between the receipt of the message and sending a reply. Note that the msg-id of the earlier message must be passed to identify it - the sender of the earlier message (the recipient of this one) will have to have retained it from the return value of the relevant call*() method to match progress reports with requests.

A  Changes between PLASTIC and SAMP

Language Neutrality:

PLASTIC contained some Java-specific ideas and details, in particular an API defined by a Java interface, use of Java RMI-Lite as a transport protocol option, and a lockfile format based on java Property serialization. No features of SAMP are specific to, or defined with reference to, Java (or to any other programming language).

Profiles:

The formal notion of a SAMP Profile replaces the choices of transport protocol in PLASTIC. In practice since the Standard Profile is the only one currently defined, this means that XML-RPC is currently the only transport protocol which can be used to communicate in SAMP.

Nomenclature:

Much of the terminology has changed between PLASTIC and SAMP, in some cases to provide better consistency with common usage in messaging systems. There is not in all cases a one-to-one correspondence betweeen PLASTIC and SAMP concepts, but a partial translation table is as follows:

PLASTIC	SAMP
message	MType
support a message	subscribe to an MType
registered application	client
synchronous request	synchronous call/response
asynchronous request	notification

MTypes:

In PLASTIC message semantics were defined using opaque URIs such as ivo://votech.org/hub/event/HubStopping. These have now been replaced by a vocabulary of structured MTypes such as samp.hub.event.shutdown.

Asynchrony:

Responses from messages in PLASTIC were returned synchronously, using blocking methods at both sender and recipient ends. As well as inhibiting flexibility, this risked timeouts for long processing times at the discretion of the underlying transport. The basic model in SAMP relies on asynchronous responses, though a synchronous façade hub method is also provided for convenience of the sender. Client toolkits may also wish to provide client-side synchronous façades based on fully asynchronous messaging.

Registration:

In PLASTIC clients registered with a single call which acquired a hub connection and declared callback information, message subscriptions, and some metadata. In SAMP, these four operations have been decomposed into separate calls. As well as being tidier, this offers benefits such as meaning that the subscriptions and metadata can be updated during the lifetime of the connection.

Client Metadata:

PLASTIC stored some application metadata (Name) in the hub and provided acess to others (Description, Icon URL, ...) using custom messages. SAMP stores it all in the hub providing better extensibility and consistency as well as improving metadata provision for non-callable applications and somewhat reducing traffic and burden on applications.

Named Parameters:

The parameters for PLASTIC messages were identified by sequence (forming a list), while the parameters for SAMP MTypes are identified by name (forming a map). As well as improving documentability, this makes it much more convenient to allow for optional parameters or to introduce new ones. The same arrangement applies to return values.

Recipient Targetting:

PLASTIC featured methods for sending messages to all or to an explicit list of recipients. In practice the list variants were rarely used except to send to a single recipient. SAMP has methods for sending to all or to a single recipient.

Typing:

Data types in PLASTIC were based partly on Java and partly on XML-RPC types. There was not a one-to-one correspondence between types in the Java-RMI transport and the XML-RPC one, which encouraged confusion. Parameter types included integer, floating point and boolean as well as string, which proved problematic to use correctly from some weakly-typed languages. SAMP uses a more restricted set of types (namely string, list and map) at the protocol level, along with some auxiliary rules for encoding numbers and booleans as strings.

Lockfile:

The lockfile in SAMP's standard profile is named .samp, its format is defined explicitly rather than with reference to Java documentation, and there is better provision for its location in a language-independent way on MS Windows systems. In many cases however, the same lockfile location/parsing code will work for both SAMP and PLASTIC except for the different filenames (".samp" vs. ".plastic").

Public/Private ID:

In PLASTIC a single, public ID was used to label and identify applications during communications directed to the hub or to other applications. This meant that applications could easily, if they wished, impersonate other applications. SAMP's standard profile uses different IDs for public labelling and private identification, which means that such "spoofing" is no longer a danger.

Errors:

SAMP has provision to return more structured error information than PLASTIC did.

Extensibility:

Although PLASTIC was in some ways extensible, SAMP provides more hooks for future extension, in particular by pervasive use of the extensible vocabulary pattern.

B  Change History

• Return values of callAll and notifyAll operations changed; they now return information about clients receiving the messages (Section 3.11).
• Characters allowed in string type restricted to avoid problems transmitting over XML; was 0x01-0x7f, now 0x09, 0x0a, 0x0d, 0x20-0x7f (Section 3.3).
• New hub administrative message samp.hub.disconnect (Section 6.4.1).
• Empty placeholder appendix on SAMP/PLASTIC interoperability removed.
• Wording clarified and made more explicit in a few places.
• Typos fixed, including incorrect BNF in Section 3.7.
• Author list re-ordered.
• Editorial changes and clarifications following RFC period.
• MType Vocabulary section now directs readers to http://www.ivoa.net/samp/ to find current MType list and process.

• Use of new SAMP_HUB environment variable lockfile location option documented in section 4.3.
• Added Non-Technical Preamble section 1.1 as per agreement for all new/revised IVOA documents.

• Add a new Section 5 on the Web Profile. Minor changes in the rest of the document noting the existence of this new Profile.

References

[1]

C. Arviset et al., "IVOA Architecture", IVOA Note, 2010

[2]

http://www.eurovotech.org/

[3]

F. Bonnarel, P. Fernique, O. Bienaymé, D. Egret, F. Genova, M. Louys, F. Ochsenbein, M. Wenger, and J. G. Bartlett, "The ALADIN interactive sky atlas. A reference tool for identification of astronomical sources", A&AS, 143:33-40, 2000

[4]

U. Becciani, M. Comparato, A. Costa, C. Gheller, B. Larsson, F. Pasian, and R. Smareglia. "VisIVO: an interoperable visualisation tool for Virtual Observatory data", Highlights of Astronomy, 14:622-622, 2007

[5]

http://hea-www.harvard.edu/RD/xpa/

[6]

J. Taylor, T. Boch, M. Comparato, M. Taylor, and N. Winstanley. "PLASTIC - a protocol for desktop application interoperability", IVOA Note, 2006

[7]

http://plastic.sourceforge.net/

[8]

http://www.xmlrpc.com/

[9]

S. Bradner, RFC 2119: "Key words for use in RFCs to Indicate Requirement Levels", IETF Request For Comments, 1997

[10]

T. Berners-Lee, L. Masinter, M. McCahill, RFC 1738: "Uniform Resource Locators (URL)", IETF Request For Comments, 1994

[11]

A. van Kesteren (Ed.), "Cross-Origin Resource Sharing", W3C Working Draft, 2010

[12]

A. van Kesteren (Ed.), "XMLHttpRequest Level 2", W3C Working Draft, 2010

[13]

Adobe Flash cross-domain policy, http://www.adobe.com/devnet/articles/crossdomain_policy_file_spec.html

[14]

Microsoft Silverlight cross-domain policy, http://msdn.microsoft.com/en-us/library/cc645032(VS.95).aspx

[15]

T. Berners-Lee et al., RFC 2396: "Uniform Resource Identifiers (URI): Generic Syntax", IETF Request For Comments, 1998

[16]

R. Fielding et al., RFC 2616: "Hypertext Transfer Protocol - HTTP/1.1", IETF Request For Comments, 1999

[17]

D. Eastlake et al., RFC 3275: "XML-Signature Syntax and Processing", IETF Request For Comments, 2002

[18]

A. Barth, "The Web Origin Concept", IETF Draft, 2010

[19]

S. Derriere et al. "An IVOA Standard for Unified Content Descriptors", IVOA Recommendation, 2005

[20]

R. J. Hanisch et al. "IVOA Document Standards", IVOA Recommendation, 2003

Footnotes: