brioche/s3

Bun implements native S3 Client, built directly in the runtime. S3 Client is highly optimized, and rely on JavaScript Core internals for some part of the client.

Because S3 is built in the runtime, it allows you to use Bun.File directly with the S3 protocol, or to consider S3 files as native Bun.File. This can help when reading or returning S3 data to your client, or when manipulating files between your servers or S3.

In case you dislike the API, or you need different features, feel free to use any other S3 client.

Bun Documentation

Types

Amazon S3 access control lists (ACLs) enable you to manage access to buckets and objects. Each bucket and object has an ACL attached to it as a subresource. It defines which AWS accounts or groups are granted access and the type of access. When a request is received against a resource, Amazon S3 checks the corresponding ACL to verify that the requester has the necessary access permissions.

AWS Documentation

pub type Acl {
  Private
  PublicRead
  PublicReadWrite
  AwsExecRead
  AuthenticatedRead
  BucketOwnerRead
  BucketOwnerFullControl
  LogDeliveryWrite
}

Constructors

  • Private
  • PublicRead
  • PublicReadWrite
  • AwsExecRead
  • AuthenticatedRead
  • BucketOwnerRead
  • BucketOwnerFullControl
  • LogDeliveryWrite

Communicating with S3 in Bun can be done in a silent, implicit way. However, Brioche requires you to setup a client to interact with S3. Implicit interaction can still be used with file, with the s3:// protocol as file.

Instanciating a client should be done with a config. Every config is customisable, but lot of option can be set using environment variables. In case of implicit interaction, environment variables are the only way to configure the connection to S3.

More details can be found on Config.

// Using S3 with a client.
let client =
  s3.config()
  |> s3.bucket("my-bucket")
  |> s3.client
let file = s3.file(client, "my-file.txt")

// Using S3 implicitely.
file.new("s3://my-bucket/my-file.txt")
pub type Client

Configure a connection to S3. Default Config can be created by using config.

pub type Config {
  Config(
    acl: Option(Acl),
    bucket: Option(String),
    region: Option(String),
    access_key_id: Option(String),
    secret_access_key: Option(String),
    session_token: Option(String),
    endpoint: Option(String),
    virtual_hosted_style: Option(Bool),
    part_size: Option(Int),
    queue_size: Option(Int),
    retry: Option(Int),
    mime_type: Option(String),
    storage_class: Option(StorageClass),
  )
}

Constructors

  • Config(
      acl: Option(Acl),
      bucket: Option(String),
      region: Option(String),
      access_key_id: Option(String),
      secret_access_key: Option(String),
      session_token: Option(String),
      endpoint: Option(String),
      virtual_hosted_style: Option(Bool),
      part_size: Option(Int),
      queue_size: Option(Int),
      retry: Option(Int),
      mime_type: Option(String),
      storage_class: Option(StorageClass),
    )

    Arguments

    acl

    Default ACL for files.

    bucket

    S3 Bucket name. Reads S3_BUCKET or AWS_BUCKET environment variables if not provided.

    region

    AWS region. Reads S3_REGION or AWS_REGION environment variable if not provided.

    access_key_id

    Access Key ID for authentication. Reads S3_ACCESS_KEY_ID or AWS_ACCESS_KEY_ID environment variable if not provided.

    secret_access_key

    Secret Key ID for authentication. Reads S3_SECRET_ACCESS_KEY or AWS_SECRET_ACCESS_KEY environment variable if not provided.

    session_token

    Optional session token for temporary credentials. Reads S3_SESSION_TOKEN or AWS_SESSION_TOKEN environment variable if not provided.

    endpoint

    S3-compatible service endpoint. Reads S3_ENDPOINT or AWS_ENDPOINT environment variable if not provided.

    virtual_hosted_style

    Activate or deactive virtual hosted style. Defaults to False.

    part_size

    The size of each part in multipart uploads (in bytes).

    • Minimum: 5 MiB
    • Maximum: 5120 MiB
    • Default: 5 MiB
    queue_size

    Number of parts to upload in parallel for multipart uploads.

    • Default: 5
    • Maximum: 255

    Increasing this value can improve upload speeds for large files but will use more memory.

    retry

    Number of retry attempts for failed uploads.

    • Default: 3
    • Maximum: 255
    mime_type

    The Mime-Type of the file. Automatically set based on file extension when possible.

    storage_class

    By default, Amazon S3 uses the STANDARD Storage Class to store newly created objects.

Configuration for presigning URL.

pub type Presign {
  Presign(
    file: String,
    method: Option(http.Method),
    expires_in: Option(Int),
    acl: Option(Acl),
    mime_type: Option(String),
  )
}

Constructors

  • Presign(
      file: String,
      method: Option(http.Method),
      expires_in: Option(Int),
      acl: Option(Acl),
      mime_type: Option(String),
    )

    Arguments

    file

    File to presign.

    method

    Only Get, Post, Put, Head, Delete methods are supported.

    expires_in

    Defines the expiration delay, in seconds.

    acl

    Defines the ACL for the file.

    mime_type

    Defines the mime-type of a file. It’s not needed to be set by default.

Each object in Amazon S3 has a storage class associated with it. By default, objects in S3 are stored in the S3 Standard storage class, however Amazon S3 offers a range of other storage classes for the objects that you store. You choose a class depending on your use case scenario and performance access requirements. Choosing a storage class designed for your use case lets you optimize storage costs, performance, and availability for your objects. All of these storage classes offer high durability.

AWS Documentation

