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.
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.
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
orAWS_BUCKET
environment variables if not provided. - region
-
AWS region. Reads
S3_REGION
orAWS_REGION
environment variable if not provided. - access_key_id
-
Access Key ID for authentication. Reads
S3_ACCESS_KEY_ID
orAWS_ACCESS_KEY_ID
environment variable if not provided. - secret_access_key
-
Secret Key ID for authentication. Reads
S3_SECRET_ACCESS_KEY
orAWS_SECRET_ACCESS_KEY
environment variable if not provided. - session_token
-
Optional session token for temporary credentials. Reads
S3_SESSION_TOKEN
orAWS_SESSION_TOKEN
environment variable if not provided. - endpoint
-
S3-compatible service endpoint. Reads
S3_ENDPOINT
orAWS_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.
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 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)