ViewVC logotype

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

Parent Directory Parent Directory | Revision Log Revision Log

Revision 5005 - (hide annotations)
Thu May 24 19:12:17 2018 UTC (2 years, 4 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 major.brian 4969 \documentclass[11pt,a4paper]{ivoa}
2     \input tthdefs
4 major.brian 5005 \usepackage{verbatim}
5 major.brian 4969
6 major.brian 5005 \title{UWS Registry Extension}
7 major.brian 4969
8 major.brian 5005 \ivoagroup{Grid and Web Services}
9 major.brian 4969
10 major.brian 5005 \author{Brian Major}
11     \author{Markus Demleitner}
12     \author{Patrick Dowler}
13 major.brian 4969
14 major.brian 5005 \editor{Brian Major}
16 major.brian 4969 \previousversion{This is the first public release}
18     \begin{document}
19     \begin{abstract}
21 major.brian 5005 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.
22 major.brian 4969
23 major.brian 5005 \end{abstract}
24 major.brian 4969
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 major.brian 5005 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.
42 major.brian 4969
43 major.brian 5005 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.
44 major.brian 4969
45 major.brian 5005 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 major.brian 4969 \centering
123 major.brian 5005 \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}
132 major.brian 4969
133 major.brian 5005 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.
134 major.brian 4969
135 major.brian 5005 \subsection{Example TAP 1.1 capability}
136 major.brian 4969
137 major.brian 5005 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.
138 major.brian 4969
139 major.brian 5005 \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}
179 major.brian 4969
180 major.brian 5005 \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 major.brian 4969 \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