Skip to content

Commit 0dd6f58

Browse files
JordonPhillipsJordonPhillips
authored
Add docs/tests for Glacier customizations (#704)
This adds documentation and protocol tests for the customizations required to generate Glacier client.
1 parent 61cffbe commit 0dd6f58

File tree

3 files changed

+289
-0
lines changed

3 files changed

+289
-0
lines changed

‎docs/source/1.0/spec/aws/glacier-customizations.rst‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
=============================
2+
Amazon Glacier Customizations
3+
=============================
4+
5+
.. contents:: Table of contents
6+
:depth: 1
7+
:local:
8+
:backlinks: none
9+
10+
11+
--------------------------------
12+
``X-Amz-Glacier-Version`` header
13+
--------------------------------
14+
15+
A client for Amazon Glacier MUST set the ``X-Amz-Glacier-Version`` header to
16+
the value of the service shape's ``version`` property for all requests.
17+
18+
19+
---------------------------
20+
Default value for accountId
21+
---------------------------
22+
23+
Many operations in Amazon Glacier have an ``accountId`` member that is bound
24+
to the URI. Customers can specify the string "-" to indicate that the
25+
account making the request should be used. Since this is what customers
26+
usually want, clients SHOULD set this value by default.
27+
28+
29+
---------------------------
30+
Default checksum generation
31+
---------------------------
32+
33+
When uploading an archive as part of the `UploadArchive`_ or `UploadMultipartPart`_
34+
operations, the ``X-Amz-Content-Sha256`` and ``X-Amz-Sha256-Tree-Hash``
35+
headers MUST be set. Since the logic for computing these headers is static,
36+
clients SHOULD populate them by default. See `computing checksums`_ for details
37+
on how to calculate the values for these headers.
38+
39+
40+
.. _UploadArchive: https://docs.aws.amazon.com/amazonglacier/latest/dev/api-archive-post.html
41+
.. _UploadMultipartPart: https://docs.aws.amazon.com/amazonglacier/latest/dev/api-upload-part.html
42+
.. _computing checksums: https://docs.aws.amazon.com/amazonglacier/latest/dev/checksum-calculations.html

‎docs/source/1.0/spec/aws/index.rst‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,3 +28,13 @@ AWS Protocols
2828
aws-restxml-protocol
2929
aws-query-protocol
3030
aws-ec2-query-protocol
31+
32+
AWS Service Customizations
33+
==========================
34+
35+
.. rst-class:: large-toctree
36+
37+
.. toctree::
38+
:maxdepth: 3
39+
40+
glacier-customizations

‎smithy-aws-protocol-tests/model/restJson1/services/glacier.smithy‎

Lines changed: 237 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,237 @@
1+
$version: "1.0"
2+
3+
metadata suppressions = [{
4+
id: "HttpMethodSemantics",
5+
namespace: "com.amazonaws.glacier",
6+
}]
7+
8+
namespace com.amazonaws.glacier
9+
10+
use aws.api#service
11+
use aws.auth#sigv4
12+
use aws.protocols#restJson1
13+
use smithy.test#httpRequestTests
14+
15+
@service(
16+
sdkId: "Glacier",
17+
arnNamespace: "glacier",
18+
cloudFormationName: "Glacier",
19+
cloudTrailEventSource: "glacier.amazonaws.com",
20+
endpointPrefix: "glacier",
21+
)
22+
@sigv4(
23+
name: "glacier",
24+
)
25+
@restJson1
26+
@title("Amazon Glacier")
27+
@xmlNamespace(
28+
uri: "http://glacier.amazonaws.com/doc/2012-06-01/",
29+
)
30+
service Glacier {
31+
version: "2012-06-01",
32+
operations: [
33+
UploadArchive,
34+
UploadMultipartPart,
35+
],
36+
}
37+
38+
@httpRequestTests([
39+
{
40+
id: "GlacierVersionHeader",
41+
documentation: "Glacier requires that a version header be set on all requests.",
42+
protocol: restJson1,
43+
method: "POST",
44+
uri: "/foo/vaults/bar/archives",
45+
headers: {
46+
"X-Amz-Glacier-Version": "2012-06-01",
47+
},
48+
body: "",
49+
params: {
50+
accountId: "foo",
51+
vaultName: "bar",
52+
},
53+
},
54+
{
55+
id: "GlacierChecksums",
56+
documentation: "Glacier requires checksum headers that are cumbersome to provide.",
57+
protocol: restJson1,
58+
method: "POST",
59+
uri: "/foo/vaults/bar/archives",
60+
headers: {
61+
"X-Amz-Glacier-Version": "2012-06-01",
62+
"X-Amz-Content-Sha256": "b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9",
63+
"X-Amz-Sha256-Tree-Hash": "b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9",
64+
},
65+
body: "hello world",
66+
params: {
67+
accountId: "foo",
68+
vaultName: "bar",
69+
},
70+
appliesTo: "client",
71+
},
72+
{
73+
id: "GlacierAccountId",
74+
documentation: """
75+
Glacier requires that the account id be set, but you can just use a
76+
hyphen (-) to indicate the current account. This should be default
77+
behavior if the customer provides a null or empty string.""",
78+
protocol: restJson1,
79+
method: "POST",
80+
uri: "/-/vaults/bar/archives",
81+
headers: {
82+
"X-Amz-Glacier-Version": "2012-06-01",
83+
},
84+
body: "",
85+
params: {
86+
accountId: "",
87+
vaultName: "bar",
88+
},
89+
appliesTo: "client",
90+
}
91+
])
92+
@http(
93+
method: "POST",
94+
uri: "/{accountId}/vaults/{vaultName}/archives",
95+
code: 201,
96+
)
97+
operation UploadArchive {
98+
input: UploadArchiveInput,
99+
output: ArchiveCreationOutput,
100+
errors: [
101+
InvalidParameterValueException,
102+
MissingParameterValueException,
103+
RequestTimeoutException,
104+
ResourceNotFoundException,
105+
ServiceUnavailableException,
106+
],
107+
}
108+
109+
@httpRequestTests([
110+
{
111+
id: "GlacierMultipartChecksums",
112+
documentation: "Glacier requires checksum headers that are cumbersome to provide.",
113+
protocol: restJson1,
114+
method: "POST",
115+
uri: "/foo/vaults/bar/multipart-uploads/baz",
116+
headers: {
117+
"X-Amz-Glacier-Version": "2012-06-01",
118+
"X-Amz-Content-Sha256": "b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9",
119+
"X-Amz-Sha256-Tree-Hash": "b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9",
120+
},
121+
body: "hello world",
122+
params: {
123+
accountId: "foo",
124+
vaultName: "bar",
125+
uploadId: "baz",
126+
},
127+
appliesTo: "client",
128+
}
129+
])
130+
@http(
131+
method: "PUT",
132+
uri: "/{accountId}/vaults/{vaultName}/multipart-uploads/{uploadId}",
133+
code: 204,
134+
)
135+
operation UploadMultipartPart {
136+
input: UploadMultipartPartInput,
137+
output: UploadMultipartPartOutput,
138+
errors: [
139+
InvalidParameterValueException,
140+
MissingParameterValueException,
141+
RequestTimeoutException,
142+
ResourceNotFoundException,
143+
ServiceUnavailableException,
144+
],
145+
}
146+
147+
structure ArchiveCreationOutput {
148+
@httpHeader("Location")
149+
location: string,
150+
@httpHeader("x-amz-sha256-tree-hash")
151+
checksum: string,
152+
@httpHeader("x-amz-archive-id")
153+
archiveId: string,
154+
}
155+
156+
@error("client")
157+
@httpError(400)
158+
structure InvalidParameterValueException {
159+
type: string,
160+
code: string,
161+
message: string,
162+
}
163+
164+
@error("client")
165+
@httpError(400)
166+
structure MissingParameterValueException {
167+
type: string,
168+
code: string,
169+
message: string,
170+
}
171+
172+
@error("client")
173+
@httpError(408)
174+
structure RequestTimeoutException {
175+
type: string,
176+
code: string,
177+
message: string,
178+
}
179+
180+
@error("client")
181+
@httpError(404)
182+
structure ResourceNotFoundException {
183+
type: string,
184+
code: string,
185+
message: string,
186+
}
187+
188+
@error("server")
189+
@httpError(500)
190+
structure ServiceUnavailableException {
191+
type: string,
192+
code: string,
193+
message: string,
194+
}
195+
196+
structure UploadArchiveInput {
197+
@httpLabel
198+
@required
199+
vaultName: string,
200+
@httpLabel
201+
@required
202+
accountId: string,
203+
@httpHeader("x-amz-archive-description")
204+
archiveDescription: string,
205+
@httpHeader("x-amz-sha256-tree-hash")
206+
checksum: string,
207+
@httpPayload
208+
body: Stream,
209+
}
210+
211+
structure UploadMultipartPartInput {
212+
@httpLabel
213+
@required
214+
accountId: string,
215+
@httpLabel
216+
@required
217+
vaultName: string,
218+
@httpLabel
219+
@required
220+
uploadId: string,
221+
@httpHeader("x-amz-sha256-tree-hash")
222+
checksum: string,
223+
@httpHeader("Content-Range")
224+
range: string,
225+
@httpPayload
226+
body: Stream,
227+
}
228+
229+
structure UploadMultipartPartOutput {
230+
@httpHeader("x-amz-sha256-tree-hash")
231+
checksum: string,
232+
}
233+
234+
@streaming
235+
blob Stream
236+
237+
string string

0 commit comments

Comments
 (0)