BLM::Startup::S3 - Bedrock Application Plugin for AWS S3
Create a s3.xml configuration file and drop it in the usual places
Bedrock looks for config files.
<object>
<scalar name="binding">s3</scalar>
<scalar name="module">BLM::Startup::S3</scalar>
<object name="config">
<scalar name="bucket">treasurersbriefcase-development</scalar>
</object>
</object>
A LocalStack configuration...
<object>
<scalar name="binding">s3</scalar>
<scalar name="module">BLM::Startup::S3</scalar>
<object name="config">
<scalar name="aws_access_key_id">test</scalar>
<scalar name="aws_secret_access_key">test</scalar>
<scalar name="region">us-east-1</scalar>
<scalar name="host">localhost:4566</scalar>
<scalar name="secure">false</scalar>
<scalar name="dns_bucket_names">0</scalar>
</object>
</object>
Usage in Bedrock:
<null:list $s3.list_bucket('delimiter', '/') >
Provides a convenient, Bedrock-optimized interface to Amazon::S3. These routines return Bedrock objects (hashes/arrays) instead of raw Perl structures, making them easier to use in templates.
You can still access the raw Amazon::S3 object if you need deep magic:
<null:s3_client $s3.get_s3()>
<null:result $s3_client.list_bucket()>
See Amazon::S3 for details on credential handling. Bedrock supports standard AWS environment variables or explicit config keys.
add_bucket(bucket-name)
Creates a new bucket in the region specified by your configuration.
my $s3 = $self->get_s3;
$s3->add_bucket({ bucket => $bucket_name, ...});
$self->bucket($bucket_name);
NOTE: This does not set the new bucket as the current active bucket. Use bucket() to switch contexts.
add_key(key, value, [ bucket ], metadata-key, metadata-value, ... )
Adds a new object to a bucket.
Arguments:
* key: The path/filename in S3.
* value: The content string (file body).
* bucket: (Optional) An Amazon::S3::Bucket object.
* metadata: Any remaining arguments are treated as metadata key/value pairs.
Example:
<null:readme $s3.get_key('README.md')>
<null:html --markdown $readme.value>
<null $s3.add_key('README.html', $html, 'content-type', 'text/html')>
add_key_filename(key, filename, [ bucket ], metadata-key, metadata-value )
Same as "add_key", but the value argument is a local filesystem path.
The file will be read and uploaded to S3.
Example (Bedrock Shell): echo '<null $s3.add_key_filename("README.md", "/tmp/README.md")>' | \ bedrock --config-var ABSOLUTE_PATHS=yes
bucket(bucket-name)
Switch the active bucket for subsequent calls. If no name is provided, returns the current bucket object.
buckets( [verify_region] )
Returns a Bedrock Array of bucket metadata hashes.
<foreach $s3.buckets>
Bucket: <var $_.bucket> (<var $_.region>)
</foreach>
Fields returned:
* bucket
* creation_date
* region
copy_object(source_key, dest_key, [headers])
Copies an object within the bucket. headers is an optional list of key/value pairs.
Example: <null $s3.copy_object('/resources/info.pdf', '/archive/info-2024.pdf')>
create_session_file(filename, content)
Helper method to save content to the current session's "directory" in S3.
Assuming your session storage is S3-backed, this creates a file at:
session_id/filename.
Returns the relative web path: /session/filename.
delete_keys(key | [keys], [bucket])
Deletes one or more keys. Accepts a single string key or an array reference of keys.
Example: <null:keylist $s3.list_bucket('delimiter', '/', 'prefix', $session.session)> <null $s3.delete_keys($keylist.keys)>
get_key(key, [ bucket ])
Retrieves an object. Returns a hash containing the body and metadata.
Returns:
* value: The object content (body).
* etag: The ETag of the object.
* content_length: Size in bytes.
* content_type: MIME type.
* MetaData: A hash of metadata (x-amz-meta-* stripped).
get_key_value(key, [ bucket ])
Convenience shortcut. Returns only the body content (the value field) of the object.
<var --markdown $s3.get_key_value('README.md')>
list_bucket(args)
List objects in the bucket. Arguments are passed as key/value pairs. See Amazon::S3 for valid arguments (prefix, delimiter, max-keys, etc).
Example: <null:list $s3.list_bucket('delimiter', '/', 'prefix', 'images/', 'max-keys', 100)>
Returns a hash:
* keys: Array of object metadata (key, etag, size, last_modified).
* common_prefixes: Array of "folders" (if delimiter is used).
* is_truncated: Boolean.
* next_marker: Pagination token.
list_bucket_keys( [ bucket => bucket , raw => 1] )
Convenience wrapper around list_bucket. Returns a simple Bedrock Array of
key strings, discarding the metadata.
<foreach $s3.list_bucket_keys()>
Found file: <var $_>
</foreach>
parse_key(key)
Utility to parse an S3 key into filename components (similar to File::Basename).
<null:parts $s3.parse_key('foo/bar/baz.jpg')>
Returns:
* name: baz
* path: foo/bar/
* ext: .jpg
* filename: baz.jpg
set_bucket_name(bucket-name)
Sets the default bucket name for the plugin instance.
Amazon S3 expects metadata headers to be prefixed with x-amz-meta-.
This plugin handles that automatically. You can pass simple names (e.g., account-id)
and they will be converted.
Writing: <null $s3.add_key('report.pdf', $content, 'account-id', 123)>
Reading: <null:obj $s3.get_key('report.pdf')> Account ID: <var $obj.MetaData.account_id>
Note that dashes ('-') in metadata names are converted to underscores ('_').
Amazon::S3, Bedrock::Application::Plugin
Rob Lauer - rlauer@treasurersbriefcase.com