pub type StorageClass {
  Standard
  DeepArchive
  ExpressOnezone
  Glacier
  GlacierIr
  IntelligentTiering
  OnezoneIa
  Outposts
  ReducedRedundancy
  Snow
  StandardIa
}

Constructors

  • Standard
  • DeepArchive
  • ExpressOnezone
  • Glacier
  • GlacierIr
  • IntelligentTiering
  • OnezoneIa
  • Outposts
  • ReducedRedundancy
  • Snow
  • StandardIa

Functions

pub fn access_key_id(
  config: Config,
  access_key_id: String,
) -> Config

Set access key ID for the client for authentication. Reads S3_ACCESS_KEY_ID or AWS_ACCESS_KEY_ID environment variable if not provided.

s3.config()
|> s3.access_key_id("key")
pub fn acl(config: Config, acl: Acl) -> Config

Set default ACL for the client.

s3.config()
|> s3.acl(s3.Public)
pub fn bucket(config: Config, bucket: String) -> Config

Set bucket for the client. Reads S3_BUCKET or AWS_BUCKET environment variables if not provided.

s3.config()
|> s3.bucket("my-bucket")
pub fn client(config: Config) -> Client

Create a S3 client from a config.

s3.config()
|> s3.client
pub fn config() -> Config

Create a new empty config.

pub fn endpoint(config: Config, endpoint: String) -> Config

Set endpoint for the client. Reads S3_ENDPOINT or AWS_ENDPOINT environment variable if not provided.

s3.config()
|> s3.endpoint("http://endpoint")
pub fn file(client: Client, path: String) -> File

Create a file from a S3 client. S3 files are compatible with Bun File like files stored directly on file system.

s3.config()
|> s3.client
|> s3.file("my-file.txt")
|> file.read
pub fn generate_url(presign: Presign, client: Client) -> String

Generate presigned URL for Presign configuration.

s3.presign("my-file")
|> s3.generate_url
pub fn mime_type(config: Config, mime_type: String) -> Config

Set the Mime-Type of files for the client. Automatically set based on file extension when possible.

s3.config()
|> s3.mime_type("application/json")
pub fn part_size(config: Config, part_size: Int) -> Config

Set the size of each part in multipart uploads (in bytes) for the client.

  • Minimum: 5 MiB
  • Maximum: 5120 MiB
  • Default: 5 MiB
s3.config()
|> s3.part_size(1024 * 5)
pub fn presign(file: String) -> Presign

When your production service needs to let users upload files to your server, it’s often more reliable for the user to upload directly to S3 instead of your server acting as an intermediary.

To facilitate this, you can presign URLs for S3 files. This generates a URL with a signature that allows a user to securely upload that specific file to S3, without exposing your credentials or granting them unnecessary access to your bucket.

The default behaviour is to generate a GET URL that expires in 24 hours. Bun attempts to infer the content type from the file extension. If inference is not possible, it will default to application/octet-stream.

s3.presign("my-file")
|> s3.generate_url
pub fn presign_acl(presign: Presign, acl: Acl) -> Presign

Defines the ACL for the file.

s3.presign("my-file")
|> s3.presign_acl(s3.Public)
pub fn presign_expires_in(
  presign: Presign,
  expires_in: Int,
) -> Presign

Defines the expiration delay, in seconds.

s3.presign("my-file")
|> s3.presign_expires_in(3600)
pub fn presign_method(
  presign: Presign,
  method: Method,
) -> Presign

Only Get, Post, Put, Head, Delete methods are supported.

s3.presign("my-file")
|> s3.presign_method(http.Get)
pub fn presign_mime_type(
  presign: Presign,
  mime_type: String,
) -> Presign

Defines the mime-type of a file. It’s not needed to be set by default.

s3.presign("my-file")
|> s3.presign_mime_type("application/json")
pub fn queue_size(config: Config, queue_size: Int) -> Config

Set the number of parts to upload in parallel for multipart uploads for the client.

  • Default: 5
  • Maximum: 255

Increasing this value can improve upload speeds for large files but will use more memory.

s3.config()
|> s3.queue_size(5)
pub fn region(config: Config, region: String) -> Config

Set region for the client. Reads S3_REGION or AWS_REGION environment variable if not provided.

s3.config()
|> s3.region("eu-west3")
pub fn retry(config: Config, retry: Int) -> Config

Set the number of retry attempts for failed uploads for the client.

  • Default: 3
  • Maximum: 255
s3.config()
|> s3.retry(3)
pub fn secret_access_key(
  config: Config,
  secret_access_key: String,
) -> Config

Set secret access key for the client for authentication. Reads S3_SECRET_ACCESS_KEY or AWS_SECRET_ACCESS_KEY environment variable if not provided.

s3.config()
|> s3.secret_access_key("key")
pub fn session_token(
  config: Config,
  session_token: String,
) -> Config

Set optional session token for temporary credentials. Reads S3_SESSION_TOKEN or AWS_SESSION_TOKEN environment variable if not provided.

s3.config()
|> s3.secret_access_key("key")
pub fn storage_class(
  config: Config,
  storage_class: StorageClass,
) -> Config

Set the default Storage Class for created objects. By default, Amazon S3 uses the STANDARD Storage Class to store newly created objects.

s3.config()
|> s3.storage_class(s3.Standard)
pub fn virtual_hosted_style(
  config: Config,
  virtual_hosted_style: Bool,
) -> Config

Set virtual hosted style for the client.

s3.config()
|> s3.virtual_hosted_style(True)
Search Document