ViewVC logotype

Contents of /trunk/projects/grid/uws/UWSRegExt/UWSRegExt.tex

Parent Directory Parent Directory | Revision Log Revision Log

Revision 5064 - (show annotations)
Mon Jun 25 11:14:29 2018 UTC (2 years, 1 month ago) by msdemlei
File MIME type: application/x-tex
File size: 12630 byte(s)

(mainly, using listings rather than verbatim, as that's likely to be better
supported in ivoatex)

1 \documentclass[11pt,a4paper]{ivoa}
2 \input tthdefs
4 \usepackage{listings}
5 \lstloadlanguages{XML,SQL}
6 \lstset{flexiblecolumns=true,tagstyle=\ttfamily,showstringspaces=False,
7 basicstyle=\footnotesize}
9 \title{UWS Registry Extension}
11 \ivoagroup{Grid and Web Services}
13 \author{Brian Major}
14 \author{Markus Demleitner}
15 \author{Patrick Dowler}
16 \author{Mark Taylor}
18 \editor{Brian Major}
20 \previousversion{This is the first public release}
22 \begin{document}
23 \begin{abstract}
25 The Universal Worker Service (UWS) Registry Extension allows for extended metadata to be set on a VOResource \xmlel{interface} for the purpose of tagging UWS job execution access URLs.
27 \end{abstract}
29 \section*{Conformance-related definitions}
31 The words ``MUST'', ``SHALL'', ``SHOULD'', ``MAY'', ``RECOMMENDED'', and
32 ``OPTIONAL'' (in upper or lower case) used in this document are to be
33 interpreted as described in IETF standard RFC2119 \citep{std:RFC2119}.
35 The \emph{Virtual Observatory (VO)} is a
36 general term for a collection of federated resources that can be used
37 to conduct astronomical research, education, and outreach.
38 The \href{http://www.ivoa.net}{International
39 Virtual Observatory Alliance (IVOA)} is a global
40 collaboration of separately funded projects to develop standards and
41 infrastructure that enable VO applications.
43 \section{Introduction}
45 This note describes the registry extension for the Universal Worker Service UWS \citep{std:UWS}. Registry extensions add information to the schema defined in VOResource \citep{std:VOR} that are specific to a particular standard, in this case UWS.
47 The UWS registry extension is very simple--it allows for two new values to be set on the \emph{type} attribute in the \xmlel{interface} element in a VOResource \xmlel{capability}. These types have the purpose of identifying the \xmlel{interface} as one of the synchronous or asynchronous UWS job execution features.
49 Although the UWS registry extension itself is simple, the history of the need for it is complicated. This history is described in section \ref{background}. The extension itself is described in section \ref{uwsregext}.
51 %\subsection{Role within the VO Architecture}
53 %\begin{figure}
54 %\centering
56 % As of ivoatex 1.2, the architecture diagram is generated by ivoatex in
57 % SVG; copy ivoatex/archdiag-full.xml to archdiag.xml and throw out
58 % all lines not relevant to your standard.
59 % Notes don't generally need this. If you don't copy archdiag.xml,
60 % you must remove archdiag.svg from FIGURES in the Makefile.
62 %\includegraphics[width=0.9\textwidth]{archdiag.svg}
63 %\caption{Architecture diagram for this document}
64 %\label{fig:archdiag}
65 %\end{figure}
67 %Fig.~\ref{fig:archdiag} shows the role this document plays within the
68 %IVOA architecture \citep{note:VOARCH}.
70 \section{Background} \label{background}
72 \subsection{Motivation}
74 During the review of the TAP 1.1 specification \citep{std:TAP}, it was discovered that, when searching for TAP instances, there is the potential for clients of RegTAP \citep{std:RegTAP} to discover multiple \xmlel{interface} results per instance when only one is expected.
76 TAP clients currently follow the recommendations of RegTAP 1.1 to discover TAP access URLs and issue a query like this:
78 \begin{lstlisting}[language=SQL]
79 SELECT ivoid, access_url
80 FROM rr.capability
81 NATURAL JOIN rr.interface
82 WHERE standard_id like 'ivo://ivoa.net/std/tap%'
83 AND intf_type='vs:paramhttp'
84 \end{lstlisting}
86 This query is sufficient for most of the existing registered TAP services and will return only one result. Those records typically look like this:
88 \begin{lstlisting}[language=XML]
89 <capability standardID="ivo://ivoa.net/std/TAP">
90 <interface xsi:type="vod:ParamHTTP" role="std">
91 <accessURL use="base">http://example.com/tap</accessURL>
92 </interface>
93 </capability>
94 \end{lstlisting}
96 To then use the sync and async endpoints of the TAP service, clients simply append /sync and /async to the end of the base access URL, as per the recommendations of TAP version 1.0.
98 Two things have changed since VOResource version 1.03 that make this query to find all TAP services incorrect:
100 \paragraph{Change \#1. Multiple standard IDs in TAP} TAP 1.1 originally stated that the standard IDs of sync and async are distinct and each are registered. Although this gives services the flexibility to use URLs for sync and async that don't end in precisely /sync and /async, it breaks the pattern of TAP 1.0 service discovery. With the search recommended by RegTAP, clients would find the \xmlel{interfaces} within each of the \xmlel{capabilities} and attempt to append /sync and /async to the endpoints.
102 Here is an example of the \xmlel{capability} element of the (now obsolete) synchronous endpoint in TAP 1.1:
104 \begin{lstlisting}[language=XML]
105 <capability standardID="ivo://ivoa.net/std/TAP#sync-1.1">
106 <interface xsi:type="vs:ParamHTTP" role="std" version="1.1">
107 <accessURL use="base">http://example.com/tap/sync</accessURL>
108 </interface>
109 </capability>
110 \end{lstlisting}
112 \paragraph{Change \#2. Multiple \xmlel{interfaces} per \xmlel{capability}} Although, in VOResource, it has always been the case that multiple \xmlel{interfaces} are allowed per \xmlel{capability}, no services had yet to be registered with such a configuration. This changed when some TAP implementations introduced TAP endpoints with a variety of \xmlel{SecurityMethod}\/s. To document such a configuration, multiple \xmlel{interfaces} per \xmlel{capability} must be created, each with a different \xmlel{SecurityMethod}. Or, when the access URLs are the same, a single \xmlel{interface} with multiple \xmlel{SecurityMethod}\/s could be created. Each configuration causes difficulties for registry service lookup.
114 Here is an example of the \xmlel{capability} element of the synchronous endpoint in TAP 1.1 (now obsolete) with multiple \xmlel{interfaces} to support multiple \xmlel{SecurityMethod}\/s:
116 \begin{lstlisting}[language=XML]
117 <capability standardID="ivo://ivoa.net/std/TAP#sync-1.1">
118 <interface xsi:type="vs:ParamHTTP" role="std" version="1.1">
119 <accessURL use="base">http://example.com/tap/sync</accessURL>
120 </interface>
121 <interface xsi:type="vs:ParamHTTP" role="std" version="1.1">
122 <accessURL use="base">https://example.com/tap/sync</accessURL>
123 <securityMethod standardID="ivo://ivoa.net/sso#tls-with-certificate"/>
124 </interface>
125 </capability>
126 \end{lstlisting}
128 Note that, though this issue was discovered on the review of TAP 1.1, it applies to all IVOA services that need to provide potentially different access URLs for each \xmlel{SecurityMethod}.
130 \subsection{Reaction}
132 To address problem \#2 described above, RegTAP 1.1 recommends that an additional constraint of having a null \xmlel{SecurityMethod} is included in the where clause of the TAP service discovery query. However, for this to work, there cannot be a case where an \xmlel{interface} is reused by multiple \xmlel{securityMethod}\/s, as this would not allow the constraint of a null securityMethod to work if the endpoint supported other non-null \xmlel{securityMethod}\/s. So, VOResource 1.1 has ensures that at most one \xmlel{SecurityMethod} is allowed per \xmlel{interface}.
134 Problem \#1 is addressed in two ways: One: By removing multiple standard IDs from TAP 1.1; and, two: by the use of this UWS Registry Extension. TAP 1.1 has removed the use of standardIDs for sync and async and instead now only uses the version agnostic standardID from TAP 1.0: \xmlel{ivo://ivoa.net/std/TAP}. Clients can recognize the TAP service as version 1.1 by checking for a \xmlel{version} attribute with the value "1.1" in the \xmlel{capability}. In order to allow services to choose their own access URLs for sync and async queries, \xmlel{interface} elements within the \xmlel{capability} are created for each type of \xmlel{SecurityMethod} that is supported. There may be both sync and async versions of these \xmlel{interfaces}. Whether an interface is sync or async is determined by the \emph{type} attribute in the \xmlel{interface}. To support TAP 1.0 backwards compatibility, a TAP 1.0 style \xmlel{interface} must remain in the \xmlel{capabilities}.
136 \section{UWS Registry Extension} \label{uwsregext}
138 A number of IVOA services have functionality built on the Universal Worker Service. Jobs, which perform service-specific functions, can be created and started in either a synchronous or asynchronous manner. These services include TAP \citep{std:TAP}, VOSpace \citep{std:VOSpace}, and others. It is the UWS specification itself that defines how the lifecycle of these jobs is managed through a RESTful interface, not the services that are built on top of them. However, in the past, it has been left to the services to state how the various UWS endpoints (namely the synchronous and asynchronous job execution endpoints) are to be discovered through the IVOA registry.
140 This first version of the UWS Registry Extension enables UWS services to be registered with UWS-specific interface types so that they can be discovered by clients in a standard way defined by this note. This means that specifications built on UWS need not specify additional details on how to discover UWS RESTful endpoints.
142 The UWS Registry Extension introduces two new \xmlel{interface} types: one for synchronous jobs and one for asynchronous jobs. The surrounding \xmlel{capability} element should be marked with the minor version of service specification, as per the recommendations in the XML schema versioning note \citep{2018ivoa.spec.0529H}.
144 \begin{table}
145 \centering
146 \begin{tabular}{| c | c | c |}
147 \hline
148 & Asynchronous & Synchronous \\
149 \hline
150 Interface Type & uws:Async & uws:Sync \\
151 \hline
152 \end{tabular}
153 \caption{UWS Async and Sync interface types}
154 \end{table}
156 Future versions of the UWS Registry Extension may allow for more detail to be added about the UWS interfaces. This first version only supplies the two new \xmlel{interface} types so that they can be used by UWS services to \emph{tag} their sync and async endpoints.
158 \subsection{Example TAP 1.1 capability}
160 The following example describes how a TAP 1.1 service advertises its sync and async query endpoints under the single TAP capability. Both sync and async support anonymous queries and authenticated queries with TLS \citep{std:SSOAUTH}. The first two \xmlel{interface} are there to provide backwards compatibility support for 1.0 TAP clients.
162 \begin{lstlisting}[language=XML]
163 <capability standardID="ivo://ivoa.net/std/TAP">
165 <!-- TAP 1.0 support -->
166 <capability standardID="ivo://ivoa.net/std/TAP">
167 <interface xsi:type="vod:ParamHTTP" role="std">
168 <accessURL use="base">http://example.com/tap</accessURL>
169 </interface>
170 <interface xsi:type="vod:ParamHTTP" role="std">
171 <accessURL use="base">http://example.com/tap</accessURL>
172 <securityMethod standardID="ivo://ivoa.net/sso#tls-with-certificate"/>
173 </interface>
174 </capability>
176 <!-- TAP 1.1 support -->
177 <interface
178 xmlns:uws="http://www.ivoa.net/xml/UWSRegExt/v1.0"
179 xsi:type="uws:Sync" role="std" version="1.1">
180 <accessURL use="base">http://example.com/tap/sync</accessURL>
181 </interface>
182 <interface
183 xmlns:uws="http://www.ivoa.net/xml/UWSRegExt/v1.0"
184 xsi:type="uws:Sync" role="std" version="1.1">
185 <accessURL use="base">https://example.com/tap/sync</accessURL>
186 <securityMethod standardID="ivo://ivoa.net/sso#tls-with-certificate"/>
187 </interface>
188 <interface
189 xmlns:uws="http://www.ivoa.net/xml/UWSRegExt/v1.0"
190 xsi:type="uws:Async" role="std" version="1.1">
191 <accessURL use="base">http://example.com/tap/async</accessURL>
192 </interface>
193 <interface
194 xmlns:uws="http://www.ivoa.net/xml/UWSRegExt/v1.0"
195 xsi:type="uws:Async" role="std" version="1.1">
196 <accessURL use="base">https://example.com/tap/async</accessURL>
197 <securityMethod standardID="ivo://ivoa.net/sso#tls-with-certificate"/>
198 </interface>
200 </capability>
201 \end{lstlisting}
203 \subsection{XML Schema}
205 The following is the XML Schema Definition for the UWS Registry Extension version 1.0. It can be brought into an XML document's schema as a namespace with the URI \xmlel{http://www.ivoa.net/xml/UWSRegExt/v1.0}.
207 \lstinputlisting[language=XML]{UWSRegExt-v1.0.xsd}
209 \appendix
210 \section{Changes from Previous Versions}
212 No previous versions yet.
213 % these would be subsections "Changes from v. WD-..."
214 % Use itemize environments.
216 \bibliography{ivoatex/ivoabib,ivoatex/docrepo}
218 \end{document}

ViewVC Help
Powered by ViewVC 1.1.26