ViewVC logotype

Contents of /trunk/projects/samp/doc/samp.tex

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1761 - (show annotations)
Fri May 18 15:45:44 2012 UTC (9 years, 5 months ago) by m.b.taylor@bristol.ac.uk
File MIME type: application/x-tex
File size: 150307 byte(s)
samp: tiny formatting fixes
1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2 % For an conversion via cgiprint (HTX):
3 % See http://vizier.u-strasbg.fr/local/man/cgiprint.htx
4 \def\ifhtx{\iffalse} % Lines used only for the HTML version
5 \ifhtx
6 % . . .
7 % . . . Definitions in HTX context
8 % . . .
9 \else
10 \documentclass[12pt,notitlepage,onecolumn]{ivoa}
11 % . . .
12 % . . . Definitions in LaTeX context
13 % . . .
14 \fi
15 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
17 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
18 % TtH processing
19 \input{tthdefs}
20 \iftth
21 \newcommand{\dbreak}{}
22 \newcommand{\dbreakd}{}
23 \else
24 \newcommand{\dbreak}{\mbox{}\protect\\}
25 \newcommand{\dbreakd}{\mbox{}\protect\\[-3ex]}
26 \fi
27 \newcommand{\examplesize}{\small}
30 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
32 %% Comment/uncomment lines below to follow your LateX distribution...
34 %%
35 %% If document is processed with latex, dvips and ps2pdf
36 %%
37 \ifx\pdftexversion\undefined
38 \usepackage[dvips]{graphicx}
39 \DeclareGraphicsExtensions{.eps,.ps}
40 %% Uncomment following line if you want PDF thumbnails
41 % \usepackage[ps2pdf]{thumbpdf}
42 % for old hyperref, use:
43 \usepackage[ps2pdf]{hyperref}
44 %% for recent hyperref, use:
45 % \usepackage[ps2pdf,bookmarks=true,bookmarksnumbered=true,hypertexnames=false,breaklinks=true,%
46 % colorlinks,linkcolor=blue,urlcolor=blue]{hyperref}
50 %%
51 %% else if document is processed with pdflatex
52 %%
53 \else
54 \usepackage[pdftex]{graphicx} %% graphics for pdftex (supports .pdf .jpg .png)
55 \usepackage{epstopdf} %% requires epstopdf
56 %% this is to support .ps files :
57 \makeatletter
58 \g@addto@macro\Gin@extensions{,.ps}
59 \@namedef{Gin@rule@.ps}#1{{pdf}{.pdf}{`ps2pdf #1}}
60 \makeatother
61 %% comment above lines if you have included ps files
62 %\DeclareGraphicsExtensions{.pdf,.jpg,.png}
63 %% Uncomment following line if you want PDF thumbnails
64 % \usepackage[pdftex]{thumbpdf}
65 %% for old hyperref, use:
66 % \usepackage[ps2pdf]{hyperref}
67 % for recent hyperref, use:
68 % \usepackage[pdftex,bookmarks=true,bookmarksnumbered=true,hypertexnames=false,breaklinks=true,%
69 % colorlinks,linkcolor=blue,urlcolor=blue]{hyperref}
70 \pdfadjustspacing=1
71 \fi
73 \setcounter{secnumdepth}{4}
74 \setcounter{tocdepth}{3} % doesn't seem to affect tth
76 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
77 % For drawing colored text backgrounds
78 \usepackage{color}
80 % Define \sampversion, \sampdate, \samptype commands.
81 \input{sampversion.tex}
83 %%
84 %% Header of the document...
85 %%
87 % Provide a title for your document
88 \title{SAMP --- Simple Application Messaging Protocol}
90 % Give date and version number
91 \date{\sampdate}
92 \version{\sampversion}
94 % Choose one document type from below
95 %\ivoatype{IVOA Note}
96 %\ivoatype{IVOA Working Draft}
97 %\ivoatype{IVOA Proposed Recommendation}
98 %\ivoatype{IVOA Recommendation}
99 \ivoatype{??}
101 % Name Working group
102 \ivoagroup{Applications}
104 % Give author list: separate different authors with \\
105 % You can add email addresses with links \url{mailto:yourname@ivoa.net}
106 \author{M.~Taylor (m.b.taylor@bristol.ac.uk)\\
107 T.~Boch (boch@astro.u-strasbg.fr)\\
108 M.~Fitzpatrick (fitz@noao.edu)\\
109 A.~Allan (aa@astro.ex.ac.uk)\\
110 J.~Fay (jfay@microsoft.com)\\
111 L.~Paioro (luigi@lambrate.inaf.it)\\
112 J.~Taylor (jontayler@gmail.com)\\
113 D.~Tody (dtody@nrao.edu)}
114 \editor{T.~Boch, M.~Fitzpatrick, M.~Taylor}
116 \def\SVN$#1: #2 ${\expandafter\def\csname SVN#1\endcsname{#2}}
117 \SVN$Rev$
118 % \urlthisversion{\url{http://www.ivoa.net/Documents/SAMP/20101216/}}
119 \urlthisversion{\sampversion: \samptype\ \sampdate\ (Revision \SVNRev)}
120 \urllastversion{\url{http://www.ivoa.net/Documents/SAMP/}}
121 \previousversion{
122 1.0: Working Draft 2008-06-25\\
123 1.11: Recommendation 2009-04-21 (Revision 987)\\
124 1.2: Recommendation 2010-12-16 (Revision 1384)\\
125 1.3: Recommendation 2012-04-11 (Revision 1684)}
127 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
128 \begin{document}
130 \iftth
131 \tthmaketitle
132 \else
133 \maketitle % print header in standard form
134 \newpage % not essential, but existing page break is bad here
135 \fi
137 \begin{abstract}
138 SAMP is a messaging protocol that enables astronomy software tools to
139 interoperate and communicate.
141 IVOA members have recognised that building a monolithic tool
142 that attempts to fulfil all
143 the requirements of all users is impractical, and it is a better use of our
144 limited resources to enable individual tools to work together better.
145 One element of this is defining common file formats for the exchange of data
146 between different applications. Another important component is a messaging
147 system that enables the applications to share data and take advantage of each
148 other's functionality.
149 SAMP supports communication between applications on the desktop
150 and in web browsers,
151 and is also intended to form a framework for more general messaging
152 requirements.
153 \end{abstract}
155 \section*{Status of this Document}
157 This document has been produced by the IVOA Applications Working Group.
158 It has been reviewed by IVOA Members and other interested parties,
159 and has been endorsed by the IVOA Executive Committee as an IVOA
160 Recommendation.
161 It is a stable document and may be used as reference material or cited as
162 a normative reference from another document. IVOA's role in making the
163 Recommendation is to draw attention to the specification and to promote
164 its widespread deployment. This enhances the functionality and
165 interoperability inside the Astronomical Community.
167 Comments, questions and discussions relating to this document
168 may be posted to the mailing list of the SAMP subgroup of the
169 Applications Working Group,
170 \href{mailto:apps-samp@ivoa.net}{apps-samp@ivoa.net}.
171 Supporting material and further discussion
172 may be found at \url{http://www.ivoa.net/samp/}.
174 Changes since earlier versions may be found in Appendix \ref{sect:changes}.
177 \tableofcontents
179 \section{Introduction}
181 \subsection{Non-Technical Preamble and Position in IVOA Architecture}
182 \label{sect:nonTechPreamble}
183 SAMP, the Simple Application Messaging Protocol, is a standard
184 for allowing software tools to exchange control and data information,
185 thus facilitating tool interoperability, and so allowing users
186 to treat separately developed applications as an integrated suite.
187 An example of an operation that SAMP might facilitate is passing a
188 source catalogue from one GUI application to another, and
189 subsequently allowing sources marked by the user in one of those
190 applications to be visible as such in the other.
192 The protocol has been designed, and implementations developed, within
193 the context of the International Virtual Observatory Alliance (IVOA),
194 but the design is not specific either to the Virtual Observatory (VO)
195 or to Astronomy. It is used in practice
196 for both VO and non-VO work with astronomical tools, and is in
197 principle suitable for non-astronomical purposes as well.
199 The SAMP standard itself is neither a dependent, nor a dependency,
200 of other VO standards, but it provides valuable glue between user-level
201 applications which perform different VO-related tasks, and hence
202 contributes to the integration of Virtual Observatory functionality
203 from a user's point of view.
204 Figure~\ref{fig:ivoa-archi} illustrates SAMP in the context of the
205 IVOA Architecture \cite{architecture}.
206 Most existing tools which operate in the
207 User Layer of this architecture provide SAMP interoperability.
208 \begin{figure}[tbh]
209 \begin{center}
210 \includegraphics[scale=0.55]{ivoa-archi}
211 \caption{IVOA Architecture diagram \cite{architecture}.
212 The SAMP protocol appears in the ``Using'' region.}
213 \label{fig:ivoa-archi}
214 \end{center}
215 \end{figure}
217 The semantics of messages that can be exchanged using SAMP are defined
218 by contracts known as MTypes (message-types), which are defined
219 by developer agreement outside of this standard. The list of MTypes
220 used for common astronomical and VO purposes can be found near
221 \url{http://www.ivoa.net/samp/}; many of these make use of standards from
222 elsewhere in the IVOA Architecture, including VOTable, VOResource,
223 Simple Spectral Access, UCD and Utype.
226 \subsection{History}
227 SAMP, the Simple Application Messaging Protocol,
228 is a direct descendent of the PLASTIC protocol, which in turn grew
229 --- in the European VOTech framework ---
230 from the interoperability work of the Aladin \cite{2000A+AS..143...33B} and
231 VisIVO \cite{2007HiA....14..622B} teams. We also note the
232 contribution of the team behind the earlier XPA protocol \cite{xpa}. For more information
233 on PLASTIC's history and purpose see the IVOA Note {\em PLASTIC --- a protocol for
234 desktop application interoperability} \cite{plastic}
235 and the PLASTIC SourceForge site \cite{plastic-sf}.
237 SAMP has similar aims to PLASTIC, but
238 incorporates lessons learnt from two years of practical experience and ideas
239 from partners who were not involved in PLASTIC's initial design.
241 Broadly speaking, SAMP is an abstract framework for
242 loosely-coupled, asynchronous, RPC-like and/or event-based communication,
243 based on a central service providing multi-directional publish/subscribe
244 message brokering.
245 The message semantics are extensible and use structured but weakly-typed data.
246 These concepts are expanded on below.
247 It attempts to make as few assumptions as possible about the transport
248 layer or programming language with which it is used.
249 It also defines a ``Standard Profile'' which specifies how to
250 implement this framework using XML-RPC \cite{xmlrpc} as the transport layer.
251 The result of combining this Standard Profile with the rest of the SAMP
252 standard is deliberately similar in design to PLASTIC,
253 and this has been largely successful in its intention of enabling
254 PLASTIC applications to be modified to use SAMP instead without great effort.
255 More recently (version 1.3) an additional ``Web Profile'' has been introduced,
256 in order to facilitate use of SAMP from web applications.
258 \subsection{Requirements and Scope}
259 SAMP aims to be a simple and extensible protocol that is platform- and
260 language-neutral.
261 The emphasis is on a
262 simple protocol with a very shallow learning curve in order to encourage
263 as many application authors as possible to adopt it.
264 SAMP is intended to do what you need most of the time. The SAMP authors
265 believe that this is the best way to foster innovation and collaboration in
266 astronomy applications.
268 It is important to note therefore that SAMP's scope is reasonably modest; it is
269 not intended to be the perfect messaging solution for all situations.
270 In particular SAMP itself has
271 no support for transactions, security, or guaranteed message delivery
272 or integrity.
273 However, by layering the SAMP architecture on top of suitable
274 messaging infrastructures such capabilities could be provided.
275 These possibilities are not discussed further in this document,
276 but the intention is to provide an architecture which is sufficiently
277 open to allow for such things in the future with little change to the
278 basics.
280 \subsection{Types of Messaging}
281 \label{sect:typeOfMsging}
283 SAMP is currently targetted at inter-application desktop messaging
284 with the idea that the basic framework presented here is extensible to meet
285 future needs, and so it is beyond the scope of this document to outline the
286 many types of messaging systems in use today (these are covered in detail
287 in many other documents). While based on established messaging models,
288 SAMP is in many ways a hybrid of several basic messaging concepts; the
289 protocol is however flexible enough that later versions should be able to
290 interact fairly easily with other messaging systems because of the shared
291 messaging models.
293 The messaging concepts used within SAMP include:
295 \begin{description}
296 \item[Publish/Subscribe Messaging:]
297 A publish/subscribe (pub/sub) messaging system supports an event driven
298 model where information producers and consumers participate in message
299 passing. SAMP applications ``publish'' a message, while consumer
300 applications ``subscribe'' to messages of interest and consume events.
301 The underlying messaging system routes messages from producers
302 to consumers based on
303 the message types in which an application has registered an interest.
304 \item[Point-to-Point Messaging:]
305 In point to point messaging systems, messages are routed to an
306 individual consumer which maintains a queue of ``incoming'' messages. In
307 a traditional message queue, applications send messages to a specified
308 queue and clients retrieve them. In SAMP, the message system manages
309 the delivery and routing of messages, but also permits the concept of a
310 directed message meant for delivery to a specific application. SAMP
311 does not, however, guarantee the order of message delivery as with a
312 traditional message queue.
313 \item[Event-based Messaging:]
314 Event-based systems are systems in which producers generate events, and in
315 which messaging middleware delivers events to consumers based upon a
316 previously specified interest. One typical usage pattern of these systems
317 is the publish/subscribe paradigm, however these systems are also widely
318 used for integrating loosely coupled application components. SAMP allows
319 for the concept that an ``event'' occurred in the system and that these
320 message types may have requirements different from messages where the
321 sender is trying to invoke some action in the network of applications.
322 \item[Synchronous vs. Asynchronous Messaging:]
323 As the term is used in this document, a ``synchronous'' message is one
324 which blocks the sending application from further processing until a
325 reply is received. However, SAMP messaging is based on ``asynchronous''
326 message and response in that the delivery of a message and its
327 subsequent response are handled as separate activities by the
328 underlying system. With the exception of the synchronous message
329 pattern supported by the system, sending or replying to a message using
330 SAMP allows an application to return to other processing while the
331 details of the delivery are handled separately.
332 \end{description}
335 \subsection{About this Document}
336 This document contains the following main sections describing the SAMP protocol
337 and how to use it.
338 Section \ref{sect:architecture}
339 covers the requirements, basic concepts and overall architecture of SAMP.
340 Section \ref{sect:apis} defines abstract (i.e.\ independent of language,
341 platform and transport protocol) interfaces which clients and hubs
342 must offer to participate in SAMP messaging, along with data types
343 and encoding rules required to use them.
344 Section \ref{sect:profile}
345 explains how the abstract API can be mapped to specific network operations
346 to form an interoperable messaging system, and defines the ``Standard Profile'',
347 based on XML-RPC, which gives a particular set of such mappings
348 suitable for general purpose desktop applications.
349 Section \ref{sect:webprofile} defines the ``Web Profile'',
350 an alternative mapping suitable for web applications.
351 Section \ref{sect:mtypes}
352 describes the use of the MType keys used to denote message semantics,
353 and outlines an MType vocabulary.
355 The key words ``MUST'', ``MUST NOT'', ``REQUIRED'', ``SHALL'', ``SHALL NOT'',
356 ``SHOULD'', ``SHOULD NOT'', ``RECOMMENDED'', ``MAY'', and ``OPTIONAL''
357 in this document are to be interpreted as described in RFC 2119 \cite{rfc2119}.
359 \section{Architectural Overview}
360 \label{sect:architecture}
361 This section provides a high level view of the SAMP protocol.
363 \subsection{Nomenclature}
364 In the text that follows these terms are used:
366 \begin{description}
367 \item[Hub:]
368 A broker service for routing SAMP Messages.
369 \item[Client:]
370 An application that talks to a Hub using SAMP. May be a
371 Sender, Recipient, or both.
372 \item[Sender:]
373 A Client that sends a SAMP Message to one or more
374 Recipients via the Hub.
375 \item[Recipient:]
376 A Client that receives a SAMP Message from
377 the Hub. This may have originated from another Client or from the
378 Hub itself.
379 \item[Message:]
380 A communication sent from a Sender to a Recipient
381 via a SAMP Hub. Contains an MType and zero or more named parameters.
382 May or may not provoke a Response.
383 \item[Response:]
384 A communication which may be returned from a Recipient to a Sender
385 in reply to a previous Message. A Response may contain returned values
386 and/or error information. In the terminology of this document,
387 a Response is not itself a Message. A Response is also known as a
388 Reply in this document.
389 \item[MType:]
390 A string defining the semantics of a Message and of its arguments and
391 return values (if any). Every Message contains exactly one MType,
392 and a Message is only delivered to Clients subscribed to that MType.
393 \item[Subscription:]
394 A Client is said to be Subscribed to a given MType if it has
395 declared to the Hub that it is prepared to receive Messages
396 with that MType.
397 \item[Callable Client:]
398 A Client to which the Hub is capable of performing callbacks.
399 Clients are not obliged to be Callable, but only Callable Clients
400 are able to receive Messages or asynchronous Responses.
401 \item[Broadcast:]
402 To send a SAMP Message to all Subscribed Clients
403 excluding the Sender.
404 \item[Profile:]
405 A set of rules which map the abstract API defined by SAMP to a set of
406 I/O operations which may be used by Clients to send and receive
407 actual Messages.
408 \end{description}
411 \subsection{Messaging Topology}
412 SAMP has a hub-based architecture (see Figure~\ref{fig:samp-archi}). The hub is a single service used to route all
413 messages between clients. This makes application discovery more
414 straightforward in that each client only needs to locate the hub, and the services
415 provided by the hub are intended to simplify the actions of the client. A disadvantage of this
416 architecture is that the hub may be a message bottleneck and potential single point of failure.
417 The former means that SAMP may not be suitable for extremely high
418 throughput requirements;
419 the latter may be mitigated by an appropriate strategy for hub restart if failure is likely.
420 \begin{figure}
421 \begin{center}
422 \includegraphics[scale=0.5]{samp-archi}
423 \caption{The SAMP hub architecture}
424 \label{fig:samp-archi}
425 \end{center}
426 \end{figure}
428 Note that the hub is defined as a service interface which may have any of
429 a number of implementations. It may be an independent application running as
430 a daemon, an adapter interface layered on top of an existing messaging
431 infrastructure, or a service provided by an application which is itself
432 one of the hub's clients.
435 \subsection{The Lifecycle of a Client}
437 A SAMP client goes through the following phases:
438 \begin{enumerate}
439 \item Determine whether a hub is running by using the appropriate hub discovery
440 mechanism.
441 \item If so, use the hub discovery mechanism to work out how to communicate
442 with the hub.
443 \item Register with the hub.
444 \item Store metadata such as client name, description and icon in the
445 hub.
446 \item Subscribe to a list of MTypes to define messages which may be
447 received.
448 \item Interrogate the hub for metadata of other clients.
449 \item Send and/or receive messages to/from other clients via the hub.
450 \item Unregister with the hub.
451 \end{enumerate}
452 Phases 4--7 are all optional and may be repeated in any order.
454 By subscribing to the MTypes described in Section \ref{sect:hub-mtypes}
455 a client may, if it wishes, keep track of the details of other clients'
456 registrations, metadata and subscriptions.
458 \subsection{The Lifecycle of a Hub}
459 A SAMP hub goes through the following phases:
461 \begin{enumerate}
462 \item Locate any existing hub by using the appropriate hub discovery mechanism.
463 \begin{enumerate}
464 \item Check whether the existing hub is alive.
465 \item If so, exit.
466 \end{enumerate}
467 \item If no hub is running, or a hub is found but is not
468 functioning, write/overwrite the hub discovery record and start up.
469 \item Await client registrations. When a client makes a legal
470 registration, assign it a public ID,
471 and add the client to the table of registered
472 clients under the public ID. Broadcast a message
473 announcing the registration of a
474 new client.
475 \item When a client stores metadata in the hub, broadcast a message
476 announcing the change
477 and make the metadata available.
478 \item When a client updates its list of subscribed MTypes, broadcast a
479 message announcing the change and make the subscription information
480 available
481 \item When the hub receives a message for relaying, pass it on to
482 appropriate recipients which are subscribed to the message's MType.
483 Broadcast messages are sent to all
484 subscribed clients except the sender, messages with a specified recipient
485 are sent to that recipient if it is subscribed.
486 \item Await client unregistrations. When a client unregisters, broadcast
487 a message announcing the unregistration
488 and remove the client from the table of registered clients.
489 \item If the hub is unable to communicate with a client, it may
490 unregister it as described in phase 7.
491 \item When the hub is about to shutdown, broadcast a message to
492 all subscribed clients.
493 \item Delete the hub discovery record.
494 \end{enumerate}
495 Phases 3--8 are responses to events which may occur
496 multiple times and in any order.
498 The MTypes broadcast by the hub to inform clients of changes in its state
499 are given in Section \ref{sect:hub-mtypes}.
501 Readers should note that, given this scheme, race conditions may occur.
502 A client might for instance try to register with a hub which has just shut down,
503 or attempt to send to a recipient which has already unregistered.
504 Specific profiles MAY define best-practice rules in order to best manage these
505 conditions,
506 but in general clients should be aware that SAMP's lack of guaranteed
507 message delivery and timing means that unexpected conditions are possible.
509 \subsection{Message Delivery Patterns}
510 \label{sect:delivery-outline}
512 Messages can be sent according to three patterns, differing in
513 whether and how a response is returned to the sender:
514 \begin{enumerate}
515 \item Notification
516 \item Asynchronous Call/Response
517 \item Synchronous Call/Response
518 \end{enumerate}
519 The Notification pattern is strictly one-way while in the Call/Response
520 patterns the recipient returns a response to the sender.
522 If the sender expects to receive some useful data as a result of the
523 receiver's processing, or if it wishes to find out whether and
524 when the processing is completed, it should use one of the Call/Response
525 variants. If on the other hand the sender has no interest in what
526 the recipient does with the message once it has been sent, it
527 may use the Notification pattern. Notification, since it involves
528 no communication back from the recipient to the sender, uses
529 fewer resources.
530 Although typically ``event''-type messages will be sent using Notify
531 and ``request-for-information''-type messages will be sent using
532 Call/Response, the choice of which delivery pattern to use is
533 entirely distinct from the content of the message, and is up to
534 the sender; any message (MType) may be sent using any of the above
535 patterns.
536 Apart from the fact of returning or not returning a response,
537 the recipient SHOULD process messages in exactly the same way
538 regardless of which pattern is used.
540 From the receiver's point of view there are only two cases:
541 Notification and Asynchronous Call/Response.
542 However, the hub provides a convenience
543 method which simulates a synchronous call from the sender's point of view.
544 The purpose of this is to simplify the use of the protocol
545 in situations such as scripting environments which cannot easily handle
546 callbacks. However, it is RECOMMENDED to use the asynchronous pattern
547 where possible due to its greater robustness.
549 \subsection{Extensible Vocabularies}
550 \label{sect:vocab}
552 At several places in this document structured information is
553 conveyed by use of a controlled but extensible vocabulary.
554 Some examples are the client metadata keys (Section \ref{sect:app-metadata}),
555 message encoding keys (Section \ref{sect:msg-encode}) and
556 MType names (Section \ref{sect:mtypes}).
558 Wherever this pattern is used, the following rules apply.
559 This document defines certain well-known keys with defined meanings.
560 These may be OPTIONAL or REQUIRED as documented, but if present
561 MUST be used by clients and hubs in the way defined here.
562 All such well-known keys start with the string ``{\tt samp.}''.
564 Clients and hubs are however free to introduce and use non-well-known
565 keys as they see fit. Any string may be used for such a non-standard key,
566 with the restriction that it MUST NOT start with the prefix ``{\tt samp.}''.
567 The prefix ``{\tt x-samp.}'' has a special meaning as described below.
569 The general rule is that hubs and clients encountering keys which
570 they do not understand SHOULD ignore them, propagating them to
571 downstream consumers if appropriate.
572 As far as possible, where new keys are introduced they SHOULD be
573 such that applications ignoring them will continue to behave
574 in a sensible way.
576 Hubs and clients are therefore able to communicate information
577 additional to that defined in the current version of this document
578 without disruption to those which do not understand it.
579 This extensibility may be of use to applications which have mutual
580 private requirements outside the scope of this specification,
581 or to enable experimentation with new features.
582 If the SAMP community finds such experiments useful,
583 future versions of this document may bring such functionality within
584 the SAMP specification itself by defining new keys in the
585 ``{\tt samp.}'' namespace. The ways in which these vocabularies
586 are used means that such extensions should be possible with
587 minimal upheaval to the existing specification and implementations.
589 Non-well-known keys (those outside of the ``{\tt samp}'' namespace)
590 fall into two categories:
591 those which are candidates for future incorporation into the SAMP
592 standard as well-known, and those which are not.
593 If developers are experimenting with keys which they hope or believe
594 may be incorporated into the SAMP standard as well-known at some time
595 in the future, they may use the special namespace ``{\tt x-samp}''.
596 If a future version of the standard does incorporate such a key
597 as well-known, the prefix is simply changed from ``{\tt x-samp.}''
598 to ``{\tt samp.}''.
599 Consumers of such keys SHOULD treat keys which differ only in the
600 substitution of the prefix ``{\tt samp.}'' for ``{\tt x-samp.}'' or
601 vice versa as if they have identical semantics,
602 so for instance a client application should treat the value of
603 a metadata item with key ``{\tt x-samp.a.b}''
604 in exactly the same way as one with key ``{\tt samp.a.b}''.
605 The ``{\tt samp}'' and ``{\tt x-samp}'' form of the same key
606 SHOULD NOT be presented in the same map. If both are presented together,
607 the ``{\tt samp}'' form MAY be considered to take precedence,
608 though any reasonable behaviour is permitted.
609 This scheme makes it easy to introduce new well-known keys
610 in a way which neither makes illicit use of the reserved ``{\tt samp.}''
611 namespace nor requires frequent updates to the SAMP standard,
612 and which places a minimum burden on application developers.
613 Lists of keys in the ``{\tt x-samp}'' namespace under discussion
614 may be found near \url{http://www.ivoa.net/samp/}.
617 \subsection{Use of Profiles}
618 \label{sect:profiles}
620 The design of SAMP is based on the abstract interfaces
621 defined in Section~\ref{sect:apis}. On its own however, this does
622 not include the detailed instructions required by application developers
623 to achieve interoperability. To achieve that, application developers
624 must know how to map the operations in the abstract SAMP interfaces
625 to specific I/O
626 (in most cases, network) operations. It is these I/O operations
627 which actually form the communication between applications.
628 The rules defining this mapping from interface to I/O operations
629 are what constitute a SAMP ``Profile''
630 (the term ``Implementation'' was considered for this purpose, but rejected
631 because it has too many overlapping meanings in this context).
633 There are two ways in which such a Profile can be specified as far as
634 client application developers are concerned:
635 \begin{enumerate}
636 \item By describing exactly what bytes are to be sent using what wire
637 protocols for each SAMP interface operation
638 \item By providing one or more language-specific libraries with calls
639 which correspond to those of the SAMP interface
640 \end{enumerate}
641 Although either is possible, SAMP is well-suited for approach (1) above
642 given a suitable low-level transport library.
643 This is the case since the operations are quite low-level,
644 so client applications can easily
645 perform them without requiring an independently developed SAMP library.
646 This has the additional advantages that central effort does not have to
647 be expended in producing language-specific libraries, and that
648 the question of ``unsupported'' languages does not arise.
650 Splitting the abstract interface and Profile descriptions
651 in this way
652 separates the basic design principles from the details
653 of how to apply them, and it opens the door for other Profiles
654 serving other use cases in the future.
656 This document defines two profiles along the lines of (1) above.
657 The Standard Profile (Section \ref{sect:profile})
658 which dates from the first version of this document,
659 is suitable for desktop applications,
660 while the Web Profile (Section \ref{sect:webprofile}),
661 introduced at SAMP version 1.3,
662 is suitable for web (browser-based) applications.
664 A client author will usually only need to implement SAMP communications
665 using a single profile.
666 Hub implementations should ideally implement all known profiles;
667 in this way clients using different profiles can communicate
668 transparently with each other via a hub which mediates between them.
669 Since the different profiles are based on the same abstract interface
670 (Section \ref{sect:apis}),
671 such mediation will not lead to loss or distortion of the communications.
673 \subsection{Security Considerations}
674 \label{sect:security}
676 SAMP enables inter-process communications including the capability for
677 one client to cause execution of code by another client.
678 This raises the possibility of an unprivileged client performing
679 privileged actions in virtue of its SAMP-enabled interoperation.
680 Whether this is problematic in practice depends on two things:
681 first the identities of the interoperating clients
682 (whether they all share similar levels of privilege or trust)
683 and second the semantics of the messages
684 (the nature of the code that may be executed remotely, and particularly
685 how it can be parameterised).
686 In the case that untrusted clients can cause execution of potentially
687 damaging code by trusted clients, there is a serious security issue.
689 The trustedness of registered clients is determined by the profile
690 or profiles operated by the hub at a given time (Section \ref{sect:profiles}),
691 since the extent to which registered clients are trusted may differ
692 between different profiles.
693 Clients registering via the Standard Profile in its usual configuration
694 can be assumed all to be owned by the same user and hence to have
695 the same privileges (Section \ref{sect:std-security}),
696 but Web Profile clients usually have only
697 limited access privileges outside of the interoperability granted by SAMP
698 (Section \ref{sect:web-security}).
700 In most cases profiles will, in virtue of their definition or at least
701 of their implementation, provide reasonable assurance that
702 registered clients are unlikely to be hostile.
703 However for clients which may be run in a general SAMP context,
704 it is wise not to expose via SAMP mechanisms unrestricted access
705 to sensitive resources.
706 In particular, it is recommended not to introduce MTypes which can
707 be made to execute arbitrary code (inviting injection attacks),
708 or to declare metadata which reveals sensitive information.
709 As an alternative approach, it may be appropriate in certain usage
710 scenarios to ensure that only a restricted secure profile is running.
712 \section{Abstract APIs and Data Types}
713 \label{sect:apis}
715 \subsection{Hub Discovery Mechanism}
716 \label{sect:hub-discovery}
718 In order to keep track of which hub is running, a hub discovery mechanism, capable
719 of yielding information about how to determine the existence of and communicate with
720 a running hub, is needed. This is a Profile-specific matter and
721 specific prescriptions are described in Sections
722 \ref{sect:lockfile} (Standard Profile) and \ref{sect:web-httpd} (Web Profile).
724 \subsection{Communicating with the Hub}
725 The details of how a client communicates with the hub are Profile-specific.
726 Specific prescriptions are described in Sections
727 \ref{sect:profile} (Standard Profile) and
728 \ref{sect:webprofile} (Web Profile).
731 \subsection{SAMP Data Types}
732 \label{sect:samp-data-types}
734 For all hub/client communication, including the actual content of messages,
735 SAMP uses three conceptual data types:
736 \begin{enumerate}
737 \item {\tt string} --- a scalar value consisting of a sequence of characters;
738 each character is an ASCII character with hex code
739 09, 0a, 0d or 20--7f
740 \item {\tt list} --- an ordered array of data items
741 \item {\tt map} --- an unordered associative array of key-value pairs,
742 in which each key is a {\tt string} and each value is a data item
743 \end{enumerate}
744 These types can in principle be nested to any level, so that the elements
745 of a list or the values of a map may themselves be strings, lists or maps.
747 There is no reserved representation for a null value, and it is
748 illegal to send a null value in a SAMP context even if the underlying
749 transport protocol permits this. However a zero-length
750 string or an empty list or map may, where appropriate, be used to
751 indicate an empty value.
753 Although SAMP imposes no maximum on the length of a string,
754 particular transport protocols or implementation considerations
755 may effectively do so; in general, hub and client implementations
756 are not expected to deal with data items of unlimited size.
757 General purpose MTypes SHOULD therefore be specified so that
758 bulk data is not sent within the message or response. In general it is
759 preferred to define a message parameter or result element
760 as the URL or filename of a potentially
761 large file rather than as the inline text of the file itself.
762 SAMP defines no formal list of which URL protocols are permitted
763 in such cases, but clients which need to dereference such URLs
764 SHOULD be capable of dealing with at least the ``http'' and ``file'' schemes.
765 ``https'', ``ftp'' and other schemes are also permitted, but when
766 sending such URLs, consideration should be given to whether receiving
767 clients are likely to be able to dereference them.
769 At the protocol level there is no provision for typing of scalars.
770 Unlike many Remote Procedure Call (RPC) protocols SAMP does not distinguish syntactically
771 between strings, integers, floating point values, booleans etc.
772 This minimizes the restrictions on what underlying transport
773 protocols may be used, and avoids a number of problems associated with
774 using typed values from weakly-typed languages such as
775 Python and Perl.
776 The practical requirement to transmit these types is addressed however
777 by the next section.
779 \subsection{Scalar Type Encoding Conventions}
780 \label{sect:scalar-types}
782 Although the protocol itself defines {\tt string} as the only scalar type,
783 some MTypes will wish to define parameters or return
784 values which have non-string semantics,
785 so conventions for encoding these as {\tt string}s
786 are in practice required.
787 Such conventions only need to be understood by the sender and
788 recipient of a given message and so can be established on a per-MType basis,
789 but to avoid unnecessary duplication of effort
790 this section defines some commonly-used
791 type encoding conventions.
793 We define the following BNF productions:
794 \begin{verbatim}
795 <digit> ::= "0" | "1" | "2" | "3" | "4" | "5" | "6"
796 | "7" | "8" | "9"
797 <digits> ::= <digit> | <digits> <digit>
798 <float-digits> ::= <digits> | <digits> "." | "." <digits>
799 | <digits> "." <digits>
800 <sign> ::= "+" | "-"
801 \end{verbatim}
802 With reference to the above we define the following type encoding conventions:
803 \begin{itemize}
804 \item \verb,<SAMP int> ::= [ <sign> ] <digits>,\\
805 An integer value is encoded using its decimal representation with
806 an OPTIONAL preceding sign and with no
807 leading, trailing or embedded whitespace.
808 There is no guarantee about the largest or smallest values which can
809 be represented, since this will depend on the processing environment
810 at decode time. \\
811 %
812 \item \verb,<SAMP float> ::= [ <sign> ] <float-digits>,\\
813 \verb, [ "e" | "E" [ <sign> ] <digits> ],\\
814 A floating point value is encoded as a mantissa with an OPTIONAL
815 preceding sign followed by an OPTIONAL exponent part
816 introduced with the character ``{\tt e}'' or ``{\tt E}''.
817 There is no guarantee about the largest or smallest values which can
818 be represented or about the number of digits of precision which are
819 significant, since these will depend on the processing environment
820 at decode time. \\
821 %
822 \item \verb,<SAMP boolean> ::= "0" | "1",\\
823 A boolean value is represented as an integer: zero represents false,
824 and any other value represents true.
825 1 is the RECOMMENDED value to represent true.
826 \end{itemize}
828 The numeric types are based on the syntax of the C programming language,
829 since this syntax forms the basis for typed data syntax in many other
830 languages.
831 There may be extensions to this list in future versions of this standard.
833 Particular MType definitions may use these conventions or devise
834 their own as required. Where the conventions in this list are used,
835 message documentation SHOULD make it clear using a form of
836 words along the lines ``this parameter contains a {\em SAMP int\/}''.
839 \subsection{Registering with the Hub}
840 \label{sect:registration}
842 A client registers with the hub to:
843 \begin{enumerate}
844 \item establish communication with the hub
845 \item advertise its presence to the hub and to other clients
846 \item obtain registration information
847 \end{enumerate}
848 The registration information is in the form of a {\tt map} containing
849 data items which the client may wish to use during the SAMP session.
850 The hub MUST fill in values for the following keys in the returned {\tt map}:
851 \begin{description}
852 \item[{\tt samp.hub-id}] ---
853 The client ID which is used by the hub when it sends messages itself
854 (rather than forwarding them from other senders).
855 For instance, this ID will be used when the hub sends the
856 {\tt samp.hub.event.shutdown} message.
857 \item[{\tt samp.self-id}] ---
858 The client ID which identifies the registering client.
859 \end{description}
860 These keys form part of an extensible vocabulary as explained in
861 Section \ref{sect:vocab}.
862 In most cases a client will not require either of the above IDs for
863 normal SAMP operation, but they are there for clients which do wish
864 to know them.
865 Particular Profiles may require additional entries in this map.
867 Immediately following registration, the client will typically
868 perform some or all of the following OPTIONAL operations:
869 \begin{itemize}
870 \item supply the hub with metadata about itself, using the
871 {\tt declareMetadata()} call
872 \item tell the hub how it wishes the hub to communicate with it,
873 if at all (the mechanism for this is profile-dependent, and it may
874 be implicit in registration)
875 \item inform the hub which MTypes it wishes to subscribe to, using the
876 {\tt declareSubscriptions()} call
877 \end{itemize}
880 \subsection{Application Metadata}
881 \label{sect:app-metadata}
883 A client may store metadata in the form of a {\tt map} of key-value pairs in the hub
884 for retrieval by other clients. Typical metadata might be the human-readable
885 name of the application, a description and a URL for its icon, but other values
886 are permitted. The following keys are defined for well-known metadata items:
887 \begin{description}
888 \item[{\tt samp.name}] --- A one word title for the application.
889 \item[{\tt samp.description.text}] --- A short description of the
890 application, in plain text.
891 \item[{\tt samp.description.html}] --- A description of the application,
892 in HTML.
893 \item[{\tt samp.icon.url}] --- The URL of an icon in png, gif or jpeg format.
894 \item[{\tt samp.documentation.url}] --- The URL of a documentation web page.
895 \end{description}
896 All of the above are OPTIONAL, but {\tt samp.name} is strongly RECOMMENDED.
897 These keys form the basis of an extensible vocabulary as explained in
898 Section \ref{sect:vocab}.
901 \subsection{MType Subscriptions}
902 \label{sect:subscription}
904 As outlined above, an MType is a string which defines the semantics of
905 a message. MTypes have a hierarchical form. Their syntax is given
906 by the following BNF:
907 \begin{verbatim}
908 <mchar> ::= [0-9A-Za-z] | "-" | "_"
909 <atom> ::= <mchar> | <atom> <mchar>
910 <mtype> ::= <atom> | <mtype> "." <atom>
911 \end{verbatim}
912 Examples might be ``{\tt samp.hub.event.shutdown}'' or ``{\tt file.load}''.
914 A client may {\em subscribe\/} to one or more MTypes to indicate
915 which messages it is willing to receive. A client will only ever
916 receive messages with MTypes to which it has subscribed.
917 In order to do this it passes a subscriptions {\tt map} to the hub.
918 Each key of this map is an MType string to which the client wishes
919 to subscribe, and the corresponding value is a map which may contain
920 additional information about that subscription. Currently, no keys
921 are defined for these per-MType maps, so typically they will be empty
922 (have no entries). The use of a map here is to permit experimentation
923 and perhaps future extension of the SAMP standard.
925 As a special case, simple wildcarding is permitted in subscriptions.
926 The keys of the subscription map may actually be of the form
927 \verb|<msub>|, where
928 \begin{verbatim}
929 <msub> ::= "*" | <mtype> "." "*"
930 \end{verbatim}
931 Thus a subscription key ``{\tt file.event.*}'' means that a client wishes
932 to receive any messages with MType which begin ``{\tt file.event.}''.
933 This does not include ``{\tt file.event}''.
934 A subscription key ``{\tt *}'' subscribes to all MTypes.
935 Note that the wildcard ``{\tt *}'' character may only appear
936 at the end of a subscription key, and that this indicates
937 subscription to the entire subtree.
939 More discussion of MTypes, including their semantics, is given in
940 Section \ref{sect:mtypes}.
942 \subsection{Message Encoding}
943 \label{sect:msg-encode}
945 A message is an abstract container for the information we wish to send
946 to another application. The message itself is that data which should
947 arrive at the receiving application. It may be transmitted along
948 with some external items (e.g.\ sender, recipient and message identifiers)
949 required to ensure proper delivery or handling.
951 A message is encoded for SAMP transmission as a {\tt map} with the following REQUIRED keys:
952 \begin{description}
953 \item[{\tt samp.mtype}] ---
954 A {\tt string} giving the MType which defines the meaning of the message.
955 The MType also, via external documentation, defines the names, types and
956 meanings of any parameters and return values.
957 MTypes are discussed in more detail in
958 Section \ref{sect:mtypes}.
959 \item[{\tt samp.params}] ---
960 A {\tt map} containing the values for the message's named parameters.
961 These give the data required for the receiver to act on the message,
962 for instance the URL of a given file. The names, types and semantics
963 of these parameters are determined by the MType.
964 Each key in this map is the name of a parameter, and the corresponding
965 value is that parameter's value.
966 \end{description}
967 These keys form the basis of an extensible vocabulary as explained in
968 Section \ref{sect:vocab}.
971 \subsection{Response Encoding}
972 \label{sect:response-encode}
974 A response is what may be returned from a recipient to a sender giving
975 the result of processing a message (though in the case of the Notification
976 delivery pattern, no such response is generated or returned).
977 It may contain MType-specific return values, or error information, or both.
979 A response is encoded for SAMP transmission as a {\tt map} with the following keys:
980 \begin{description}
981 \item[{\tt samp.status}] (REQUIRED) ---
982 A {\tt string} summarising the result of the processing.
983 It may take one of the following defined values:
984 \begin{description}
985 \item[{\tt samp.ok}:]
986 Processing successful.
987 The {\tt samp.result}, but not the {\tt samp.error} entry
988 SHOULD be present.
989 \item[{\tt samp.warning}:]
990 Processing partially successful.
991 Both {\tt samp.result} and {\tt samp.error} entries SHOULD be present.
992 \item[{\tt samp.error}:]
993 Processing failed.
994 The {\tt samp.error}, but not the {\tt samp.result} entry
995 SHOULD be present.
996 \end{description}
997 These values form the basis of an extensible vocabulary as explained in
998 Section \ref{sect:vocab}.
999 \item[{\tt samp.result}] (REQUIRED in case of full or partial success) ---
1000 A {\tt map} containing the values for the message's named return values.
1001 The names, types and semantics of these returns are determined by
1002 the MType.
1003 Each key in this map is the name of a return value, and the corresponding
1004 value is the actual value.
1005 Note that even for MTypes which define no return values, the value of this
1006 entry MUST still be a {\tt map} (typically an empty one).
1007 \item[{\tt samp.error}] (REQUIRED in case of full or partial error) ---
1008 A {\tt map} containing error information.
1009 The following keys are defined for this map:
1010 \begin{description}
1011 \item[{\tt samp.errortxt}] (REQUIRED) ---
1012 A short string describing what went wrong.
1013 This will typically be delivered to the user of the sender application.
1014 \item[{\tt samp.usertxt}] (OPTIONAL) ---
1015 A free-form string containing any additional text an application wishes
1016 to return. This may be a more verbose error description meant to be
1017 appended to the {\tt samp.errortxt} string,
1018 however it is undefined how this
1019 string should be handled when received.
1020 \item[{\tt samp.debugtxt}] (OPTIONAL) ---
1021 A longer string which may contain more detail on what went wrong.
1022 This is typically intended for debugging purposes, and may for instance
1023 be a stack trace.
1024 \item[{\tt samp.code}] (OPTIONAL) ---
1025 A string containing a numeric or textual code identifying the error,
1026 perhaps intended to be parsable by software.
1027 Values beginning ``{\tt samp.}'' are reserved.
1028 \end{description}
1029 These keys form the basis of an extensible vocabulary as explained in
1030 Section \ref{sect:vocab}.
1031 \end{description}
1032 These keys form the basis of an extensible vocabulary as explained in
1033 Section \ref{sect:vocab}.
1035 In most cases, such responses will be generated by a Recipient client
1036 and forwarded by the Hub to the Sender.
1037 In some cases however the hub may pass to the sender an error response it has
1038 generated itself on behalf of the recipient.
1039 In particular, if the hub determines that no response will ever be received
1040 from the recipient (perhaps because the recipient has unregistered
1041 without replying) the hub MAY generate and forward a response with
1042 {\tt samp.status=samp.error} and the {\tt samp.code} key in the
1043 {\tt samp.error} structure set to ``{\tt samp.noresponse}''.
1044 Clients SHOULD NOT generate such {\tt samp.code=samp.noresponse} responses
1045 themselves.
1048 \subsection{Sending and Receiving Messages}
1049 \label{sect:delivery}
1051 As outlined in Section~\ref{sect:delivery-outline},
1052 three messaging patterns are supported, differing
1053 according to whether and how the response is returned to the sender.
1054 For a given MType
1055 there may be a messaging pattern that is most typically used, but there is
1056 nothing in the protocol that ties a particular MType to a particular messaging
1057 pattern; any MType may legally be sent using any delivery pattern.
1059 From the point of view of the sender, there are three ways in which a message
1060 may be sent,
1061 and from the point of view of the recipient there are two ways in which
1062 one may be received. These are described as follows.
1063 \begin{description}
1064 \item[Notification:] In the notification pattern, communication is only
1065 in one direction:
1066 \begin{enumerate}
1067 \item The sender sends a message to the hub for delivery to one or more
1068 recipients.
1069 \item The hub forwards the message to those requested recipients which are subscribed.
1070 \item No reply from the recipients is expected or possible.
1071 \end{enumerate}
1072 Notifications can be sent to a given recipient or broadcast to all
1073 recipients. The notification pattern for a single recipient is illustrated in
1074 Figure~\ref{fig:notification}.
1075 \begin{figure}[!h]
1076 \begin{center}
1077 \includegraphics[scale=0.5]{samp-notification}
1078 \caption{Notification pattern}
1079 \label{fig:notification}
1080 \end{center}
1081 \end{figure}
1082 %
1083 \item[Asynchronous Call/Response:]
1084 In the asynchronous call pattern, {\em message tags\/} and
1085 {\em message identifiers\/} are used
1086 to tie together messages and their replies:
1087 \begin{enumerate}
1088 \item The sender sends a message to the hub for delivery to one or more
1089 recipients, supplying along with the message a tag string of its
1090 own choice, {\em msg-tag\/}. In return it receives a unique
1091 identifier string, {\em msg-id\/}.
1092 \item The hub forwards the message to the appropriate recipients,
1093 supplying along with the message an identifier string, {\em msg-id\/}.
1094 \item Each recipient processes the message, and sends its response
1095 back to the hub along with the ID string {\em msg-id\/}.
1096 \item Using a callback, the hub passes the response back to the
1097 original sender along with the ID string {\em msg-tag\/}.
1098 \end{enumerate}
1099 The sender is free to use any value for the {\em msg-tag\/}.
1100 There is no requirement on the form of the hub-generated {\em msg-id\/}
1101 (it is not intended to be parsed by the recipient), but it MUST be
1102 sufficient for the hub to pair messages with their responses reliably,
1103 and to pass the correct {\em msg-tag\/} back with the response
1104 to the sender\footnote{
1105 One way a hub might implement this is to generate {\em msg-id\/}
1106 by concatenating the sender's client ID and the {\em msg-tag\/}.
1107 When any response is received the hub can then unpack the accompanying
1108 {\em msg-id\/} to find out who the original sender was and what
1109 {\em msg-tag\/} it used. In this way the hub can determine
1110 how to pass each response back to its correct sender without needing
1111 to maintain internal state concerning messages in progress.
1112 Hub and client implementations may wish to exploit this freedom
1113 in assigning message IDs for other purposes as well,
1114 for instance to incorporate timestamps or checksums.
1115 }.
1116 In most cases the sender will not require the {\em msg-id\/}, since
1117 the {\em msg-tag\/} is sufficient to match calls with responses.
1118 For this reason, the sender need not retain the {\em msg-id\/} and
1119 indeed need not wait for it, avoiding a hub round trip at send time.
1120 The only case in which the sender may require the {\em msg-id\/} is
1121 if it needs to communicate later with the recipient about the message
1122 that was sent, for instance as part of a progress report.
1123 Asynchronous calls may be sent to a given recipient or broadcast to all
1124 recipients. In the latter case, the sender SHOULD be prepared to deal
1125 with multiple responses to the same call.
1126 The asynchronous pattern is illustrated in Figure~\ref{fig:async}.
1127 \begin{figure}[!h]
1128 \begin{center}
1129 \includegraphics[scale=0.45]{samp-asynchronous}
1130 \caption{Asynchronous Call/Response pattern}
1131 \label{fig:async}
1132 \end{center}
1133 \end{figure}
1134 %
1135 \item[Synchronous Call/Response]
1136 A synchronous utility method is provided by the hub, mainly for
1137 the convenience of
1138 environments where dealing with asynchronicity might be a problem.
1139 The hub will provide synchronous behaviour to the sender,
1140 interacting with the receiver in exactly the same way as for the
1141 asynchronous case above.
1142 \begin{enumerate}
1143 \item The sender sends a message to the hub for delivery to a given recipient,
1144 optionally specifying as well a maximum time it is prepared to wait.
1145 The sender's call blocks until a response is available.
1146 \item The hub forwards the message to the recipient,
1147 supplying along with the message an ID string, {\em msg-id\/}.
1148 \item The recipient processes the message, and sends its response
1149 back to the hub along with the ID string {\em msg-id\/}.
1150 \item The hub passes back the response as the return value from the original
1151 blocking call made by the sender. If no response is received within
1152 the sender's specified timeout the blocking call will terminate with
1153 an error. The hub is not guaranteed to wait indefinitely;
1154 it MAY in effect impose its own timeout.
1155 \end{enumerate}
1156 There is no broadcast counterpart for the synchronous call.
1157 This pattern is illustrated in Figure~\ref{fig:sync}.
1158 \begin{figure}[!h]
1159 \begin{center}
1160 \includegraphics[scale=0.45]{samp-synchronous}
1161 \caption{Synchronous Call/Response pattern}
1162 \label{fig:sync}
1163 \end{center}
1164 \end{figure}
1165 %
1166 \end{description}
1168 Note that the two different cases from the receiver's point of view,
1169 {\em Notification\/} and {\em Call/Response\/},
1170 differ only in whether a response is returned to the hub.
1171 In other respects the receiver SHOULD process the message in
1172 exactly the same way for both patterns.
1174 Although it is REQUIRED by this standard that client applications
1175 provide a Response for every Call that they receive, there is no
1176 way that the hub can enforce this. Senders using the Synchronous
1177 or Asynchronous Call/Response patterns therefore should be aware
1178 that badly-behaved recipients might fail to respond, leading to calls
1179 going unanswered indefinitely. The timeout parameter in the
1180 Synchronous Call/Response pattern provides some protection from
1181 this eventuality; users of the Asynchronous Call/Response pattern
1182 may or may not wish to take their own steps.
1185 \subsection{Operations a Hub Must Support}
1186 \label{sect:hubOps}
1187 This section describes the operations that a hub MUST support and the associated
1188 data that MUST be sent and received.
1189 The precise details of how these operations
1190 map onto method names and signatures is Profile-dependent.
1191 The mapping for the
1192 Standard Profile is described in Section \ref{sect:mappingXMLRPC},
1193 and for the Web Profile in Section \ref{sect:webXMLRPC}.
1194 \begin{itemize}
1195 \item \verb|map reg-info = register()|\\
1196 Method called by a client wishing to register
1197 with the hub.
1198 The form of {\tt reg-info} is given in Section \ref{sect:registration}.
1199 Note that the form of this call may vary according to the requirements
1200 of the particular Profile in use. For instance authentication tokens
1201 may be passed in one or both directions to complete registration.
1202 \\
1203 \item \verb|unregister()|\\
1204 Method called by a client wishing to unregister from the hub.
1205 \\
1206 \item \verb|declareMetadata(map metadata)|\\
1207 Method called
1208 by a client to declare its metadata.
1209 May be called zero or more times to update hub state; the most recent
1210 call is the one which defines the client's currently declared metadata.
1211 The form of the {\tt metadata} map is given in
1212 Section \ref{sect:app-metadata}.
1213 \\
1214 \item \verb|map metadata = getMetadata(string client-id)|\\
1215 Returns the metadata
1216 information for the client whose public ID is {\tt client-id}.
1217 The form of the {\tt metadata} map is given in
1218 Section \ref{sect:app-metadata}.
1219 \\
1220 \item \verb|declareSubscriptions(map subscriptions)|\\
1221 Method called by
1222 a callable client to declare the MTypes it wishes to subscribe to.
1223 May be called zero or more times to update hub state; the most recent
1224 call is the one which defines the client's currently subscribed MTypes.
1225 The form of the {\tt subscriptions} map is given in
1226 Section \ref{sect:subscription}.
1227 \\
1228 \item \verb|map subscriptions = getSubscriptions(string client-id)|\\
1229 Returns the subscribed MTypes
1230 for the client whose public ID is {\tt client-id}.
1231 The form of the {\tt subscriptions} map is given in
1232 Section \ref{sect:subscription}.
1233 \\
1234 \item \verb|list client-ids = getRegisteredClients()|\\
1235 Returns the list of public ids of all other registered clients.
1236 The caller's ID ({\tt samp.self-id} from Section \ref{sect:registration})
1237 is not included,
1238 but the hub's ID ({\tt samp.hub-id} from Section \ref{sect:registration}) is.
1239 \\
1240 \item \verb|map client-subs = getSubscribedClients(string mtype)|\\
1241 Returns a map with an entry for all other registered clients which are
1242 subscribed to the MType {\tt mtype}.
1243 The key for each entry is a subscribed client ID,
1244 and the value is a (possibly empty) {\tt map}
1245 providing further information on its subscription to {\tt mtype}
1246 as described in Section \ref{sect:subscription}.
1247 An entry for the caller is not included, even if it is subscribed.
1248 {\tt mtype} MUST NOT include wildcards.
1249 \\
1250 \item \verb|notify(string recipient-id, map message)|\\
1251 Sends a message using the Notification pattern
1252 to a given recipient.
1253 The form of the {\tt message} map is given
1254 in Section \ref{sect:msg-encode}.
1255 An error results if the recipient is not subscribed to the message's
1256 MType.
1257 \\
1258 \item \verb|list recipient-ids = notifyAll(map message)|\\
1259 Sends a message using the Notification pattern
1260 to all other clients which are subscribed to the message's MType.
1261 The form of the {\tt message} map is given
1262 in Section \ref{sect:msg-encode}.
1263 The return value is a {\tt list} of the client IDs of the clients
1264 to which an attempt to send the message is made.
1265 \\
1266 \item \verb|string msg-id = call(string recipient-id, string msg-tag,|\\
1267 \verb| map message)|\\
1268 Sends a message using the Asynchronous Call/Response pattern
1269 to a given recipient.
1270 The form of the {\tt message} map is given
1271 in Section \ref{sect:msg-encode}.
1272 An error results if the recipient is not subscribed to the message's
1273 MType, or if the invoking client is not Callable.
1274 \\
1275 \item \verb|map calls = callAll(string msg-tag, map message)|\\
1276 Sends a message using the Asynchronous Call/Response pattern
1277 to all other clients which are subscribed to the message's MType.
1278 The form of the {\tt message} map is given
1279 in Section \ref{sect:msg-encode}.
1280 The returned value is a {\tt map} in which the keys are the client IDs
1281 of clients to which an attempt to send the message is made,
1282 and the values are the associated {\tt msg-id} strings.
1283 An error results if the invoking client is not Callable.
1284 \\
1285 \item \verb|map response = callAndWait(string recipient-id,|\\
1286 \verb| map message, string timeout)|\\
1287 Sends a message using the Synchronous Call/Response pattern
1288 to a given recipient.
1289 The forms of the {\tt message} and {\tt response} maps are given
1290 in Sections \ref{sect:msg-encode} and \ref{sect:response-encode}.
1291 The {\tt timeout} parameter is interpreted as a {\em SAMP int\/}
1292 (Section \ref{sect:scalar-types}) giving
1293 the maximum number of seconds the client wishes to wait.
1294 If the response takes longer than that to arrive this method SHOULD
1295 terminate anyway with an error (it MUST not return a {\tt response} indicating
1296 error).
1297 Any response arriving from the recipient after that will be discarded.
1298 If {\tt timeout}$<=0$ then no artificial timeout is imposed.
1299 An error results if the recipient is not subscribed to the message's
1300 MType.
1301 \\
1302 \item \verb|reply(string msg-id, map response)|\\
1303 Method
1304 called by a client to send its response to a given message.
1305 The form of the {\tt response} map is given
1306 in Section \ref{sect:response-encode}.
1307 \end{itemize}
1309 Of these operations, only {\tt callAndWait()} involves blocking communication
1310 with another client.
1311 The others SHOULD be implemented in such a way that clients can expect
1312 them to complete, and where appropriate return a value, on a timescale
1313 short compared to user response time.
1315 \subsection{Operations a Callable Client Must Support}
1316 \label{sect:clientOps}
1318 This section lists the operations which a client MUST support in order
1319 to be classified as callable.
1320 The hub uses these operations when it wishes to
1321 pass information to a callable client.
1322 Note that callability is OPTIONAL for clients; special (Profile-dependent) steps
1323 may be required for a client to inform the hub how it can be contacted,
1324 and thus become callable. Clients which are not callable can send
1325 messages using the Notify or Synchronous Call/Response patterns,
1326 but are unable to receive messages or to use Asynchronous Call/Response,
1327 since these operations rely on client callbacks from the hub.
1329 The precise details of how these operations
1330 map onto method names and signatures is Profile-dependent.
1331 The mapping for
1332 the Standard Profile is given in Section \ref{sect:mappingXMLRPC}
1333 and for the Web Profile in Section \ref{sect:web-callable}.
1334 \begin{itemize}
1335 \item \verb|receiveNotification(string sender-id, map message)|\\
1336 Method called by the hub when dispatching a notification to its
1337 recipient.
1338 The form of the {\tt message} map is given
1339 in Section \ref{sect:msg-encode}.
1340 \\
1341 \item \verb|receiveCall(string sender-id, string msg-id, map message)|\\
1342 Method called by the hub when dispatching a call to its recipient. The client
1343 MUST at some later time make a matching call to {\tt reply()} on the hub.
1344 The form of the {\tt message} map is given
1345 in Section \ref{sect:msg-encode}.
1346 \\
1347 \item \verb|receiveResponse(string responder-id, string msg-tag,|\\
1348 \verb| map response)|\\
1349 Method used by the hub to dispatch to the sender the response of an
1350 earlier asynchronous call.
1351 The form of the {\tt response} map is given
1352 in Section \ref{sect:response-encode}.
1353 \end{itemize}
1355 \subsection{Error Processing}
1356 \label{sect:faults}
1358 Errors encountered by clients when processing Call/Response-pattern messages
1359 themselves (in response to a syntactically legal {\tt receiveCall()}
1360 operation) SHOULD be signalled by returning appropriate content in
1361 the response map sent back in the matching {\tt reply()} call,
1362 as described in Section \ref{sect:response-encode}.
1364 In the case of failed calls of
1365 the operations defined in Sections \ref{sect:hubOps} and \ref{sect:clientOps},
1366 for instance syntactically invalid parameters or communications failures,
1367 hubs and clients SHOULD where possible use the usual error reporting
1368 mechanisms of the transport protocol in use.
1370 Where it is problematic or impossible to use the transport protocol's
1371 error reporting mechanisms, in the case of a Call/Response pattern message,
1372 the hub MAY signal errors by generating and passing back
1373 to the sender a suitable response map as described in Section
1374 \ref{sect:response-encode}.
1378 %% Mark Taylor's part %%
1379 \section{Standard Profile}
1380 \label{sect:profile}
1383 Section \ref{sect:apis} provides an abstract definition of
1384 the operations and data structures used for SAMP messaging.
1385 As explained in Section~\ref{sect:profiles},
1386 in order to implement this architecture some concrete choices about
1387 how to instantiate these concepts are required.
1389 This section gives the details of a SAMP Profile based on the
1390 XML-RPC specification \cite{xmlrpc}.
1391 Hub discovery is via a lockfile in the user's home directory.
1393 XML-RPC is a simple general purpose Remote Procedure Call
1394 protocol based on sending XML documents using HTTP POST
1395 (it resembles a very lightweight version of SOAP).
1396 Since the mappings from SAMP concepts
1397 such as API calls and data types to their XML-RPC equivalents is very
1398 straightforward, it is easy for application authors to write
1399 compliant code without use of any SAMP-specific library code.
1400 An XML-RPC library, while not essential, will make coding much easier;
1401 such libraries are available for many languages.
1404 \subsection{Data Type Mappings}
1405 \label{sect:profile-typemap}
1407 The SAMP argument and return value data types described in
1408 Section \ref{sect:samp-data-types} map straightforwardly onto XML-RPC
1409 data types as follows:
1410 \begin{center}
1411 \begin{tabular}{lcl}
1412 SAMP type & & XML-RPC element \\
1413 \hline
1414 {\tt string} & --- & {\tt <string>} \\
1415 {\tt list} & --- & {\tt <array>} \\
1416 {\tt map} & --- & {\tt <struct>} \\
1417 \end{tabular}
1418 \end{center}
1419 The {\tt <value>} children of {\tt <array>} and {\tt <struct>} elements
1420 themselves contain children of type {\tt <string>}, {\tt <array>} or
1421 {\tt <struct>}.
1423 Note that other XML-RPC scalar types ({\tt <i4>}, {\tt <double>} etc)
1424 are not used; even where the semantic sense of a value matches
1425 one of those types it MUST be encoded as an XML-RPC {\tt <string>}.
1428 \subsection{API Mappings}
1429 \label{sect:mappingXMLRPC}
1431 The operation names in the SAMP hub and client abstract APIs
1432 (Sections \ref{sect:hubOps} and \ref{sect:clientOps}) very nearly
1433 have a one to one mapping with those in the Standard Profile XML-RPC APIs.
1434 The Standard Profile API MUST be implemented as described in Sections
1435 \ref{sect:hubOps} and \ref{sect:clientOps} with the following REQUIRED adjustments:
1436 \begin{enumerate}
1437 \item The XML-RPC method names (i.e.\ the contents of the XML-RPC
1438 {\tt <methodName>} elements) are formed by
1439 prefixing the hub and client abstract API operation names with
1440 ``{\tt samp.hub.}'' or ``{\tt samp.client.}'' respectively.
1441 \item The {\tt register()} operation takes the following form:
1442 \begin{itemize}
1443 \item \verb|map reg-info = register(string samp-secret)|
1444 \end{itemize}
1445 The argument is the {\tt samp-secret} value read from the lockfile
1446 (see Section \ref{sect:lockfile}).
1447 The returned {\tt reg-info} map contains an additional entry
1448 with key {\tt samp.private-key} whose value is a string
1449 generated by the hub.
1450 \item {\em All\/} other hub and client methods take the
1451 {\tt private-key} as their first argument.
1452 \item A new method, {\tt setXmlrpcCallback()} is added to the hub API.
1453 \begin{itemize}
1454 \item \verb|setXmlrpcCallback(string private-key, string url)|
1455 \end{itemize}
1456 This informs the hub of the XML-RPC endpoint on which the client
1457 is listening for calls from the hub.
1458 The client is not considered Callable unless and until
1459 it has invoked this method.
1460 \item Another new method, {\tt ping()} is added to the hub API.
1461 This may be called by registered or unregistered applications
1462 (as a special case the {\tt private-key} argument may be omitted),
1463 and can be used to determine whether the hub is responding to requests.
1464 Any non-error return indicates that the hub is running.
1465 \end{enumerate}
1467 The {\tt private-key} string referred to above serves two purposes.
1468 First it identifies the client in hub/client communications.
1469 Some such identifier is required, since XML-RPC calls have no other way of
1470 determining the sender's identity.
1471 Second, it prevents application spoofing, since the private key is
1472 never revealed to other applications, so that one application cannot
1473 pose as another in making calls to the hub.
1475 The usual XML-RPC fault mechanism is used to respond to invalid
1476 calls as described in Section \ref{sect:faults}.
1477 The XML-RPC {\tt <fault>}'s {\tt <faultString>} element SHOULD contain a
1478 user-directed message as appropriate and the {\tt <faultCode>} value
1479 has no particular significance.
1482 \subsection{Lockfile and Hub Discovery}
1483 \label{sect:lockfile}
1485 Hub discovery is performed by examining a lockfile to determine
1486 hub connection parameters, specifically the XML-RPC endpoint at
1487 which the hub can be found, and a ``secret'' token which affords
1488 some measure of security, given suitable restrictions on the
1489 lockfile's readability (see Section \ref{sect:std-security}).
1490 To discover the hub, a client must
1491 therefore:
1492 \begin{enumerate}
1493 \item Determine where to find the lockfile
1494 (\ref{sect:lockfileLoc})
1495 \item Read the lockfile to obtain the hub connection parameters
1496 (\ref{sect:lockfileText})
1497 \end{enumerate}
1499 \subsubsection{Lockfile Location}
1500 \label{sect:lockfileLoc}
1502 The default location of the lockfile is the file named ``{\tt .samp}''
1503 in the user's home directory. However the content of the environment
1504 variable named SAMP\_HUB can be used to override this default.
1506 The value of the SAMP\_HUB environment variable is of the form
1507 \verb|<samphub-value>|, as defined by the following BNF production:
1508 \begin{verbatim}
1509 <samphub-value> ::= <hub-location>
1510 <hub-location> ::= <stdlock-prefix> <stdlock-url>
1511 <lockurl-prefix> ::= "std-lockurl:"
1512 <stdlock-url> ::= (any URL)
1513 \end{verbatim}
1514 The \verb|<stdlock-url>| will typically, but not necessarily, be a
1515 file-type URL (as described in RFC 1738, section 3.10 \cite{rfc1738}).
1516 So for instance to indicate that the
1517 lockfile to be used will be the file ``{\tt /tmp/samp1}'', you would set
1518 \begin{verbatim}
1519 SAMP_HUB=std-lockurl:file:///tmp/samp1
1520 \end{verbatim}
1522 Although no other form of the \verb|<hub-location>| value is defined
1523 here, the intention is that the SAMP\_HUB environment variable MAY
1524 be used with prefixes other than ``{\tt std-lockurl:}'' to indicate
1525 use of other, non-Standard, profiles.
1526 Issues may in future arise related to the need to indicate multiple
1527 profiles or profile variants at once; the impact of this requirement
1528 on the syntax and semantics of the SAMP\_HUB variable is for now
1529 deferred.
1531 To locate the lockfile therefore, a Standard Profile-compliant client MUST
1532 determine whether an environment variable named SAMP\_HUB exists;
1533 if so, the client MUST examine the variable's value;
1534 if the value begins with the prefix ``{\tt std-lockurl:}''
1535 the client MUST interpret the remainder of the value as a URL
1536 whose content is the text of the lockfile to be used for hub discovery.
1537 If no SAMP\_HUB environment variable exists, the client MUST
1538 use the file ``.samp'' in the user's home directory as the
1539 lockfile to be used for hub discovery.
1540 If the variable exists, but its value begins with a different prefix,
1541 the client MAY interpret that in some non-Standard way for hub discovery.
1543 Rules for a Standard Profile-compliant hub to use when writing lockfiles
1544 are similar, but if a hub is unable or unwilling to write a lockfile
1545 such that it can be read using the above procedure, it MUST signal
1546 an error at the startup and then abort. For practical reasons, a hub
1547 will probably only be able to write a lockfile indicated by a {\tt file}-type
1548 URL, not for instance an arbitrary {\tt http}-type one.
1549 Lockfiles SHOULD be created with appropriate access restrictions
1550 as discussed in Section \ref{sect:std-security}.
1552 The existence or readability of the lockfile MAY be taken
1553 (e.g.\ by a hub deciding whether to start or not)
1554 to indicate that a hub is running.
1555 However it is RECOMMENDED to attempt to contact the hub
1556 at the given XML-RPC URL (e.g.\ by calling {\tt ping()})
1557 to determine whether it is actually alive.
1559 The ``home directory'' referred to above is a somewhat system-dependent
1560 concept: we define it as the value of the {\tt HOME} environment variable on
1561 Unix-like systems and as the value of the {\tt USERPROFILE} environment
1562 variable on Microsoft Windows\footnote{
1563 Note to Java developers: contrary to what you might expect,
1564 the {\tt user.home} system property on Windows does {\em not} give you the
1565 value of {\tt USERPROFILE}.
1566 See \url{http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4787931}.
1567 }.
1568 ``Environment variable'' is itself potentially a system-dependent concept,
1569 but it is clear how to interpret it for all platforms on which we
1570 currently expect SAMP to be used, so no further explanation is provided
1571 here.
1573 In version 1.11 of the standard, the lockfile was always in the
1574 ``{\tt .samp}'' file in the user's home directory.
1575 The option of setting the SAMP\_HUB environment variable to override
1576 this has been introduced to allow more flexibility;
1577 for instance one user can run multiple unconnected hubs,
1578 or multiple users can share the same hub.
1579 If no SAMP\_HUB environment variable is defined, client and hub
1580 behaviour is exactly as in version 1.11.
1582 \subsubsection{Security Considerations}
1583 \label{sect:std-security}
1585 The hub SHOULD normally create the lockfile with file permissions which allow
1586 only its owner to read it. This provides a measure of security in
1587 that only processes with the same privileges as the hub process
1588 (hence presumably running under the same user ID) will be able to
1589 register with the hub, since only they will be able to provide the
1590 secret token, obtained from the lockfile, which is required for registration.
1591 Thus under normal circumstances all Standard Profile clients can be
1592 presumed to be running with the same level of trust, so that
1593 no security issues of the type discussed in Section \ref{sect:security}
1594 arise.
1596 If the lockfile is made available in some way other than an
1597 owner-only readable file, for instance via
1598 an unprotected {\tt http}-type URL in order to facilitate use of
1599 the same hub by multiple users on different hosts, there is a potential
1600 security risk. In that case, protection through an authentication and/or
1601 authorization mechanism might be adopted by the hub implementations, for
1602 instance exploiting the TLS cryptographic protocol \cite{rfc2246}.
1604 \subsubsection{Lockfile Content}
1605 \label{sect:lockfileText}
1607 The format of the lockfile is given by the following BNF productions:
1608 \begin{verbatim}
1609 <file> ::= <lines>
1610 <lines> ::= <line> | <lines> <line>
1611 <line> ::= <line-content> <EOL> | <EOL>
1612 <line-content> ::= <comment> | <assignment>
1613 <comment> ::= "#" <any-string>
1614 <assignment> ::= <name> "=" <any-string>
1615 <name> ::= <token-string>
1616 <token-string> ::= <token-char> | <token-string> <token-char>
1617 <any-string> ::= <any-char> | <any-string> <any-char>
1618 <EOL> ::= "\r" | "\n" | "\r" "\n"
1619 <token-char> ::= [a-zA-Z0-9] | "-" | "_" | "."
1620 <any-char> ::= [\x20-\x7f]
1621 \end{verbatim}
1622 The only parts which are significant to SAMP clients/hubs are
1623 (a) existence of the file and (b) {\tt <assignment>} lines.
1625 A legal lockfile MUST provide (in any order) unique assignments for the
1626 following tokens:
1627 \begin{description}
1628 \item[{\tt samp.secret}] ---
1629 An opaque text string which must be passed to the hub to permit
1630 registration.
1631 \item[{\tt samp.hub.xmlrpc.url}] ---
1632 The XML-RPC endpoint for communication with the hub.
1633 \item[{\tt samp.profile.version}] ---
1634 The version of the SAMP Standard Profile implemented by the hub
1635 (``\sampversion'' for the version described by this document).
1636 \end{description}
1637 These keys form the basis of an extensible vocabulary as explained in
1638 Section \ref{sect:vocab}.
1639 Other blank, comment or assignment lines may be included as desired.
1641 An example lockfile might therefore look like this:
1642 \begin{quote}\tt
1643 \# SAMP lockfile written 2011-12-22T05:30:01 \\
1644 \# Required keys: \\
1645 samp.secret=734144fdaab8400a1ec2 \\
1646 samp.hub.xmlrpc.url=http://andromeda.star.bris.ac.uk:8001/xmlrpc \\
1647 samp.profile.version=\sampversion \\
1648 \# Info stored by hub for some private reason: \\
1649 com.yoyodyne.hubid=c80995f1
1650 \end{quote}
1652 \subsubsection{Hub Discovery Sequences}
1654 The hub discovery sequences are therefore as follows:
1656 \begin{itemize}
1657 \item Client startup:
1658 \begin{itemize}
1659 \item Determine hub existence as above
1660 \item If no hub, client MAY start its own hub
1661 \item Acquire {\tt samp.secret} value from lockfile
1662 \item If pre-existing or own hub is running, call {\tt register()} and
1663 zero or more of {\tt setXmlrpcCallback()}, {\tt declareMetadata()},
1664 {\tt declareSubscriptions()}
1665 \end{itemize}
1666 \item Hub startup:
1667 \begin{itemize}
1668 \item Determine hub existence as above
1669 \item If hub is running, exit
1670 \item Otherwise, start up XML-RPC server
1671 \item Write lockfile containing mandatory assignments including
1672 XML-RPC endpoint, using appropriate access restrictions
1673 \end{itemize}
1674 \item Hub shutdown:
1675 \begin{itemize}
1676 \item Remove lockfile (it is RECOMMENDED to first check that this
1677 is the lockfile written by self)
1678 \item Notify candidate clients that shutdown will occur
1679 \item Shut down services
1680 \end{itemize}
1681 \end{itemize}
1683 A hub implementation SHOULD make its best effort to perform the
1684 shutdown sequence above even if it terminates as a result of some
1685 error condition.
1687 Note that manipulation of a file is not atomic, so that race conditions
1688 are possible. For instance a client or hub examining the lockfile
1689 may read it after it has been created but before it has been populated
1690 with the mandatory assignments, or two hubs may look for a lockfile
1691 simultaneously, not find one, and both decide that they should
1692 therefore start up, one presumably overwriting the other's lockfile.
1693 Hub and client implementations should be aware of such possibilities,
1694 but may not be able to guarantee to avoid them or their consequences.
1695 In general this is the sort of risk that SAMP and its
1696 Standard Profile are prepared to take --- an eventuality which will occur
1697 sufficiently infrequently that it is not worth significant
1698 additional complexity to avoid.
1699 In the worst case a SAMP session may fail in some way, and will have
1700 to be restarted manually.
1703 \subsection{Examples}
1705 Here is an example in pseudo-code of how an application might locate and
1706 register with a hub, and send a message requiring no response to other
1707 registered clients.
1708 {\examplesize
1709 \begin{verbatim}
1710 # Locate and read the lockfile.
1711 string hubvar-value = readEnvironmentVariable("SAMP_HUB");
1712 string lock-location = getLockfileLocation(hubvar-value);
1713 map lock-info = readLockfile(lock-location);
1715 # Extract information from lockfile to locate and register with hub.
1716 string hub-url = lock-info.getValue("samp.hub.xmlprc.url");
1717 string samp-secret = lock-info.getValue("samp.secret");
1719 # Establish XML-RPC connection with hub
1720 # (uses some generic XML-RPC library)
1721 xmlrpcServer hub = xmlrpcConnect(hub-url);
1723 # Register with hub.
1724 map reg-info = hub.xmlrpcCall("samp.hub.register", samp-secret);
1725 string private-key = reg-info.getValue("samp.private-key");
1727 # Store metadata in hub for use by other applications.
1728 map metadata = ("samp.name" -> "dummy",
1729 "samp.description.text" -> "Test Application",
1730 "dummy.version" -> "0.1-3");
1731 hub.xmlrpcCall("samp.hub.declareMetadata", private-key, metadata);
1733 # Send a message requesting file load to all other
1734 # registered clients, not wanting any response.
1735 map loadParams = ("filename" -> "/tmp/foo.bar");
1736 map loadMsg = ("samp.mtype" -> "file.load",
1737 "samp.params" -> loadParams);
1738 hub.xmlrpcCall("samp.hub.notifyAll", private-key, loadMsg);
1740 # Unregister
1741 hub.xmlrpcCall("samp.hub.unregister", private-key);
1742 \end{verbatim}
1743 }
1745 The first few XML-RPC documents sent over the wire for this exchange
1746 would look something like the following.
1747 The registration call from the client to the hub:
1748 {\examplesize
1749 \begin{verbatim}
1750 POST /xmlrpc HTTP/1.0
1751 User-Agent: Java/1.5.0_10
1752 Content-Type: text/xml
1753 Content-Length: 189
1755 <?xml version="1.0"?>
1756 <methodCall>
1757 <methodName>samp.hub.register</methodName>
1758 <params>
1759 <param><value><string>734144fdaab8400a1ec2</string></value></param>
1760 </params>
1761 </methodCall>
1762 \end{verbatim}
1763 }
1764 which leads to the response:
1765 {\examplesize
1766 \begin{verbatim}
1767 HTTP/1.1 200 OK
1768 Connection: close
1769 Content-Type: text/xml
1770 Content-Length: 464
1772 <?xml version="1.0"?>
1773 <methodResponse>
1774 <params><param><value><struct>
1775 <member>
1776 <name>samp.private-key</name>
1777 <value><string>client-key:1a52fdf</string></value>
1778 </member>
1779 <member>
1780 <name>samp.hub-id</name>
1781 <value><string>client-id:0</string></value>
1782 </member>
1783 <member>
1784 <name>samp.self-id</name>
1785 <value><string>client-id:4</string></value>
1786 </member>
1787 </struct></value></param></params>
1788 </methodResponse>
1789 \end{verbatim}
1790 }
1791 The client can then declare its metadata:
1792 the response to this call has no useful content so can be ignored or discarded.
1793 {\examplesize
1794 \begin{verbatim}
1795 POST /xmlrpc HTTP/1.0
1796 User-Agent: Java/1.5.0_10
1797 Content-Type: text/xml
1798 Content-Length: 600
1800 <?xml version="1.0"?>
1801 <methodCall>
1802 <methodName>samp.hub.declareMetadata</methodName>
1803 <params>
1804 <param><value><string>app-id:1a52fdf-2</string></value></param>
1805 <param><value><struct>
1806 <member>
1807 <name>samp.name</name>
1808 <value><string>dummy</string></value>
1809 </member>
1810 <member>
1811 <name>samp.description.text</name>
1812 <value><string>Test application</string></value>
1813 </member>
1814 <member>
1815 <name>dummy.version</name>
1816 <value><string>0.1-3</string></value>
1817 </member>
1818 </struct></value></param>
1819 </params>
1820 </methodCall>
1821 \end{verbatim}
1822 }
1823 The message itself is sent from the client to the hub as follows:
1824 {\examplesize
1825 \begin{verbatim}
1826 POST /xmlrpc HTTP/1.0
1827 User-Agent: Java/1.5.0_10
1828 Content-Type: text/xml
1829 Content-Length: 523
1831 <?xml version="1.0"?>
1832 <methodCall>
1833 <methodName>samp.hub.notifyAll</methodName>
1834 <params>
1835 <param><value><string>app-id:1a52fdf-2</string></value></param>
1836 <param><value><struct>
1837 <member>
1838 <name>samp.mtype</name>
1839 <value>file.load</value>
1840 </member>
1841 <member>
1842 <name>samp.params</name>
1843 <value><struct>
1844 <name>filename</name>
1845 <value>/tmp/foo.bar</value>
1846 </struct></value>
1847 </member>
1848 </struct></value></param>
1849 </params>
1850 </methodCall>
1851 \end{verbatim}
1852 }
1853 Again, there is no interesting response.
1856 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1857 \section{Web Profile}
1858 \label{sect:webprofile}
1860 This section defines the SAMP Web Profile
1861 which allows web applications
1862 to communicate with a SAMP hub.
1863 A {\em web application\/} in this context is code which is downloaded
1864 by a web browser from a remote server, usually as part of a web page,
1865 and which then runs from within that browser.
1866 The most common platforms (browser-based runtime environments) for such
1867 applications are currently JavaScript (a.k.a.\ JScript, ECMAScript),
1868 Java applets, Adobe Flash, and Microsoft Silverlight.
1869 For security reasons, these runtime environments run the web applications
1870 that they host inside a secure ``sandbox'', which imposes restrictions
1871 on access to resources, making it impossible to use the Standard Profile
1872 defined in Section \ref{sect:profile}.
1873 Java applets provide a client-controlled cross-browser mechanism,
1874 based on code signing, for circumventing these restrictions,
1875 but the others do not.
1877 Section \ref{sect:web-overview} gives an illustrative overview of the
1878 way the Web Profile achieves its communication requirements,
1879 with comparison to the Standard Profile.
1880 Section \ref{sect:web-hub} describes in detail how the Web Profile hub
1881 is implemented in order to provide the functionality defined by
1882 the SAMP abstract hub and client APIs
1883 (Sections \ref{sect:hubOps} and \ref{sect:clientOps}).
1884 Section \ref{sect:web-client} outlines the steps that a Web Profile client
1885 must take to locate and communicate with the hub.
1886 The important topic of the security implications of this scheme,
1887 and measures which hub implementations can take in view of these,
1888 is covered separately in Section \ref{sect:web-security}.
1891 \subsection{Overview and Comparison with Standard Profile}
1892 \label{sect:web-overview}
1894 The Web Profile is based on the Standard Profile
1895 (Section \ref{sect:profile}), but with some
1896 modifications which allow clients to overcome
1897 the restrictions imposed by the browser sandbox.
1899 Browser restrictions present four main problems for a web-based SAMP client:
1900 hub discovery, outward hub communication, inward hub communication and
1901 use of third-party URLs.
1902 These are solved in the Web Profile by use of a well-known port,
1903 use of standard and de facto cross-origin access techniques,
1904 reversed HTTP communication,
1905 and URL proxying.
1906 These solutions are described, with comparison to the approaches
1907 used by the Standard Profile, in the following subsections.
1910 \subsubsection{Hub Discovery}
1912 A Standard Profile client locates the hub by reading a ``lockfile''
1913 at a well-known location in the filesystem, which provides the HTTP
1914 endpoint at which the hub XML-RPC server is listening and a token
1915 which the client must present in order to register.
1916 Web applications have no access to the local filesystem and so
1917 are unable to read such a lockfile.
1919 In the Web profile, the hub HTTP server listens instead
1920 on a well-known port on the local host.
1921 The hub will apply some security measures at registration time
1922 (Section \ref{sect:web-sec-reg}),
1923 but they are not based on presentation of a secret token.
1925 Note that since this well-known port number is fixed,
1926 it is not possible for more than one Web Profile hub to run on
1927 the same host. The Web Profile Hub and corresponding web browser
1928 MUST run on the same host, and SHOULD always be run by the same user.
1930 For a web client to be able to access this well-known port at all,
1931 the cross-origin techniques discussed in the next section are required.
1934 \subsubsection{Outward Communications}
1936 In the Standard Profile, all hub communication is done using the HTTP-based
1937 XML-RPC protocol \cite{xmlrpc}, usually to a port on the local host.
1939 This is problematic for web-based clients, since so-called
1940 ``cross-origin'' or ``cross-domain'' policies
1941 enforced by browsers restrict HTTP access under normal circumstances
1942 so that web applications may {\em only\/} make HTTP requests to
1943 URLs at their own {\em Origin\/} \cite{origin}, that is to URLs on the server
1944 from which the web application itself was downloaded.
1945 This deliberately excludes access to a server on the local host,
1946 which is where the SAMP hub is likely to reside.
1948 Since cross-origin access is a common requirement for web-based clients,
1949 and it is not always in conflict with the security concerns of servers,
1950 a number of platform-dependent but widely-used mechanisms have been
1951 implemented in browser technology
1952 which allow a sandboxed client to talk to an HTTP server
1953 which has explicitly opted in for such cross-origin communications.
1954 A Web Profile hub will implement one or more of these cross-origin
1955 workarounds (Section \ref{sect:web-httpd})
1956 and so permit Web Profile clients running in the
1957 relevant browser runtime environment(s) to make HTTP requests to itself,
1958 thereby allowing client-to-hub XML-RPC calls.
1961 \subsubsection{Inward Communications}
1963 If it wishes to receive as well as send messages, and also to make
1964 asynchronous calls, a SAMP client must declare itself
1965 {\em Callable\/}, by providing the Hub with a profile-dependent means
1966 to invoke the client API defined in Section \ref{sect:clientOps}.
1968 In the Standard Profile a client declares itself Callable by
1969 providing to the Hub an HTTP endpoint to which the Hub may make
1970 XML-RPC requests. Thus, the client must itself run a publicly
1971 accessible HTTP server in order to be callable.
1972 Running an HTTP server is typically not within the capabilities
1973 of a web application.
1975 In the Web Profile, hub-to-client communication is effected by reversing
1976 the direction of the XML-RPC calls, and hence of the HTTP requests.
1977 Instead of the client running a server which listens
1978 for incoming messages from the Hub, the Hub maintains a queue
1979 of messages destined for the client, and the client polls
1980 the Hub to find out if any are available. The client may
1981 either make periodic short-timeout requests to the hub, or
1982 make a long-timeout (``long poll'') request which will
1983 return early if and when one or more messages are available.
1984 This effects inward communications using only the same outward
1985 HTTP capability discussed in the previous section.
1988 \subsubsection{Third-Party URLs}
1990 Although it is not fundamental to the SAMP protocol itself, many
1991 SAMP MTypes are defined in such a way that a receiving client
1992 must retrieve data from a URL external to the SAMP client-hub system in order
1993 to act on them. For instance the {\tt table.load.votable} MType
1994 has an argument named ``{\tt url}'', whose value is the location of
1995 the VOTable document to be loaded. Such URLs may point
1996 to the local filesystem, to a server run by the sending client,
1997 or to some other web server internal or external to the host on
1998 which the SAMP communications are taking place.
1999 Similar considerations apply to some of the client metadata items
2000 (Section \ref{sect:app-metadata}), for instance {\tt samp.icon.url}.
2001 In any of these cases, it is likely that a browser-based client
2002 will be blocked by the browser's cross-origin policy from accessing
2003 the content of the resource in question.
2005 The Web Profile therefore mandates that the Hub must provide to
2006 registered clients a mechanism for translating arbitrary URLs
2007 into cross-origin-accessible URLs with the same content as the
2008 specified resource. Since a hub must already be providing a
2009 cross-origin capable HTTP service accessible from the web client,
2010 it can use the same mechanism to operate a service which proxies
2011 external resources in a cross-origin capable way.
2014 \subsection{Hub Behaviour}
2015 \label{sect:web-hub}
2017 This section specifies in detail the services that a SAMP hub must
2018 provide in order to implement the SAMP Web Profile.
2020 The Web Profile is based on client-to-hub XML-RPC calls,
2021 with the hub residing at a well-known port,
2022 and some special measures for allowing cross-origin requests.
2023 In most ways it resembles the Standard Profile (Section \ref{sect:profile}),
2024 but there are some differences.
2027 \subsubsection{Data Type Mappings}
2029 SAMP argument and return value data types are encoded into XML-RPC
2030 exactly as for the Standard Profile (Section \ref{sect:profile-typemap}).
2033 \subsubsection{API Mappings}
2034 \label{sect:webXMLRPC}
2036 The operation names in the SAMP hub API very nearly have a one to one
2037 mapping with those in the Web Profile XML-RPC API. The Web Profile
2038 Hub API MUST be implemented as described in Section \ref{sect:hubOps},
2039 with a number of REQUIRED adjustments.
2040 These are summarised as follows, and described in more detail later.
2042 \begin{enumerate}
2043 \item The XML-RPC method names (i.e.\ the contents of the XML-RPC
2044 {\tt <methodName>} elements) are formed by prefixing
2045 the hub abstract API operation names with ``{\tt samp.webhub.}''.
2046 For brevity, this prefix is not written in the rest of this document,
2047 but it is to be understood on all hub API XML-RPC calls.
2048 \item The {\tt register} operation takes the following form
2049 (Section \ref{sect:web-registration}):
2050 \begin{itemize}
2051 \item {\tt map reg-info = register(map identity-info)}
2052 \end{itemize}
2053 The {\tt identity-info} is a map containing at least a declared
2054 application name supplied by the registering application to
2055 indicate its identity.
2056 \item The {\tt reg-info} map returned from the {\tt register} method
2057 MUST contain two entries additional to those mandated by the
2058 hub API (Section \ref{sect:web-registration}):
2059 \begin{description}
2060 \item[{\tt samp.private-key}:]
2061 used as the first argument of all hub API XML-RPC calls
2062 \item[{\tt samp.url-translator}:]
2063 used for translation of foreign URLs for cross-origin accessibility
2064 \end{description}
2065 \item {\em All\/} hub methods other than {\tt register}
2066 take the {\tt private-key} as their first argument,
2067 except where otherwise noted ({\tt ping}).
2068 For brevity, this argument is not written in the rest of this document,
2069 but it is to be understood on all hub API calls.
2070 \item Two new methods are added to the hub API to support reversed callbacks
2071 (Section \ref{sect:web-callable}):
2072 \begin{itemize}
2073 \item {\tt allowReverseCallbacks(string allow)}
2074 \item {\tt map pullCallbacks(string timeout)}
2075 \end{itemize}
2076 \item Another new method is added to the hub API:
2077 \begin{itemize}
2078 \item {\tt ping()}
2079 \end{itemize}
2080 This may be called by registered or unregistered applications
2081 (as a special case the {\tt private-key} argument may be omitted),
2082 and can be used to determine whether the hub is responding to requests.
2083 Any non-error return indicates that the hub is running.
2084 \end{enumerate}
2087 \subsubsection{Hub HTTP Server}
2088 \label{sect:web-httpd}
2090 Communications are XML-RPC calls \cite{xmlrpc} from the client to the Hub.
2091 XML-RPC works using POSTs to an HTTP server. The Web Profile hub HTTP
2092 server resides on the well-known port 21012,
2093 so that clients know where to find it on the local host.
2094 The XML-RPC endpoint for Web Profile requests
2095 is at the root of that server, so that web clients can access it by
2096 POSTing to the URL ``{\tt http://localhost:21012/}''.
2098 In general, web applications operate inside a browser-enforced sandbox that
2099 prevents them from accessing cross-origin resources, including HTTP-based ones
2100 served from the local host. However there are a number of ways in which
2101 an HTTP server can elect to permit access from browser-based clients.
2102 In order to be useful a Web Profile hub must implement at
2103 least one of these ``cross-origin workarounds''.
2105 The following cross-origin workarounds are known to exist, and
2106 can be considered for use by Web Profile hub HTTP servers:
2107 \begin{description}
2108 %
2109 \item[Cross-Origin Resource Sharing:]
2110 CORS \cite{cors} is a W3C standard which
2111 works by manipulation of the HTTP Origin header and related headers
2112 by the browser runtime environment and the HTTP server,
2113 allowing the HTTP server to grant
2114 cross-domain access from clients with some or all Origins.
2115 CORS forms part of the XmlHttpRequest Level 2 standard \cite{xhr2},
2116 which is implemented by, at least,
2117 Chrome v2.0+, Firefox v3.5+ and Safari v4.0+.
2118 Microsoft's IE8+ implements CORS via its own non-standard XDomainRequest
2119 object.
2120 This standard belongs to the loose HTML5 family of technologies,
2121 and it is likely that support will become wider in the future.
2122 A Web Profile hub HTTP server can grant unrestricted access
2123 to CORS-aware web applications
2124 by following the instructions in the CORS standard to enable both
2125 {\em simple\/} and {\em preflight\/} requests from clients
2126 with any Origin.
2127 %
2128 \item[Flash cross-domain policy:] Adobe's Flash browser plugin makes
2129 use of a resource named ``{\tt crossdomain.xml}'', which, if present on
2130 an external HTTP server, is taken to indicate willingness to serve
2131 cross-domain requests \cite{flash-crossdomain}.
2132 This has emerged as something of a de facto standard, and the
2133 crossdomain file is honoured by Silverlight and unsigned Java
2134 Applets/WebStart applications\footnote{Support for the crossdomain.xml
2135 file is reportedly implemented in Java v1.6.0\_10 and later,
2136 see \url{http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6676256}.}
2137 as well as for Flash applications.
2138 A Web Profile hub HTTP server can grant unrestricted access
2139 to Flash-like web applications
2140 by serving a resource named ``{\tt /crossdomain.xml}''
2141 with a Content-Type header of
2142 ``{\tt text/x-cross-domain-policy}'' and content like:
2143 {\footnotesize\begin{verbatim}
2144 <?xml version="1.0"?>
2145 <!DOCTYPE cross-domain-policy
2146 SYSTEM "http://www.adobe.com/xml/dtds/cross-domain-policy.dtd">
2147 <cross-domain-policy>
2148 <site-control permitted-cross-domain-policies="all"/>
2149 <allow-access-from domain="*"/>
2150 <allow-http-request-headers-from domain="*" headers="*"/>
2151 </cross-domain-policy>
2152 \end{verbatim}}
2153 %
2154 \item[Silverlight cross-domain policy:]
2155 Microsoft's Silverlight environment will take note of Flash-style
2156 {\tt crossdomain.xml} files, so the above measure ought to permit
2157 Silverlight clients to access a compliant HTTP server. However,
2158 Silverlight has its own cross-domain policy mechanism
2159 \cite{silverlight-crossdomain}, which may be implemented in addition.
2160 A Web Profile hub HTTP server can grant unrestricted access
2161 to Silverlight web applications
2162 by serving a resource named ``{\tt /clientaccesspolicy.xml}''
2163 with a Content-Type header of ``{\tt text/xml}'' and content like:
2164 {\footnotesize\begin{verbatim}
2165 <?xml version="1.0"?>
2166 <access-policy>
2167 <cross-domain-access>
2168 <policy>
2169 <allow-from>
2170 <domain uri="http://*"/>
2171 </allow-from>
2172 <grant-to>
2173 <resource path="/" include-subpaths="true"/>
2174 </grant-to>
2175 </policy>
2176 </cross-domain-access>
2177 </access-policy>
2178 \end{verbatim}}
2179 \end{description}
2181 If the hub implements these cross-origin workarounds
2182 it is believed that cross-origin access, hence Web Profile SAMP access,
2183 can be provided from nearly all browsers.
2184 Most modern browsers support CORS for JavaScript,
2185 nearly all others support Flash,
2186 and it is possible for JavaScript applications to
2187 make use of Flash libraries for their
2188 SAMP communications\footnote{See for instance the
2189 flXHR library at \url{http://flxhr.flensed.com/}.
2190 }.
2191 Maximum interoperability therefore can be achieved by
2192 implementing all of these, or at least CORS and Flash,
2193 in the Web Profile HTTP server.
2194 There are however security implications of which ones to implement,
2195 discussed in Section \ref{sect:web-sec-confirm}.
2197 In the usual browser-hub configuration,
2198 web applications will always seek the Web Profile HTTP server on the
2199 local host.
2200 Since no legitimate use of the Web Profile HTTP server is expected
2201 from non-local hosts, it is therefore strongly RECOMMENDED for
2202 security reasons that the Web Profile HTTP server refuses
2203 HTTP requests from external hosts with a 403 Forbidden status.
2204 This recommendation and possible exceptions to it are discussed
2205 further in Section \ref{sect:web-sec-host}.
2207 \subsubsection{Registration}
2208 \label{sect:web-registration}
2210 In order to request registration with the Web Profile, a client needs
2211 to invoke the following XML-RPC method:
2212 \begin{verbatim}
2213 map register(map identity-info)
2214 \end{verbatim}
2215 The {\tt identity-info} map provides information identifying the
2216 registering application which can inform the
2217 hub's decision about whether to allow registration.
2218 It has the following REQUIRED entry:
2219 \begin{description}
2220 \item[{\tt samp.name}] ---
2221 A {\tt string} giving the name of the application wishing to register,
2222 in a form that can be presented to the user.
2223 This SHOULD be the same as the value of the {\tt samp.name} key in the
2224 application metadata as described in Section \ref{sect:app-metadata}.
2225 \end{description}
2226 Particular implementations or future versions of this standard
2227 may specify additional required or optional entries to this map.
2229 The hub will accept or reject the registration based on the contents of
2230 the {\tt identity-info} map, available information from the HTTP connection
2231 carrying the XML-RPC call, user confirmation,
2232 and the hub's own security policy, as discussed in \ref{sect:web-sec-reg}.
2233 The {\tt register} XML-RPC request will not return until the
2234 hub has decided whether to accept registration.
2235 This decision may involve user interaction and hence take a significant
2236 amount of time.
2237 The likely timescales mean that an HTTP timeout is possible
2238 but not very probable; in case of a timeout, registration fails.
2240 If registration is accepted, the hub MUST return to the client
2241 a SAMP map containing the entries mandated by Section \ref{sect:registration}
2242 and also the following entries:
2244 \begin{description}
2245 \item[{\tt samp.private-key}:]
2246 The value of this key is a string which identifies the registered client.
2247 This string SHOULD be difficult for third parties to guess.
2248 This arrangement is the same as for the Standard Profile
2249 (Section \ref{sect:mappingXMLRPC})
2250 \item[{\tt samp.url-translator}:]
2251 The value of this key is a string which forms the base for a URL
2252 proxying service, used as described in Section \ref{sect:web-urltrans}
2253 \end{description}
2255 If registration is rejected, the hub MUST return to the client
2256 an XML-RPC Fault, which SHOULD have a suitably explanatory
2257 {\tt faultString}.
2260 \subsubsection{Callable Clients}
2261 \label{sect:web-callable}
2263 In order to be able to receive communications (incoming messages and
2264 asynchronous call replies) {\em from\/} the hub, the Web Profile
2265 provides for the client to be able to poll the hub server for any
2266 messages or replies which are ready for receipt.
2267 In this way, such communications
2268 are pulled by the client rather than being pushed by the hub, so that
2269 no server component is required on the client side.
2271 Two hub methods are provided to implement this:
2272 \begin{itemize}
2273 \item {\tt allowReverseCallbacks(string allow)}
2274 \item {\tt list pullCallbacks(string timeout-secs)}
2275 \end{itemize}
2276 Both these methods, like the others in the interface, are named with the
2277 {\tt samp.webhub.} prefix and take the {\tt private-key} as an additional
2278 first argument.
2280 The {\tt allow} argument of {\tt allowReverseCallbacks} is a
2281 {\em SAMP boolean\/} (``0'' for false or ``1'' for true), and
2282 the {\tt timeout-secs} argument of {\tt pullCallbacks} is a {\em SAMP int}
2283 (see Section \ref{sect:scalar-types}).
2285 If a client intends at some time in the future to poll for callbacks
2286 it MUST invoke {\tt allowReverseCallbacks} with a true argument.
2287 If at some later point it decides that it will remain registered but
2288 will never poll for callbacks again it SHOULD invoke
2289 {\tt allowReverseCallbacks} with a false argument
2290 (most clients will never make this second call).
2291 The client becomes {\em Callable\/} only when it has invoked this
2292 method with a true argument.
2294 Having invoked {\tt allowReverseCallbacks} with a true argument,
2295 the client SHOULD periodically invoke {\tt pullCallbacks} whose
2296 return value gives the details of
2297 any callbacks ready for dispatch to the client.
2298 The {\tt timeout-secs} parameter is the maximum number of seconds the
2299 client wishes to wait for a response. When the method is called,
2300 the hub SHOULD wait until at least one callback is available, and
2301 at that point SHOULD return any pending callbacks.
2302 If the elapsed time since {\tt pullCallbacks} was received
2303 exceeds the number of seconds given by the {\tt timeout-secs} argument,
2304 the hub SHOULD return with an empty list of callbacks.
2305 A client may therefore make a non-waiting poll by using a
2306 {\tt timeout-secs} argument of 0.
2307 The hub MAY return with an empty list of callbacks before the
2308 given timeout has elapsed, for instance if it reaches an internal
2309 timeout limit.
2311 The hub MAY discard pending messages before they have been polled for by
2312 the client, for instance to avoid excessive usage of resources to
2313 store them. If a {\tt receiveCall} for an Asynchronous Call/Response-pattern
2314 message is discarded in this way, the hub SHOULD inform the sender by
2315 passing back a {\tt samp.code=samp.noresponse}-type error response,
2316 as described in Section \ref{sect:response-encode}.
2318 The format of the returned value from {\tt pullCallbacks} is a {\tt list}
2319 of elements each of which is a {\tt map} representing a callback
2320 corresponding to one of the methods in the SAMP client API
2321 (Section \ref{sect:clientOps}).
2322 Each of these callbacks is encoded as a {\tt map} with the
2323 following REQUIRED keys:
2324 \begin{description}
2325 \item[{\tt samp.methodName}] ---
2326 The client API method name for the callback.
2327 Its value is a {\tt string} taking one of the values
2328 ``{\tt receiveNotification}'', ``{\tt receiveCall}'' or
2329 ``{\tt receiveResponse}''.
2330 \item[{\tt samp.params}] ---
2331 A {\tt list} of the parameters taken by the client API method in
2332 question, as documented in Section \ref{sect:clientOps}.
2333 \end{description}
2334 These items correspond to the elements present in an XML-RPC call.
2336 Here is an example of a call to {\tt pullCallbacks}.
2337 The client POSTs an XML-RPC call which requests any callbacks
2338 which are currently pending or which
2339 become available during the next 600 seconds:
2340 {\examplesize\begin{verbatim}
2341 POST /
2342 Host: localhost:21012
2343 User-Agent: Mozilla/5.0 (X11; U; Linux i686; en-US; rv:
2344 Gecko/20101028 Red Hat/3.6-2.el5 Firefox/3.6.11
2345 Referer: http://www.star.bris.ac.uk/~mbt/websamp/sample.html
2346 Content-Length: 284
2347 Content-Type: text/plain; charset=UTF-8
2348 Origin: http://www.star.bris.ac.uk
2350 <?xml version='1.0'?>
2351 <methodCall>
2352 <methodName>samp.webhub.pullCallbacks</methodName>
2353 <params>
2354 <param>
2355 <value><string>wk:1_fjlyrdtwtigfqhnwkqokqpbq</string></value>
2356 </param>
2357 <param>
2358 <value><string>600</string></value>
2359 </param>
2360 </params>
2361 </methodCall>
2362 \end{verbatim}}
2363 The response, which is returned by the hub after some delay
2364 between 0 and 600 seconds, specifies a {\tt receiveCall} operation
2365 that the client should respond to:
2366 {\examplesize\begin{verbatim}
2367 200 OK
2368 Content-Length: 1444
2369 Content-Type: text/xml
2370 Access-Control-Allow-Origin: http://www.star.bris.ac.uk
2372 <?xml version='1.0' encoding='UTF-8'?>
2373 <methodResponse>
2374 <params>
2375 <param>
2376 <value>
2377 <array>
2378 <data>
2379 <value>
2380 <struct>
2381 <member>
2382 <name>samp.methodName</name>
2383 <value>samp.webclient.receiveCall</value>
2384 </member>
2385 <member>
2386 <name>samp.params</name>
2387 <value>
2388 <array>
2389 <data>
2390 <value>hub</value>
2391 <value>hub_A_cc55_Ping-tag</value>
2392 <value>
2393 <struct>
2394 <member>
2395 <name>samp.mtype</name>
2396 <value>samp.app.ping</value>
2397 </member>
2398 <member>
2399 <name>samp.params</name>
2400 <value>
2401 <struct>
2402 </struct>
2403 </value>
2404 </member>
2405 </struct>
2406 </value>
2407 </data>
2408 </array>
2409 </value>
2410 </member>
2411 </struct>
2412 </value>
2413 </data>
2414 </array>
2415 </value>
2416 </param>
2417 </params>
2418 </methodResponse>
2419 \end{verbatim}}
2420 Some of the HTTP headers in the outgoing request in this example
2421 have been added outside of the client's control by the browser
2422 runtime environment.
2423 In particular the {\tt Origin} inserted by the browser, and the
2424 {\tt Access-Control-Allow-Origin} provided in response by the Hub,
2425 indicate that CORS negotiation \cite{cors} is in operation
2426 here to allow cross-origin access.
2429 \subsubsection{URL Translation}
2430 \label{sect:web-urltrans}
2432 In order that sandboxed clients are able to obtain the content of
2433 URLs from foreign domains, as is often required by SAMP interoperation,
2434 the hub provides a service which is able to dereference general URLs.
2436 At registration time, as described in Section \ref{sect:web-registration},
2437 one of the values provided to the registering client is that of the
2438 {\tt samp.url-translator} key. This is a partial URL which, when
2439 another URL {\em u1\/} is appended to it, will return the same content as
2440 {\em u1\/} from an HTTP GET request.
2441 If {\em u1} is a syntactically legal URL according to
2442 RFC 2396 \cite{rfc2396}, no additional encoding
2443 needs to be performed on it by the client prior to the concatenation.
2445 A sample of ECMAScript code using this facility might look something
2446 like this:
2447 {\footnotesize\begin{verbatim}
2448 var url_trans = reg_info["samp.url-translator"];
2449 var u1 = msg["samp.params"]["url"]; // base URL received from message
2450 var u2 = url_trans + u1; // URL ready for retrieval
2451 \end{verbatim}}
2453 The partial translator URL might typically be implemented as a URL
2454 pointing to the same HTTP server in which the hub is hosted, with an
2455 empty query part. The content of URLs accessed in this way SHOULD be
2456 available under the same cross-origin arrangements described
2457 in Section \ref{sect:web-httpd}. For security reasons the hub SHOULD ensure
2458 that this facility can only be used by registered clients, for instance
2459 by embedding the private key in the URL. Thus a translator URL might
2460 look something like
2461 \begin{quote}
2462 {\tt http://localhost:21012/translator}/{\sl client-private-key\/}{\tt ?}
2463 \end{quote}
2465 The URL translation service SHOULD in general write an HTTP response
2466 with HTTP headers appropriate for the resource being served,
2467 in accordance with the HTTP version in use (e.g.\ \cite{rfc2616}).
2468 Where the content type of
2469 a resource is not known (which is typical if that resource is backed
2470 by a file rather than an HTTP URI) the HTTP Content-Type header MAY
2471 be omitted.
2473 For security reasons, such a hub URL translation service MAY refuse
2474 access to certain resources, as discussed in Section \ref{sect:web-sec-urls}.
2477 \subsection{Client Behaviour}
2478 \label{sect:web-client}
2480 The steps that a client must take to register with a Web Profile hub and
2481 participate in two-way SAMP communications are as follows:
2482 \begin{enumerate}
2483 \item Prepare to make XML-RPC communications with the XML-RPC endpoint
2484 {\tt http://localhost:21012/}.
2485 Web applications will need to do this using a client which
2486 supports one of the cross-origin workarounds described in
2487 Section \ref{sect:web-httpd} and supported by the Web Profile hub.
2488 \item Call the {\tt register}
2489 XML-RPC method supplying a short application name
2490 and possibly other information in the {\tt identity-info} argument.
2491 If this succeeds (returns a non-Fault XML-RPC response),
2492 the client is registered.
2493 \item If the client wishes to receive as well as send communications
2494 (to be {\em Callable\/}), first call
2495 {\tt allowReverseCallbacks} and then
2496 periodically call {\tt pullCallbacks}.
2497 Call {\tt declareSubscriptions} as required.
2498 \item Act on retrieved callbacks as required.
2499 If any MType argument or return value is a URL,
2500 prefix it with the value of the {\tt samp.url-translator}
2501 entry from the registration map before dereferencing it.
2502 \item Send SAMP messages etc as required.
2503 \item Unregister when no further SAMP activity is required,
2504 either because the user requests disconnection or on
2505 page unload or a similar event.
2506 \end{enumerate}
2509 \subsection{Security Considerations}
2510 \label{sect:web-security}
2512 Web browsers implement cross-origin access restrictions in order to prevent
2513 web applications from activity on a local host which presents
2514 a security risk, for instance reading and writing local files.
2515 This means that, at least in principle, a user can visit a web page
2516 without worrying about security issues, in a way which is not the
2517 case if they download and install an application to run outside
2518 a browser.
2520 The Web Profile described in the preceding subsections however
2521 relies on neutralising these security measures to some extent.
2522 Although it only affects access to a single resource, the HTTP
2523 server on which the Web Profile hub resides, it is potentially serious
2524 since the services provided by the hub can expose sensitive
2525 resources.
2527 Section \ref{sect:web-sec-analysis} below presents an analysis of the risks,
2528 Sections \ref{sect:web-sec-reg} and \ref{sect:web-sec-behave}
2529 outline how they may be mitigated,
2530 and Section \ref{sect:web-sec-summary} summarises the security status of
2531 Web Profile hub deployments in practice.
2533 \subsubsection{Risk Analysis}
2534 \label{sect:web-sec-analysis}
2536 Implementation in the Web Profile of one or more of the sandbox-defeating
2537 cross-origin workarounds described in Section \ref{sect:web-httpd}
2538 allows an untrusted, hence potentially hostile, web application
2539 to make HTTP requests to the Web Profile SAMP hub HTTP server.
2540 In the first instance, there is only one potentially sensitive
2541 action that this access permits: attempting to register
2542 with the SAMP hub. If the registration attempt is denied,
2543 the web application can perform no useful or potentially dangerous
2544 operations (except for a denial of service attack, which sandboxed
2545 web applications are capable of in any case).
2546 If the registration is granted, the client can perform two classes
2547 of sensitive actions: first, exchange SAMP messages with other clients,
2548 and second, use the hub's URL translation service to access
2549 cross-domain URLs which would normally be blocked by the browser.
2551 In order to protect against security breaches related to the
2552 Web Profile therefore, two lines of defence may be established:
2553 first, exercise control over which web applications are
2554 permitted to register, and second, restrict the actions that
2555 registered applications are permitted to take.
2556 These options are explored in the following sections,
2557 \ref{sect:web-sec-reg} and \ref{sect:web-sec-behave} respectively.
2560 \subsubsection{Registration Restrictions}
2561 \label{sect:web-sec-reg}
2563 A running Web Profile implementation may receive requests to register
2564 from any web application running in a local browser, and even some
2565 clients in other categories.
2566 Since not all such applications may be trustworthy, the Web Profile
2567 SHOULD exercise careful control over which ones are permitted to register.
2568 A Web Profile implementation is permitted to make such decisions
2569 in accordance with whatever security policy it deems appropriate,
2570 but it is RECOMMENDED that at least the restrictions described in
2571 the following subsections are considered:
2572 restricting requests to the local host (Section \ref{sect:web-sec-host}),
2573 requiring explicit user confirmation (Section \ref{sect:web-sec-confirm})
2574 and attempting client authentication (Section \ref{sect:web-sec-auth}).
2576 \paragraph{Local Host Restriction}
2577 \label{sect:web-sec-host}
2579 As strongly RECOMMENDED in Section \ref{sect:web-httpd}, registration requests,
2580 and in fact all access to the hub HTTP server, SHOULD under normal
2581 circumstances only be permitted
2582 from the local host. This blocks registration attempts from web or
2583 non-web applications on the internet at large.
2585 Given this restriction, the only applications which may attempt to
2586 register with a hub run by user U are therefore:
2587 \begin{enumerate}
2588 \item web applications running in a browser run by user U on the local host
2589 \item non-web applications run by user U on the local host
2590 \item web or non-web applications run by users other than U on the local host
2591 \end{enumerate}
2592 Type 1 are the applications that the Web Profile is designed to serve.
2593 Type 2 are not what the Web Profile is designed for, since they could
2594 use the Standard Profile instead, but they already have user privileges
2595 so present no additional security risk.
2596 Type 3 are potentially problematic, if the host in question is a
2597 multi-user machine, since they may result in a different user who
2598 is already able to run processes on the local host acquiring access to
2599 the hub-owner's resources (e.g.\ private files).
2600 In practice the User Confirmation step (Section \ref{sect:web-sec-confirm})
2601 should serve to distinguish type 3 from legitimate (type 1) requests,
2602 and the behaviour restrictions described in Section \ref{sect:web-sec-behave}
2603 will limit any potential damage.
2605 There may be circumstances under which it is appropriate to relax this
2606 local host restriction, for instance to enable collaboration with
2607 a known external host not capable of Standard Profile communication,
2608 such as a mobile device operated by the hub user.
2609 However, it is RECOMMENDED that Web Profile implementations at
2610 least restrict access to the local host in their default
2611 configuration, and if access is permitted to external hosts
2612 it is only by explicit user request, and to a named host or
2613 list of hosts.
2614 Opening the well-known Web Profile hub server port to the internet at
2615 large would invite denial of service and perhaps phishing attacks
2616 in which the user is exposed to unwanted SAMP registration
2617 requests.
2619 \paragraph{User Confirmation}
2620 \label{sect:web-sec-confirm}
2622 It is strongly RECOMMENDED that the Hub requires explicit confirmation
2623 from the user before any Web Profile application is allowed to register.
2624 This will normally take the form of the Hub popping up a dialogue window
2625 which requires the user to click ``OK'' or similar for registration to proceed.
2626 An implication of this is that the Web Profile hub must have access to
2627 the same visual display on which the browser is running, which almost
2628 certainly means the hub and the browser are run by the same user.
2630 When enquiring about authorization the hub should make clear to the
2631 user the security implications of accepting the registration request,
2632 and should also present to the user any known information about
2633 the application attempting to register.
2634 Unfortunately, little such information is guaranteed to be available.
2635 The name declared by the application as part of its registration request
2636 will be present, but the application is free to declare any name,
2637 perhaps a misleading one.
2638 Certain HTTP headers on the incoming request may also be relevant:
2639 the ``Origin'' header \cite{origin} will be present for requests
2640 originating from CORS, and
2641 the ``Referer'' header \cite[section 14.36]{rfc2616} may be provided,
2642 though its presence and reliability is dependent on the combination of
2643 browser, platform and cross-origin workaround.
2644 Note that use of non-CORS options might on some browser/plugin
2645 platforms permit faking of HTTP headers\footnote{See for example
2646 \url{http://secunia.com/advisories/22467/},
2647 which refers to a Flash version from 2006.
2648 Hopefully browsers and plugins in current use do
2649 not contain such vulnerabilities,
2650 but an assurance of this is beyond the scope of this document.},
2651 so that if the Web Profile HTTP server implements one of the non-CORS
2652 options alongside CORS this may reduce the reliability of
2653 header information even from HTTP requests which (apparently)
2654 originate from CORS. These headers should therefore be used with care.
2656 Since only the name, which may be chosen at will by the registering
2657 application, is guaranteed present, this looks on the face of it
2658 like a poor basis on which to accept or reject registration by
2659 a potentially hostile web application.
2661 However, in practice the timing of the request presentation provides
2662 the most useful information about the identity and credibility of
2663 the request. A user will only see such a popup dialogue at the time
2664 that a web application attempts to register with SAMP.
2665 This will normally be immediately following a deliberate user browser
2666 action like opening, or clicking a ``Register'' button on, a web page.
2667 If the user trusts the web page he has just interacted with,
2668 he can trust the application within it, and should hence authorize
2669 registration. If the user does not trust the web page he has
2670 just interacted with, or if the popup appears at a time when no
2671 obvious action has been taken to trigger a SAMP registration,
2672 then the user should deny registration.
2673 This pattern of user interaction, requiring authorization based on
2674 the timing of actions in a browser, is both intuitive and familiar
2675 to users; for instance it is used when launching a signed Java applet
2676 or Java WebStart application.
2678 \paragraph{Client Authentication}
2679 \label{sect:web-sec-auth}
2681 As an additional security measure it would be desirable to make a
2682 reliable identification of the author of a web application
2683 by examining an associated digital certificate, with reference
2684 to a list of trusted certificate authorities.
2685 If a certificate reliably associated with the application could be
2686 obtained, this additional information could be presented
2687 to the user or used automatically by the hub to inform the decision
2688 about whether to accept or reject the registration request.
2690 Unfortunately however the content of the actual application is not
2691 available to the Hub at registration time,
2692 so signing the application code will not in itself help.
2694 The Web Profile does not at present therefore make any recommendation
2695 concerning client authentication. Implementations may however
2696 wish to attempt some level of authentication, perhaps by somehow
2697 associating a certificate with the web client's URL or Origin
2698 using the HTTP (or HTTPS) request headers noted in
2699 Section \ref{sect:web-sec-confirm}, or by use of additional
2700 credentials passed in the {\tt identity-info} map.
2703 \subsubsection{Behaviour Restrictions}
2704 \label{sect:web-sec-behave}
2706 Given the restrictions on client registration recommended by
2707 Section \ref{sect:web-sec-reg}, there is a reasonable expectation
2708 that clients registered with the Web Profile will be trustworthy.
2709 However, the possibility remains that user carelessness or
2710 some phishing-like attack might lead to registration of hostile
2711 clients, and so Web Profile implementations may additionally restrict
2712 the behaviour of registered clients.
2713 In general, a Web Profile hub implementation MAY impose such restrictions
2714 as it sees fit, based on its chosen security policy.
2715 This may lead to the inability of some Web Profile clients
2716 to perform some legitimate SAMP operations;
2717 in such cases the hub SHOULD signal that fact to the client
2718 using an appropriate error mechanism.
2720 Restrictions may be applied as described in the following subsections:
2721 restricting the MTypes that may be sent (Section \ref{sect:web-sec-mtypes}),
2722 and restricting the scope of the URL translation service
2723 (Section \ref{sect:web-sec-urls}).
2725 \paragraph{MType Restrictions}
2726 \label{sect:web-sec-mtypes}
2728 The SAMP standard imposes no restriction on the semantics of MTypes,
2729 so SAMP can in principle be used to send messages which exercise
2730 the privileges available to other SAMP clients in arbitrary ways.
2731 In practice, most SAMP MTypes are fairly harmless; a typical result
2732 is loading an image into an image viewer. While hostile
2733 abuse of such a capability could be annoying, it does not consitute
2734 a serious security concern. However one might imagine an MType
2735 that intentionally or unintentionally allowed execution of
2736 arbitrary scripting operations within the context of a connected
2737 client, and hostile abuse of such a facility could easily result
2738 in theft of or damage to data, or in other serious security breaches.
2740 With this in mind, Web Profile hub implementations MAY
2741 impose some restrictions on the MTypes that registered clients are
2742 permitted to send, via for instance some per-MType whitelisting
2743 or blacklisting mechanism. Given the open-ended nature of the MType
2744 vocabulary, a whitelisting approach may be most appropriate.
2746 The hub MAY also restrict MTypes that Web Profile registered clients
2747 are permitted to receive, though it is harder to imagine exploits
2748 based on message receipt.
2750 Hubs may implement such message blocking either by hiding
2751 blocked subscriptions from other clients as appropriate,
2752 or by refusing to forward messages corresponding to blocked subscriptions.
2753 In the latter case a communication failure should be signalled
2754 by responding with an XML-RPC fault.
2756 \paragraph{URL Restrictions}
2757 \label{sect:web-sec-urls}
2759 As explained in Section \ref{sect:web-urltrans}, the Web Profile
2760 provides a service for proxying arbitrary URLs, so that
2761 web clients can access data referenced by URL in SAMP messages
2762 or metadata, which sandbox-imposed cross-origin restrictions would
2763 otherwise block them from reading.
2765 This capability is essential for worthwhile use of many common
2766 SAMP MTypes.
2767 However, it is also open to abuse, for instance a hostile client
2768 might request to read {\tt file:///etc/passwd} or some HTTP URL
2769 on the local host or network which is restricted to local access.
2771 Web Profile implementations therefore MAY impose such restrictions
2772 as they see fit on the use of the URL translation service provided
2773 to web clients, in order to prevent such abuse.
2774 Blocking all access to resources which are local
2775 ({\tt file:} or {\tt http://localhost/}) is too strict to be useful,
2776 since the URLs referenced in SAMP messages very often
2777 fall into this category.
2779 An appropriate policy might be to proxy only
2780 URLs which a web client is known to have some legitimate
2781 SAMP-based reason to access, namely those which have previously appeared
2782 in the metadata declared by,
2783 or in a message or response originating from, some other client.
2784 In consideration of the fact that web clients might be able to
2785 provoke other clients to emit a chosen URL, or might cooperate
2786 between themselves, such a list of permitted values SHOULD
2787 be further restricted to those URLs which first appeared
2788 in a metadata or message content or response map from a trusted
2789 (i.e.\ non-web) client.
2791 Since the hub in general lacks the relevant semantic knowledge
2792 there is no foolproof way to identify URLs in metadata or messages,
2793 but checking for syntactically suitable map values
2794 (e.g.\ \verb,(http|https|ftp|file)://.*,)
2795 is likely to be good enough for this purpose.
2797 Where the Web Profile implementation declines a given URL proxy
2798 request, it MUST respond with a 403 Forbidden HTTP response.
2800 It is also RECOMMENDED that proxied HTTP access is limited to
2801 the ``safe'' HTTP methods GET and optionally HEAD
2802 \cite[section 9.1.1]{rfc2616},
2803 and that user credentials (cookies, authentication etc) are not propagated.
2804 Requests using unsupported HTTP methods MUST be met with a
2805 405 Method Not Allowed response.
2808 \subsubsection{Security Summary}
2809 \label{sect:web-sec-summary}
2811 The basic mechanics of the Web Profile present significant security risks
2812 for a host on which it runs. This section has described how
2813 security-conscious implementations of the Profile can mitigate those risks.
2814 Following the recommendations from Section \ref{sect:web-sec-reg}
2815 on when to permit registration provides a reasonable assurance that
2816 registered clients will be trustworthy, and in particular guarantees
2817 that clients can only register with explicit authorization from a
2818 human user.
2819 Following the recommendations from Section \ref{sect:web-sec-behave}
2820 about permitted behaviour of registered clients
2821 ensures that even if a hostile client is allowed to register
2822 it is unlikely to be able to do significant damage.
2823 By combining these measures it is believed that the level of risk
2824 associated with running a Web Profile, while it would not be appropriate
2825 for instance for financial transactions, is no greater than that
2826 encountered on a regular basis by use of the web in general.
2828 The mitigation measures are presented as (in some cases strong)
2829 RECOMMENDations and suggestions rather than REQUIREments,
2830 in order to allow implementations to
2831 experiment with the most appropriate configurations, which may change
2832 as a result of emerging technology and common usage patterns.
2833 Such experimentation and further consideration may result in some
2834 modification of the protocol or documentation of best practice in
2835 future versions of this document or elsewhere.
2838 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2839 \section{MTypes: Message Semantics and Vocabulary}
2840 \label{sect:mtypes}
2842 A message contains an MType string that
2843 defines the semantic meaning of the message, for example a request for
2844 another application to load a table.
2845 The concept behind the MType
2846 is similar to that of a UCD \cite{ucd}
2847 in that a small vocabulary is sufficient to
2848 describe the expected range of concepts required by a messaging system
2849 within the current scope of the SAMP protocol.
2850 Developers are free to introduce new MTypes for use within applications
2851 without restriction; new MTypes intended to be used for Hub messaging or
2852 other administrative purposes within the messaging system should be discussed
2853 within the IVOA for approval as part of the SAMP standard.
2855 \subsection{The Form of an MType}
2857 MType syntax is formally defined in Section \ref{sect:subscription}.
2858 Like a UCD, an MType is made up of {\em atoms}.
2859 These are not only meaningful to the developer, but form the central
2860 concept of the message.
2861 Because the capabilities one application is searching for
2862 are loosely coupled with the details of what another may provide,
2863 there is not a rigorous definition of the {\em behavior} that
2864 an MType must provoke in a receiver. Instead, the MType defines a specific
2865 semantic message such as ``display an image'', and it is up to the receiving
2866 application to determine how it chooses to do the display (e.g.\ a rendered
2867 greyscale image within an application or displaying the image in a web
2868 browser might both be valid for the recipient and faithful to the meaning
2869 of the message).
2871 The ordering of the words in an MType SHOULD normally use the
2872 object of the message followed by the action to be performed (or the
2873 information about that object). For example, the use of ``{\tt image.display}''
2874 is preferred to ``{\tt display.image}'' in order to keep the number of top-level
2875 words (and thus message classes) like `image' small, but still allow for a
2876 wide variety of messages to be created that can perform many useful actions
2877 on an image. If no existing MType exists for the required purpose,
2878 developers can agree to the use of a new MType such as
2879 ``{\tt image.display.extnum}'' if, e.g., the ability to display a specific image
2880 extension number warrants a new MType.
2883 \subsection{The Description of an MType}
2884 \label{sect:mtype-doc}
2886 In order that senders and recipients can agree on what is meant by
2887 a given message, the meaning of an MType must be clearly documented.
2888 This means that for a given MType the following information must be
2889 available:
2890 \begin{enumerate}
2891 \item The MType string itself
2892 \item A list of zero or more named parameters
2893 \item A list of zero or more named returned values
2894 \item A description of the meaning of the message
2895 \end{enumerate}
2896 For each of the named parameters, and each of the returned values,
2897 the following information must be provided:
2898 \begin{itemize}
2899 \item name
2900 \item data type ({\tt map}, {\tt list} or {\tt string}
2901 as described in Section \ref{sect:samp-data-types}) and if appropriate
2902 scalar sub-type (see Section \ref{sect:scalar-types})
2903 \item meaning
2904 \item whether it is OPTIONAL (considered REQUIRED unless stated otherwise)
2905 \item OPTIONAL parameters MAY specify what default will be used
2906 if the value is not supplied
2907 \end{itemize}
2908 Together, this is much the same information as should be given for
2909 documentation of a public interface method in a weakly-typed programming
2910 language.
2912 The parameters and return values associated with each MType
2913 form extensible vocabularies as explained in Section \ref{sect:vocab},
2914 except that there is no reserved ``{\tt samp.}'' namespace.
2916 Note that it is possible for the MType to have no returned values.
2917 This is actually quite common if the MType does not represent a
2918 request for data. It is not usually necessary to define a status-like
2919 return value (success or failure),
2920 since this information can be conveyed as the value of the {\tt samp.status}
2921 entry in the call response as described in Section \ref{sect:response-encode}.
2923 \subsection{MType Vocabulary: Extensibility and Process}
2925 The set of MTypes forms an extensible vocabulary along the lines of
2926 Section \ref{sect:vocab}.
2927 The relatively small set of MTypes in the ``{\tt samp.}'' namespace is
2928 defined in Section \ref{sect:admin-mtypes} of this document,
2929 but applications will need to use a wider range of MTypes to exchange
2930 useful information.
2931 Although clients are formally permitted to
2932 define and use any MTypes outside of the reserved ``{\tt samp.}'' namespace,
2933 for effective interoperability there must be
2934 public agreement between application authors on this unreserved vocabulary
2935 and its semantics.
2937 Since addition of new MTypes is expected to be ongoing,
2938 MTypes from this broader vocabulary will
2939 be documented
2940 outside of this document to avoid the administrative
2941 overhead and delay associated with the IVOA Recommendation Track \cite{docstd}.
2942 At time of writing, the procedures for maintaining the list of
2943 publicly-agreed MTypes are quite informal.
2944 These procedures remain under review,
2945 however the current list and details of best practice for adding to it
2946 are, and will remain, available in some form from the URL
2947 \url{http://www.ivoa.net/samp/}.
2950 \subsection{Core MTypes}
2951 \label{sect:admin-mtypes}
2953 This section defines those MTypes currently in the ``{\tt samp.}'' hierarchy.
2954 These are the ``administrative''-type MTypes which are core to the
2955 SAMP architecture or widely applicable to SAMP applications.
2957 % define command for describing an MType.
2958 % arguments are:
2959 % qualified name,
2960 % parameter list,
2961 % return values,
2962 % description,
2963 \newcommand{\mtypedef}[4]{
2964 \begin{description}
2965 \item[{\tt #1}:]\dbreakd
2966 \begin{description}
2967 \item[Arguments:]\dbreakd\begin{description}#2\end{description}
2968 \item[Return Values:]\dbreakd\begin{description}#3\end{description}
2969 \item[Description:]\dbreak #4
2970 \end{description}
2971 \end{description}
2972 }
2974 % define command for describing an MType argument.
2975 % arguments are:
2976 % name,
2977 % type,
2978 % short description
2979 \newcommand{\mtypearg}[3]{\item[{\tt #1} ({\tt #2}) ---] #3}
2981 \newcommand{\mtypenoargs}{\item[{\em none}]}
2983 \subsubsection{Hub Administrative Messages}
2984 \label{sect:hub-mtypes}
2986 The following MTypes are for messages which SHOULD be broadcast by the hub
2987 in response to changes in hub state. By subscribing to these messages,
2988 clients are able to keep track of the current set of registered applications
2989 and of their metadata and subscriptions.
2990 In general, non-hub clients SHOULD NOT send these messages.
2991 %
2992 \mtypedef{samp.hub.event.shutdown}
2993 {\mtypenoargs}
2994 {\mtypenoargs}
2995 {The hub SHOULD broadcast this message just before it exits.
2996 It SHOULD also send it to clients who are registered using a
2997 given profile if that profile is about to shut down, even if
2998 the hub itself will continue to operate.
2999 The hub SHOULD make every effort to broadcast this message even in
3000 case of an exit due to an error condition.}
3001 %
3002 \mtypedef{samp.hub.event.register}
3003 {\mtypearg{id}{string}{Public ID of newly registered client}}
3004 {\mtypenoargs}
3005 {The hub SHOULD broadcast this message every time a client
3006 successfully registers.}
3007 %
3008 \mtypedef{samp.hub.event.unregister}
3009 {\mtypearg{id}{string}{public ID of unregistered client}}
3010 {\mtypenoargs}
3011 {The hub SHOULD broadcast this message every time a client
3012 unregisters.}
3013 %
3014 \mtypedef{samp.hub.event.metadata}
3015 {\mtypearg{id}{string}{public ID of client declaring metadata}
3016 \mtypearg{metadata}{map}{new metadata declared by client}}
3017 {\mtypenoargs}
3018 {The hub SHOULD broadcast this message every time a client
3019 declares its metadata.
3020 The {\tt metadata} argument is exactly as passed using the
3021 {\tt declareMetadata()} method.}
3022 %
3023 \mtypedef{samp.hub.event.subscriptions}
3024 {\mtypearg{id}{string}{public ID of subscribing client}
3025 \mtypearg{subscriptions}{map}{new subscriptions declared by client}}
3026 {\mtypenoargs}
3027 {The hub SHOULD broadcast this message every time a client
3028 declares its subscriptions.
3029 The {\tt subscriptions} argument is exactly as passed using the
3030 {\tt declareSubscriptions()} method, and hence may contain wildcarded
3031 MType strings.}
3032 %
3033 \mtypedef{samp.hub.disconnect}
3034 {\mtypearg{reason}{string}{(OPTIONAL)
3035 Short text message indicating the reason
3036 that the disconnection is being forced}}
3037 {\mtypenoargs}
3038 {The hub SHOULD send this message to a client if the hub intends to disconnect that
3039 client forcibly. This indicates that no further communication
3040 from that client is welcome, and any such attempts may be
3041 expected to fail.
3042 The hub may wish to disconnect clients forcibly as a result of
3043 some hub timeout policy or for other reasons.}
3045 \subsubsection{Client Administrative Messages}
3047 The following messages are generic messages defined for client use.
3048 %
3049 \mtypedef{samp.app.ping}
3050 {\mtypenoargs}
3051 {\mtypenoargs}
3052 {Diagnostic used to indicate whether an application is
3053 currently responding.
3054 No ``status''-like return value is defined,
3055 since in general any response will indicate aliveness,
3056 and the normal {\tt samp.status} key in the response may be
3057 used to indicate any abnormal state.}
3058 %
3059 \mtypedef{samp.app.status}
3060 {\mtypearg{txt}{string}{Textual indication of status}}
3061 {\mtypenoargs}
3062 {General purpose message to indicate application status.}
3063 %
3064 \mtypedef{samp.app.event.shutdown}
3065 {\mtypenoargs}
3066 {\mtypenoargs}
3067 {Indicates that the sending application is going to shut down.
3068 Note that sending this message is not a substitute for unregistering
3069 with the hub --- registered clients about to shut down
3070 SHOULD always explicitly unregister.}
3071 %
3072 \mtypedef{samp.msg.progress}
3073 {\mtypearg{msgid}{string}{Message ID of a previously received message}
3074 \mtypearg{txt}{string}{Textual indication of progress}
3075 \mtypearg{percent}{string}{(OPTIONAL)
3076 SAMP float value giving the approximate
3077 percentage progress}
3078 \mtypearg{timeLeft}{string}{(OPTIONAL)
3079 SAMP float value giving the estimated
3080 time to completion in seconds}}
3081 {\mtypenoargs}
3082 {Reports on progress of a message previously received by the sender
3083 of this message. Such progress reports MAY be sent at intervals
3084 between the receipt of the message and sending a reply.
3085 Note that the {\tt msg-id} of the earlier message must be passed to
3086 identify it --- the sender of the earlier message (the recipient of
3087 this one) will have to have retained it from the return value of the
3088 relevant {\tt call*()} method to match progress reports with
3089 requests.}
3091 \newpage
3092 \appendix
3094 \section{Changes between PLASTIC and SAMP}
3096 In order to facilitate the transition from PLASTIC to SAMP from an
3097 application developer's point of view, we summarize in this Appendix
3098 the main changes.
3099 In some cases the reasons for these are summarized as well.
3101 \begin{description}
3102 \item[Language Neutrality:]
3103 PLASTIC contained some Java-specific ideas and details, in particular
3104 an API defined by a Java interface, use of Java RMI-Lite as a
3105 transport protocol option, and a lockfile format
3106 based on java Property serialization.
3107 No features of SAMP are specific to, or defined with reference to, Java
3108 (or to any other programming language).
3109 \item[Profiles:]
3110 The formal notion of a SAMP Profile replaces the choices of transport
3111 protocol in PLASTIC.
3112 \item[Nomenclature:]
3113 Much of the terminology has changed between PLASTIC and SAMP,
3114 in some cases to provide better consistency with common usage in
3115 messaging systems.
3116 There is not in all cases a one-to-one correspondence betweeen PLASTIC and
3117 SAMP concepts, but a partial translation table is as follows:
3118 \begin{center}
3119 \begin{tabular}{ll}
3120 PLASTIC & SAMP \\
3121 \hline
3122 message & MType \\
3123 support a message & subscribe to an MType \\
3124 registered application & client \\
3125 synchronous request & synchronous call/response \\
3126 asynchronous request & notification
3127 \end{tabular}
3128 \end{center}
3129 \item[MTypes:]
3130 In PLASTIC message semantics were defined using opaque URIs such as
3131 {\tt ivo://votech.org/hub/event/HubStopping}.
3132 SAMP replaces these with a vocabulary of structured MTypes
3133 such as {\tt samp.hub.event.shutdown}.
3134 \item[Asynchrony:]
3135 Responses from messages in PLASTIC were returned synchronously, using
3136 blocking methods at both sender and recipient ends. As well as
3137 inhibiting flexibility, this risked timeouts for long processing times
3138 at the discretion of the underlying transport.
3139 The basic model in SAMP relies on asynchronous responses, though
3140 a synchronous fa\c{c}ade hub method is also provided for
3141 convenience of the sender.
3142 Client toolkits may also wish to provide client-side synchronous
3143 fa\c{c}ades based on fully asynchronous messaging.
3144 \item[Registration:]
3145 In PLASTIC clients registered with a single call which acquired a
3146 hub connection and declared callback information, message subscriptions,
3147 and some metadata.
3148 In SAMP, these four operations have been decomposed into separate calls.
3149 As well as being tidier, this offers benefits such as meaning that
3150 the subscriptions and metadata can be updated during the lifetime of
3151 the connection.
3152 \item[Client Metadata:]
3153 PLASTIC stored some application metadata (Name) in the hub and provided
3154 acess to others (Description, Icon URL, \ldots) using custom messages.
3155 SAMP stores it all in the hub providing better extensibility and consistency
3156 as well as improving metadata provision for non-callable applications
3157 and somewhat reducing traffic and burden on applications.
3158 \item[Named Parameters:]
3159 The parameters for PLASTIC messages were identified by sequence
3160 (forming a list), while
3161 the parameters for SAMP MTypes are identified by name (forming a map).
3162 As well as improving documentability, this makes it much more convenient
3163 to allow for optional parameters or to introduce new ones.
3164 The same arrangement applies to return values.
3165 \item[Recipient Targetting:]
3166 PLASTIC featured methods for sending messages to all or to an explicit list
3167 of recipients. In practice the list variants were rarely used except to
3168 send to a single recipient.
3169 SAMP has methods for sending to all or to a single recipient.
3170 \item[Typing:]
3171 Data types in PLASTIC were based partly on Java and partly on XML-RPC types.
3172 There was not a one-to-one correspondence between types in the Java-RMI
3173 transport and the XML-RPC one, which encouraged confusion.
3174 Parameter types included integer, floating point and boolean as well as
3175 string, which proved problematic to use correctly from some
3176 weakly-typed languages.
3177 SAMP uses a more restricted set of types
3178 (namely string, list and map) at the protocol level,
3179 along with some auxiliary rules for encoding numbers and booleans as strings.
3180 \item[Lockfile:]
3181 The lockfile in SAMP's standard profile is named {\tt .samp},
3182 its format is defined explicitly rather than with reference
3183 to Java documentation, and there is better provision for its
3184 location in a language-independent way on MS Windows systems.
3185 In many cases however, the same lockfile location/parsing code
3186 will work for both SAMP and PLASTIC except for the different filenames
3187 (``.samp'' vs.\ ``.plastic'').
3188 \item[Public/Private ID:]
3189 In PLASTIC a single, public ID was used to label and identify
3190 applications during communications directed to the hub
3191 or to other applications.
3192 This meant that applications could easily, if they wished,
3193 impersonate other applications. The practice in SAMP is to
3194 use different IDs for public labelling and private identification,
3195 which means that such ``spoofing'' is no longer a danger.
3196 \item[Errors:]
3197 SAMP has provision to return more structured error information
3198 than PLASTIC did.
3199 \item[Extensibility:]
3200 Although PLASTIC was in some ways extensible, SAMP provides more hooks
3201 for future extension, in particular by pervasive use of the
3202 {\em extensible vocabulary\/} pattern.
3203 \end{description}
3206 \section{Change History}
3207 \label{sect:changes}
3209 Changes to SAMP between Working Draft version 1.0 (2008-06-25) and
3210 Recommendation version 1.11 (2009-04-21):
3211 \begin{itemize}
3212 \item Return values of {\tt callAll} and {\tt notifyAll} operations changed;
3213 they now return information about clients receiving the messages
3214 (Section \ref{sect:hubOps}).
3215 \item Characters allowed in {\tt string} type restricted to avoid
3216 problems transmitting over XML;
3217 was 0x01--0x7f, now 0x09, 0x0a, 0x0d, 0x20--0x7f
3218 (Section \ref{sect:samp-data-types}).
3219 \item New hub administrative message {\tt samp.hub.disconnect}
3220 (Section \ref{sect:hub-mtypes}).
3221 \item Empty placeholder appendix on SAMP/PLASTIC interoperability removed.
3222 \item Wording clarified and made more explicit in a few places.
3223 \item Typos fixed, including incorrect BNF in Section \ref{sect:subscription}.
3224 \item Author list re-ordered.
3225 \item Editorial changes and clarifications following RFC period.
3226 \item MType Vocabulary section now directs readers to
3227 {\tt http://www.ivoa.net/samp/} to find current MType list and process.
3228 \end{itemize}
3230 Changes to SAMP between Recommendation version 1.11 (2009-04-21) and
3231 version 1.2 (2010-12-16):
3232 \begin{itemize}
3233 \item Use of new SAMP\_HUB environment variable lockfile location option
3234 documented in section \ref{sect:lockfile}.
3235 \item Added Non-Technical Preamble section \ref{sect:nonTechPreamble}
3236 as per agreement for all new/revised IVOA documents.
3237 \end{itemize}
3239 Changes to SAMP between Recommendation version 1.2 (2010-12-16) and
3240 version 1.3 (2012-04-11):
3241 \begin{itemize}
3242 \item Add a new Section \ref{sect:webprofile} on the Web Profile.
3243 Minor changes in the rest of the document noting the existence
3244 of this new Profile.
3245 \item Add a new Section \ref{sect:security} discussing security issues
3246 in general, with reference to their particular consideration for
3247 both Standard and Web Profiles. The discussion of Standard Profile
3248 security is moved to its own new Section \ref{sect:std-security}.
3249 \item MType syntax declaration in Section \ref{sect:subscription} now permits
3250 upper-case letters (for consistency with actual usage).
3251 \item Sections \ref{sect:response-encode} and \ref{sect:faults} now note
3252 that the hub is permitted to generate and forward an error response
3253 on behalf of a client under some circumstances.
3254 The {\tt samp.code=samp.noresponse} code is reserved for
3255 this purpose.
3256 \item Section \ref{sect:vocab} now reserves a namespace ``{\tt x-samp}''
3257 for keys in an extensible vocabulary which are proposed
3258 for possible future introduction into this standard.
3259 \item A comment has been added to Section \ref{sect:samp-data-types}
3260 concerning recommended protocols for use with URLs in messages.
3261 \end{itemize}
3263 %%%%%%%% Bibliography %%%%%%%
3264 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3265 \begin{thebibliography}{99}
3266 \bibitem{architecture}
3267 C.~Arviset et al.,
3268 ``\href{http://www.ivoa.net/Documents/Notes/IVOAArchitecture/index.html}
3269 {IVOA Architecture}'', IVOA Note, 2010
3270 \bibitem{2000A+AS..143...33B}
3271 F.~{Bonnarel}, P.~{Fernique}, O.~{Bienaym{\'e}}, D.~{Egret}, F.~{Genova},
3272 M.~{Louys}, F.~{Ochsenbein}, M.~{Wenger}, and J.~G. {Bartlett},
3273 ``The ALADIN interactive sky atlas. A reference tool for
3274 identification of astronomical sources'',
3275 {\em A\&AS}, 143:33--40, 2000
3276 \bibitem{2007HiA....14..622B}
3277 U.~{Becciani}, M.~{Comparato}, A.~{Costa}, C.~{Gheller}, B.~{Larsson},
3278 F.~{Pasian}, and R.~{Smareglia}.
3279 ``VisIVO: an interoperable visualisation tool for Virtual Observatory data'',
3280 {\em Highlights of Astronomy}, 14:622--622, 2007
3281 \bibitem{xpa}
3282 \url{http://hea-www.harvard.edu/RD/xpa/}
3283 \bibitem{plastic}
3284 J.~{Taylor}, T.~{Boch}, M.~{Comparato}, M.~{Taylor}, and N.~{Winstanley}.
3285 ``\href{http://ivoa.net/Documents/latest/PlasticDesktopInterop.html}
3286 {PLASTIC --- a protocol for desktop application interoperability}'',
3287 IVOA Note, 2006
3288 \bibitem{plastic-sf}
3289 \url{http://plastic.sourceforge.net/}
3290 \bibitem{xmlrpc}
3291 \url{http://www.xmlrpc.com/}
3292 \bibitem{rfc2119}
3293 S.~Bradner,
3294 \href{http://www.rfc-editor.org/rfc/rfc2119.txt}{RFC~2119}:
3295 ``Key words for use in RFCs to Indicate Requirement Levels'',
3296 IETF Request For Comments, 1997
3297 \bibitem{rfc1738}
3298 T.~Berners-Lee, L.~Masinter, M.~McCahill,
3299 \href{http://www.rfc-editor.org/rfc/rfc1738.txt}{RFC~1738}:
3300 ``Uniform Resource Locators (URL)'',
3301 IETF Request For Comments, 1994
3302 \bibitem{rfc2246}
3303 T.~Dierks, C.~Allen,
3304 \href{http://www.rfc-editor.org/rfc/rfc2246.txt}{RFC~2246}:
3305 ``The TLS Protocol'',
3306 IETF Request For Comments, 1999
3307 \bibitem{cors}
3308 A.~van~Kesteren (Ed.),
3309 ``\href{http://www.w3.org/TR/cors/}{Cross-Origin Resource Sharing}'',
3310 W3C Working Draft, 2010
3311 \bibitem{xhr2}
3312 A.~van~Kesteren (Ed.),
3313 ``\href{http://www.w3.org/TR/XMLHttpRequest2/}{XMLHttpRequest Level 2}'',
3314 W3C Working Draft, 2012
3315 \bibitem{flash-crossdomain}
3316 Adobe Flash cross-domain policy,
3317 \url{http://www.adobe.com/devnet/articles/crossdomain_policy_file_spec.html}
3318 \bibitem{silverlight-crossdomain}
3319 Microsoft Silverlight cross-domain policy,
3320 \url{http://msdn.microsoft.com/en-us/library/cc645032(VS.95).aspx}
3321 \bibitem{rfc2396}
3322 T.~Berners-Lee et al.,
3323 \href{http://www.rfc-editor.org/rfc/rfc2396.txt}{RFC~2396}:
3324 ``Uniform Resource Identifiers (URI): Generic Syntax'',
3325 IETF Request For Comments, 1998
3326 \bibitem{rfc2616}
3327 R.~Fielding et al.,
3328 \href{http://www.w3.org/Protocols/rfc2616/rfc2616.html}{RFC~2616}:
3329 ``Hypertext Transfer Protocol -- HTTP/1.1'',
3330 IETF Request For Comments, 1999
3331 \bibitem{rfc3275}
3332 D.~Eastlake et al.,
3333 \href{http://www.rfc-editor.org/rfc/rfc3275.txt}{RFC~3275}:
3334 ``XML-Signature Syntax and Processing'',
3335 IETF Request For Comments, 2002
3336 \bibitem{origin}
3337 A.~Barth,
3338 ``\href{http://tools.ietf.org/html/draft-abarth-origin}
3339 {The Web Origin Concept}'',
3340 IETF Draft, 2010
3341 \bibitem{ucd}
3342 A.~Preite~Martinez et al.
3343 ``\href{http://www.ivoa.net/Documents/latest/UCD.html}
3344 {An IVOA Standard for Unified Content Descriptors}'',
3345 IVOA Recommendation, 2007
3346 \bibitem{docstd}
3347 R.~J.~Hanisch et al.
3348 ``\href{http://www.ivoa.net/Documents/latest/DocStd.html}
3349 {IVOA Document Standards}'',
3350 IVOA Recommendation, 2010
3351 \end{thebibliography}
3353 \end{document}
3355 % $Id$


Name Value
svn:keywords Date Id Rev URL

ViewVC Help
Powered by ViewVC 1.1.26