Separate use-cases for generating signed object references

[jboynes]

There's currently one method for generating signed references:

URL signUrl(BlobInfo blobInfo, long expirationTimeInSeconds, SignUrlOption... options);

There are a number of SignUrlOption types but its not clear from the interface which ones can be used in combination. For example:

• specifying md5 and contentType should not be allowed for a GET, HEAD or DELETE
• for PUT, md5 and contentType take their values from BlobInfo but the object hasn't been created yet

I also don't see how extension headers or the base URL would be specified.

Instead, can we use a method chain for this:

 URI get = datastore.signedReference(bucketName, objectName, expiration).toURI();
 String put = datastore.signedReference(bucketName, objectName, expiration)
 .forPut().ofContentType("text/plain").toString();

[aozarov]

I would prefer not to introduce a new method invocation style (so API is simple to learn/use).

Current styles are:

• standard invocation with options as optional varargs.
• When invocation settings is to complex for the above pass an immutable XXXRequest constructed
  by its associated XXXRequset.Builder

Canonicalized_Extension_Headers option was not added as I found it confusing and I saw that also other clients such as gsutil were selective in what options they expose. However, it should be simple to add as another SignUrlOption if desired.

I am not sure where it is specified that md5 and contentType are not allowed for GET, HEAD,..
My understanding was that GCS mandates that any HTTP request for signed URL with MD5
and/or CONTENT_TYPE must supply a matching header as well. Are you saying the the HTTP
spec does not allow specifying these headers in some of the request types?

In general, after I got that as a feedback from the Datastore review, in the API am a trying to force
a valid request construct but without applying any client-side validation of options that are enforced by the server (and might change one day).

[jboynes]

Content-MD5 and Content-Type both refer to the entity contained in the message. For GET, HEAD and DELETE there is no entity allowed in the request so these would not apply.

They make sense if the user wants to constrain a PUT request so that the client can only upload data of a certain type or specific data. Use-case would be:

1. Client picks file it wants to upload
2. Client makes request to get PUT URI passing media type and md5 of file
3. Server returns signed URI which only allows that media type and file
4. Client uploads data; if content-type or md5 don't match server rejects the upload

That's assuming the client isn't doing a resumable upload.

[aozarov]

@Capstan can you confirm?

[Capstan]

@jboynes is correct. For those HTTP verbs, there'd be no body for which those headers apply. You could specify them, but they'd be at best a no-op (Content-Type: whatever, Content-MD5: 1B2M2Y8AsgTpgAmY7PhCfg==) or worse an error for a MD5 mismatch presuming we check, which I'm not sure we do.

[aozarov]

Ok, good to know.

I don't think this is clear in this documentation and therefore assumed it would be used to verify header matching regardless of the request type.

I assumed it could be used, for example, to provide a signed URL to get a content of specific/version-of blob only if it was not modified (by using the MD5 header).

[Capstan]

Happy to take docs suggestions. Both of them are marked optional in the table in the docs you pointed to, and talk about the request not the response.

Canonical Extension Headers refer to those extension headers that you may want to allow the user to specify. e.g.,

• x-goog-acl if you wanted the user to override the default object acl with something specific
• x-goog-generation if you wanted to pin the request to a specific version
• x-goog-hash to validate CRC32c (or MD5)
• x-goog-meta-* to ensure that specific custom metadata is attached to the object
• x-goog-project-id if listing or creating new buckets

POST policies even allow more specific conditions.

[aozarov]

@mziccard My preference is to keep the library method dispatching style consistent, and minimize on client side validation.

I agree, that we could be more "user-friendly" using the suggestion above for some use-cases.
What do you think?

[mziccard]

I would keep this as simple as possible. I agree that we should not change the library style. I don't think that having a method chain like:

storage.signedReference(bucketName, objectName, expiration)
 .forPut().ofContentType("text/plain").toString();

helps a lot.

AWS APIs use a GeneratePresignedUrlRequest class to set all signed url options, and then a method generatePresignedUrl to generate the URL object. This last method throws exceptions if something goes wrong with signing and I assume it includes some kind of input validation.
We could do something similar, and the style fits with the one of BatchRequest and ComposeRequest. But this clashes with your preference of minimizing client side validation.

[aozarov]

Yes, I doubt that adding another XXXRequest style call is going to help (unless we use subclasses to support the different combination) as I would not want to have runtime validation done by the client (we could actually do that now if we wanted to).

Looks like we both think we can leave it as is, so I am closing it for now.