ViewVC logotype

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

Parent Directory Parent Directory | Revision Log Revision Log

Revision 5005 - (show annotations)
Thu May 24 19:12:17 2018 UTC (2 years, 7 months ago) by major.brian
File MIME type: application/x-tex
File size: 11715 byte(s)
Initial version of the note for the UWS Registry Extension
1 \documentclass[11pt,a4paper]{ivoa}
2 \input tthdefs
4 \usepackage{verbatim}
6 \title{UWS Registry Extension}
8 \ivoagroup{Grid and Web Services}
10 \author{Brian Major}
11 \author{Markus Demleitner}
12 \author{Patrick Dowler}
14 \editor{Brian Major}
16 \previousversion{This is the first public release}
18 \begin{document}
19 \begin{abstract}
21 The Universal Worker Service (UWS) Registry Extension allows for extended metadata to be set on a VOResource \xmlel{interface} for the purpose of discovering UWS job execution access URLs.
23 \end{abstract}
25 \section*{Conformance-related definitions}
27 The words ``MUST'', ``SHALL'', ``SHOULD'', ``MAY'', ``RECOMMENDED'', and
28 ``OPTIONAL'' (in upper or lower case) used in this document are to be
29 interpreted as described in IETF standard RFC2119 \citep{std:RFC2119}.
31 The \emph{Virtual Observatory (VO)} is a
32 general term for a collection of federated resources that can be used
33 to conduct astronomical research, education, and outreach.
34 The \href{http://www.ivoa.net}{International
35 Virtual Observatory Alliance (IVOA)} is a global
36 collaboration of separately funded projects to develop standards and
37 infrastructure that enable VO applications.
39 \section{Introduction}
41 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.
43 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.
45 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}.
47 \section{Background} \label{background}
49 \subsection{Motivation}
51 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.
53 TAP clients currently follow the recommendations of RegTAP 1.1 to discover TAP access URLs and issue a query like this:
55 \begin{verbatim}
56 SELECT ivoid, access_url
57 FROM rr.capability
58 NATURAL JOIN rr.interface
59 WHERE standard_id like 'ivo://ivoa.net/std/tap%'
60 AND intf_type='vs:paramhttp'
61 \end{verbatim}
63 This query is sufficient for most of the existing registered TAP services and will return only one result. Those records typically look like this:
65 \begin{verbatim}
66 <capability standardID="ivo://ivoa.net/std/TAP">
67 <interface xsi:type="vod:ParamHTTP" role="std">
68 <accessURL use="base">http://example.com/tap</accessURL>
69 </interface>
70 </capability>
71 \end{verbatim}
73 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.
75 Two things have changed since VOResource version 1.03 that make this query to find all TAP services incorrect:
77 \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.
79 Here is an example of the \xmlel{capability} element of the (now obsolete) synchronous endpoint in TAP 1.1:
81 \begin{verbatim}
82 <capability standardID="ivo://ivoa.net/std/TAP#sync-1.1">
83 <interface xsi:type="vs:ParamHTTP" role="std" version="1.1">
84 <accessURL use="base">http://example.com/tap/sync</accessURL>
85 </interface>
86 </capability>
87 \end{verbatim}
89 \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{SecurityMethods}. 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{SecurityMethods} could be created. Each configuration causes difficulties for registry service lookup.
91 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{SecurityMethods}:
93 \begin{verbatim}
94 <capability standardID="ivo://ivoa.net/std/TAP#sync-1.1">
95 <interface xsi:type="vs:ParamHTTP" role="std" version="1.1">
96 <accessURL use="base">http://example.com/tap/sync</accessURL>
97 </interface>
98 <interface xsi:type="vs:ParamHTTP" role="std" version="1.1">
99 <accessURL use="base">https://example.com/tap/sync</accessURL>
100 <securityMethod standardID="ivo://ivoa.net/sso#tls-with-certificate"/>
101 </interface>
102 </capability>
103 \end{verbatim}
105 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}.
107 \subsection{Solution}
109 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{securityMethods}, as this would not allow the constraint of a null securityMethod to work if the endpoint supported other non-null securityMethods. So, VOResource 1.1 has ensures that at most one \xmlel{SecurityMethod} is allowed per \xmlel{interface}.
111 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}.
113 \section{UWS Registry Extension} \label{uwsregext}
115 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.
117 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.
119 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{std:schemaversioning})).
121 \begin{table}
122 \centering
123 \begin{tabular}{| c | c | c |}
124 \hline
125 & Asynchronous & Synchronous \\
126 \hline
127 Interface Type & uws:Async & uws:Sync \\
128 \hline
129 \end{tabular}
130 \caption{UWS Async and Sync interface types}
131 \end{table}
133 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.
135 \subsection{Example TAP 1.1 capability}
137 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.
139 \begin{verbatim}
140 <capability standardID="ivo://ivoa.net/std/TAP">
142 # TAP 1.0 support
143 <capability standardID="ivo://ivoa.net/std/TAP">
144 <interface xsi:type="vod:ParamHTTP" role="std">
145 <accessURL use="base">http://example.com/tap</accessURL>
146 </interface>
147 <interface xsi:type="vod:ParamHTTP" role="std">
148 <accessURL use="base">http://example.com/tap</accessURL>
149 <securityMethod standardID="ivo://ivoa.net/sso#tls-with-certificate"/>
150 </interface>
151 </capability>
153 # TAP 1.1 support
154 <interface
155 xmlns:uws="http://www.ivoa.net/xml/UWSRegExt/v1.0"
156 xsi:type="uws:Sync" role="std" version="1.1">
157 <accessURL use="base">http://example.com/tap/sync</accessURL>
158 </interface>
159 <interface
160 xmlns:uws="http://www.ivoa.net/xml/UWSRegExt/v1.0"
161 xsi:type="uws:Sync" role="std" version="1.1">
162 <accessURL use="base">https://example.com/tap/sync</accessURL>
163 <securityMethod standardID="ivo://ivoa.net/sso#tls-with-certificate"/>
164 </interface>
165 <interface
166 xmlns:uws="http://www.ivoa.net/xml/UWSRegExt/v1.0"
167 xsi:type="uws:Async" role="std" version="1.1">
168 <accessURL use="base">http://example.com/tap/async</accessURL>
169 </interface>
170 <interface
171 xmlns:uws="http://www.ivoa.net/xml/UWSRegExt/v1.0"
172 xsi:type="uws:Async" role="std" version="1.1">
173 <accessURL use="base">https://example.com/tap/async</accessURL>
174 <securityMethod standardID="ivo://ivoa.net/sso#tls-with-certificate"/>
175 </interface>
177 </capability>
178 \end{verbatim}
180 \subsection{XML Schema}
182 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}.
184 \verbatiminput{UWSRegExt-v1.0.xsd}
186 \appendix
187 \section{Changes from Previous Versions}
189 No previous versions yet.
190 % these would be subsections "Changes from v. WD-..."
191 % Use itemize environments.
193 \bibliography{ivoatex/ivoabib,ivoatex/docrepo}
195 \end{document}

ViewVC Help
Powered by ViewVC 1.1.26