/
path2globus.xml
202 lines (202 loc) · 8.59 KB
/
path2globus.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
<?xml version="1.0" encoding="ASCII"?>
<!-- vi: set ts=2 sw=2 et: -->
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<rfc category='info' submissionType='independent' ipr='trust200902' docName="kornel-globus-path-01">
<front>
<title abbrev='Globus ID from FS Paths'>
Globus Endpoint Identification from Filesystem Paths
</title>
<author fullname='A. Karl Kornel' initials='A. K.' surname='Kornel'>
<organization>Stanford University</organization>
<address>
<postal>
<street>Polya Hall</street>
<street>255 Panama Street</street>
<city>Stanford</city>
<region>CA</region>
<code>94305</code>
<country>United States</country>
</postal>
<email>akkornel@stanford.edu</email>
</address>
</author>
</front>
<middle>
<section title='Introduction' anchor='intro'>
<t>Text goes here!</t>
<section title='Conventions Used in This Document' anchor='conventions'>
<t>
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY",
and "OPTIONAL" in this document are to be interpreted as
described in BCP 14
<xref target='RFC2119' />
<xref target='RFC8174' />
when, and only when, they appear in all capitals, as shown here.
</t>
</section>
<section title='Structure of This Document' anchor='structure'>
<t>
After the Introduction, this document is divided into two main
sections. First, <xref target='goals' /> describes the goals (and
non-goals) of the specification. <xref target='spec' /> describes
the Path2Globus specification, with example Path2Globus documents in
<xref target='examples' />. Following the specification,
<xref target='discovery' /> will describe the process implementors
should follow for locating a Path2Globus document.
</t>
</section>
</section><!-- End of intro -->
<section title='Design Goals' anchor='goals'>
<t>
Before describing the specification, it is worth spending some time
setting the 'ground rules' for the specification. This specification
was designed to meet the following goals:
</t>
<t>
<list style='hanging'>
<t hangText='Describe collections serving a directory'>
TBD
</t>
<t hangText='Map local paths to collection paths'>
TBD
</t>
<t hangText='Support multiple collections'>
This goal recognizes the use of the plural "collections" in the previous goal. A path might be served by multiple endpoints (although this does <spanx style='emph'>not</spanx> guarantee that a user has access to all collections).
</t>
<t hangText='Enable collection migration'>
From time to time, the Globus collection(s) serving a path might change. To reflect this in a Path2Globus document, endpoint's must be able to be marked as 'deprecated', telling new users to not use a particlar collection, and telling existing users that they should begin moving away from the collection. Also, collections must be able to identify the collection(s) they are replacing. This goal implies the need to support multiple collections.
</t>
<t hangText='Identify collection features'>
TBD
</t>
</list>
</t>
<t>
There are also a number of <spanx style='emph'>non-goals</spanx>,
which are properties that we are intentionally trying to avoid.
</t>
<t>
<list style='hanging'>
<t hangText='Guarantee accuracy'>
The presence of an endpoint in a Path2Globus document does not
guarantee that the information is valid at the time the client
attempts to use it. It is up to clients to confirm that the endpoint
information is valid. <xref target='discovery' />
includes an example of how this might be done.
</t>
<t hangText='Guarantee access'>
Even if the endpoints listed in the Path2Globus document are
accurate, a user's ability to read the document does not guarantee
the user access to any of the endpoints listed in the document.
Again, <xref target='discovery' /> includes an example of how
this might be checked.
</t>
<t hangText='Include user or group information'>
As mentioned in the previous non-goal, a user with access to the
Path2Globus document does not immediately know that they are able
to use any of the endpoints listed in the document. Endpoint
administrators are able to restrict an endpoint's access to
specific users. It is an intentional decision to
<spanx style='emph'>not</spanx>
include this information in the Path2Globus document. Including
that information leaks information about who the authorized users
and groups are for an endpoint. For storage that may be mounted
across different environments, that may not be readily apparent to
users.
</t>
</list>
</t>
</section><!-- End of goals -->
<section title='The Path2Globus Specification' anchor='spec'>
<t>
A Path2Globus document is a document written in the JavaScript Object
Notation (JSON) format, as specified in <xref target='JSON'/>.
The document's media type is
<spanx style='verb'>application/json</spanx> , and its file extension
is <spanx style='verb'>.json </spanx>. The file MUST use the UTF-8
encoding and MUST NOT include a byte order mark.
</t>
<t>
A Path2Globus document contains a single JSON array (the "document
root"). If the document contains any other JSON value at its root, or
there is any non-whitespace content before or after the array (where
"whitespace" is defined as a space, horizontal tab, line feed, or
carriage return), the document is not a valid Path2Globus document
and MUST be rejected.
</t>
<t>
The document root contains one or more JSON object as array members.
</t>
<t>
Content continues!
</t>
</section><!-- End of spec -->
<section title='Globus Path File Discovery' anchor='discovery'>
<t>Discovery goes here!</t>
</section><!-- End of discovery -->
</middle>
<back>
<references>
<reference anchor='JSON'>
<front>
<title>
The JavaScript Object Notation (JSON) Data Interchange Format
</title>
<author fullname='T. Bray' initials='T.' surname='Bray' role='editor'>
<organization>Textuality</organization>
</author>
<date month='December' year='2017' />
</front>
<seriesInfo name='RFC' value='8259' />
<seriesInfo name='STD' value='90' />
</reference>
<reference anchor='RFC2119'>
<front>
<title>
Key words for use in RFCs to Indicate Requirement Levels
</title>
<author fullname='S. Bradner' initials='S.' surname='Bradner'>
<organization>Harvard University</organization>
</author>
</front>
<seriesInfo name='BCP' value='14' />
<seriesInfo name='RFC' value='8174' />
</reference>
<reference anchor='RFC8174'>
<front>
<title>
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words
</title>
<author fullname='B. Leiba' initials='B.' surname='Leiba'>
<organization>Huawei Technologies</organization>
</author>
<date month='May' year='2017' />
</front>
<seriesInfo name='BCP' value='14' />
<seriesInfo name='RFC' value='8174' />
</reference>
</references>
<section title='Examples' anchor='examples'>
<section title='No endpoints available' anchor='ex-no-endpoint'>
<t>
In this example, the space owner is declaring that this space does
not have a corresponding Globus endpoint. By making the declaration
authoritative, any program searching for a Globus endpoint MUST stop
searching at this point.
</t>
<figure>
<artwork type='application/json'><![CDATA[
[
{
"v": 1,
"authoritative": true,
"endpoints": []
}
]
]]></artwork>
</figure>
</section>
</section><!-- End of examples -->
</back>
</rfc>