jhn_s3c (α)

View Source

A partial S3 Erlang client lib

Introduction

A partial S3 Erlang client lib that only supports a few methods and AWS Signature Version 2. Will be expanded.

Configuration

New (Multiple servers):

If the servers is config is undefined or the empty list the old (legacy) configuation is used. If at least one server is defined any definitions of host, port, access_key_id, or access_key are ignored.

The first server config is always the default server so if one of the functions are called without the server option defined that is the one called.

All the config values except servers acts as default values if defined but will be overridden by the server config if that is defined. So for example the request_type if not defined at the top level or for a the server will have the default value of path, but if set to say virtual_host it will have that value for all servers not defining it, and if a server defines it to path well then that particular server will use the virtual_host request type.

The default for request_type is path in the new configuration unlike the old.

  • servers ([]): a list of server configurations
  • request_type (path): connection mode either virtual_host or path
  • protocol (http): either http or https
  • hackney_opts ([]): additional options provided to the hackney request
  • hackney_pool (jhn_s3): which hackney pool to use
  • max_tries (3): the max number of request tries including inital and retries

Server configuration:

  • request_type (path): connection mode either virtual_host or path
  • protocol (http): either http or https
  • host (~"localhost"): either a hostname or ip-address
  • port (80): the port number as an integer
  • hackney_opts ([]): additional options provided to the hackney request
  • hackney_pool (jhn_s3): which hackney pool to use
  • max_tries (3): the max number of request tries including inital and retries
  • access_key_id: the user/access_key_id for S3
  • access_key: password/access_key for S3

Example: From the test suite where the protocol definition being strictly speeking redundant but harmless and acts a default for server_a and server_b.

[{kernel, [{inetrc, "test/inetrc"}]},
 {jhn_s3c,
  [{servers,
    [{server_a, [{host, ~"s3.service"}, {port, 9000},
                 {access_key_id, ~"admin"}, {access_key, ~"password"}]},
     {server_b, [{host, ~"s3bis.service"}, {port, 8000},
                 {access_key_id, ~"hugo"}, {access_key, ~"password"}]}]},
   {protocol, http}
  ]
 }
].

Old (legacy will be discontinued with theh next major release):

  • request_type (path): connection mode either virtual_host or path
  • protocol (http): either http or https
  • host (~"localhost"): either a hostname or ip-address
  • port (80): the port number as an integer
  • hackney_opts ([]): additional options provided to the hackney request
  • hackney_pool (jhn_s3): which hackney pool to use
  • max_tries (3): the max number of request tries including inital and retries
  • access_key_id: the user/access_key_id for S3
  • access_key: password/access_key for S3
[{kernel, [{inetrc, "test/inetrc"}]},
 {jhn_s3c,
  [{protocol, http},
   {host, ~"s3.service"},
   {port, 9000},
   {access_key_id, "admin"},
   {access_key, "password"}]}].

Build

jhn_s3c requires rebar3 to build, but provides make support to download and install rebar. To build jhn_s3c, go to the jhn_s3c directory and type:

make

To make sure jhn_s3c works on your platform, run the tests (reuquires docker):

make ci

Contribute

Should you find yourself using jhn_s3c and have issues, comments or feedback please create an issue here on GitHub.

Patches are greatly appreciated, but since these libraries reflect my learning process and I have rather peculiar notions of code hygiene

For a much nicer history, please write good commit messages. I know I really should.