Implement an S3 URI

[carlspring]

Task Description

We need to implement an S3URI class. Unfortunately, this class cannot simply extend java.net.URI, because: As it's final, we'll need to create a wrapper class that can return an instance of a java.net.URI and have a URI toUri() method.

S3 Formats

• Path
  • Description This format will gradually be phased out, but is what is still most used. As explain in this post:

    Original Plan – Support for the path-style model ends on September 30, 2020.

    Revised Plan – Support for the path-style model continues for buckets created on or before September 30, 2020. Buckets created after that date must be referenced using the virtual-hosted model.

    We are moving to virtual-hosted references for two reasons: First, anticipating a world with billions of buckets homed in many dozens of regions, routing all incoming requests directly to a small set of endpoints makes less and less sense over time. DNS resolution, scaling, security, and traffic management (including DDoS protection) are more challenging with this centralized model. The virtual-hosted model reduces the area of impact (which we call the “blast radius” internally) when problems arise; this helps us to increase availability and performance.

    Second, the team has a lot of powerful features in the works, many of which depend on the use of unique, virtual-hosted style subdomains. Moving to this model will allow you to benefit from these new features as soon as they are announced. For example, we are planning to deprecate some of the oldest security ciphers and versions (details to come later). The deprecation process is easier and smoother (for you and for us) if you are using virtual-hosted references.

  • Format
  • s3://[endpoint/]bucket[/directory/file]
  • Examples
  • s3://s3.eu-west-2.amazonaws.com/myBucket/resources/image1.png
  • s3://myBucket/resources/image1.png
  • s3:///resources/image1.png (needs to be confirmed, but seen in the source code)
• Virtual
  • Description
  • This is the transitional format between Path-style and ARN.
  • Format
  • https://bucket-name.s3.[region.]amazonaws.com/key
  • Examples
  • https://jbarr-public.s3.amazonaws.com/images/ritchie_and_thompson_pdp11.jpeg
  • https://my-bucket.s3.us-west-2.amazonaws.com/puppy.png
• ARN (Amazon Resource Names)
  • Description
  • Amazon Resource Names (ARNs) uniquely identify AWS resources. An ARN is required when you need to specify a resource unambiguously across all of AWS, such as in IAM policies, Amazon Relational Database Service (Amazon RDS) tags, and API calls. This can be used for S3 as well and it is going to be the new way to address paths.
  • Format
  • s3://arn:aws:s3:[region]:[account-id]:accesspoint/[ap-name]/
  • s3://arn:partition:service:region:account-id:resource-id
  • s3://arn:partition:service:region:account-id:resource-type/resource-id
  • s3://arn:partition:service:region:account-id:resource-type:resource-id
  • Examples
  • s3://arn:aws:s3:::awsexamplebucket1/debug.log
  • s3://arn:aws:s3:us-west-2:123456789012:accesspoint/example-vpc-ap/object/my-file.txt

Tasks

The following tasks will need to be carried out:

• [ ] Implement an S3URI class.
• [ ] Add extensive tests.

Task Relationships

This task:

• Is a sub-task of: #
• Depends on: #
• Is a follow-up of: #
• Relates to: #131 , aws/aws-sdk-java-v2#272

Useful Links

• Amazon S3 path deprecation plan: The rest of the story
• AWS ARN-s and namespaces
• Virtual Hosting

Help

• Our chat channel
• Points of contact:
  • @carlspring
  • @steve-todorov

[steve-todorov]

This task might be obsoleted as of aws-sdk-java-v2@v2.20.41 which includes an S3Uri.class.