evennia.contrib.base_systems.awsstorage.aws_s3_cdn

AWS Storage System The Right Honourable Reverend (trhr) 2020

ABOUT THIS PLUGIN:

This plugin migrates the Web-based portion of Evennia, namely images, javascript, and other items located inside staticfiles into Amazon AWS (S3) for hosting.

Files hosted on S3 are “in the cloud,” and while your personal server may be sufficient for serving multimedia to a minimal number of users, the perfect use case for this plugin would be:

1. Servers supporting heavy web-based traffic (webclient, etc)

2. With a sizable number of users

3. Where the users are globally distributed

4. Where multimedia files are served to users as a part of gameplay

Bottom line - if you’re sending an image to a player every time they traverse a map, the bandwidth reduction will be substantial. If not, probably skip this one.

Note that storing and serving files via S3 is not technically free outside of Amazon’s “free tier” offering, which you may or may not be eligible for; evennia’s base install currently requires 1.5MB of storage space on S3, making the current total cost to install this plugin ~$0.0005 per year. If you have substantial media assets and intend to serve them to many users, caveat emptor on a total cost of ownership - check AWS’s pricing structure.

See the ./README.md file for details and install instructions.

evennia.contrib.base_systems.awsstorage.aws_s3_cdn.setting(name, default=None)

Helper function to get a Django setting by name. If setting doesn’t exist it will return a default.

Parameters

name (str) – A Django setting name

Returns

The value of the setting variable by that name

evennia.contrib.base_systems.awsstorage.aws_s3_cdn.safe_join(base, *paths)

Helper function, a version of django.utils._os.safe_join for S3 paths. Joins one or more path components to the base path component intelligently. Returns a normalized version of the final path. The final path must be located inside of the base path component (otherwise a ValueError is raised). Paths outside the base path indicate a possible security sensitive operation.

Parameters

• base (str) – A path string to the base of the staticfiles

• *paths (list) – A list of paths as referenced from the base path

Returns

final_path (str) – A joined path, base + filepath

evennia.contrib.base_systems.awsstorage.aws_s3_cdn.check_location(storage)

Helper function to make sure that the storage location is configured correctly.

Parameters

storage (Storage) – A Storage object (Django)

Raises

ImproperlyConfigured – If the storage location is not configured correctly, this is raised.

evennia.contrib.base_systems.awsstorage.aws_s3_cdn.lookup_env(names)

Helper function for looking up names in env vars. Returns the first element found.

Parameters

names (str) – A list of environment variables

Returns

value (str) – The value of the found environment variable.

evennia.contrib.base_systems.awsstorage.aws_s3_cdn.get_available_overwrite_name(name, max_length)

Helper function indicating files that will be overwritten during trunc.

Parameters

• name (str) – The name of the file

• max_length (int) – The maximum length of a filename

Returns

joined (path) – A joined path including directory, file, and extension

class evennia.contrib.base_systems.awsstorage.aws_s3_cdn.S3Boto3StorageFile(*args, **kwargs)

Bases: django.core.files.base.File

The default file object used by the S3Boto3Storage backend. This file implements file streaming using boto’s multipart uploading functionality. The file can be opened in read or write mode. This class extends Django’s File class. However, the contained data is only the data contained in the current buffer. So you should not access the contained file object directly. You should access the data via this class. Warning: This file must be closed using the close() method in order to properly write the file to S3. Be sure to close the file in your application.

__init__(name, mode, storage, buffer_size=None)

Initializes the File object.

Parameters

• name (str) – The name of the file

• mode (str) – The access mode (‘r’ or ‘w’)

• storage (Storage) – The Django Storage object

• buffer_size (int) – The buffer size, for multipart uploads

buffer_size = 5242880

property size

Helper property to return filesize

property file

Helper function to manage zipping and temporary files

read(*args, **kwargs)

Checks if file is in read mode; then continues to boto3 operation

readline(*args, **kwargs)

Checks if file is in read mode; then continues to boto3 operation

write(content)

Checks if file is in write mode or needs multipart handling, then continues to boto3 operation.

close()

Manages file closing after multipart uploads

deconstruct()

Return a 3-tuple of class import path, positional arguments, and keyword arguments.

class evennia.contrib.base_systems.awsstorage.aws_s3_cdn.S3Boto3Storage(*args, **kwargs)

Bases: django.core.files.storage.base.Storage

Amazon Simple Storage Service using Boto3 This storage backend supports opening files in read or write mode and supports streaming(buffering) data in chunks to S3 when writing.

default_content_type = 'application/octet-stream'

access_key_names = ['AWS_S3_ACCESS_KEY_ID', 'AWS_ACCESS_KEY_ID']

secret_key_names = ['AWS_S3_SECRET_ACCESS_KEY', 'AWS_SECRET_ACCESS_KEY']

security_token_names = ['AWS_SESSION_TOKEN', 'AWS_SECURITY_TOKEN']

file_overwrite = True

object_parameters = {}

bucket_name = None

auto_create_bucket = False

default_acl = 'public-read'

bucket_acl = 'public-read'

querystring_auth = True

querystring_expire = 3600

signature_version = None

reduced_redundancy = False

location = ''

encryption = False

custom_domain = None

addressing_style = None

secure_urls = True

file_name_charset = 'utf-8'

gzip = False

preload_metadata = False

gzip_content_types = ('text/css', 'text/javascript', 'application/javascript', 'application/x-javascript', 'image/svg+xml')

endpoint_url = None

proxies = None

region_name = None

use_ssl = True

verify = None

max_memory_size = 0

__init__(acl=None, bucket=None, **settings)

Check if some of the settings we’ve provided as class attributes need to be overwritten with values passed in here.

url_protocol = 'http:'

access_key = ''

secret_key = ''

security_token = None

config = None

property connection

Creates the actual connection to S3

property bucket

Get the current bucket. If there is no current bucket object create it.

property entries

Get the locally cached files for the bucket.

delete(name)

Deletes a file from S3.

exists(name)

Checks if file exists.

listdir(name)

Translational function to go from S3 file paths to the format Django’s listdir expects.

size(name)

Gets the filesize of a remote file.

deconstruct()

Return a 3-tuple of class import path, positional arguments, and keyword arguments.

get_object_parameters(name)

Returns a dictionary that is passed to file upload. Override this method to adjust this on a per-object basis to set e.g ContentDisposition. By default, returns the value of AWS_S3_OBJECT_PARAMETERS. Setting ContentEncoding will prevent objects from being automatically gzipped.

get_modified_time(name)

Returns an (aware) datetime object containing the last modified time if USE_TZ is True, otherwise returns a naive datetime in the local timezone.

modified_time(name)

Returns a naive datetime object containing the last modified time. If USE_TZ=False then get_modified_time will return a naive datetime so we just return that, else we have to localize and strip the tz

url(name, parameters=None, expire=None)

Returns the URL of a remotely-hosted file

get_available_name(name, max_length=None)

Overwrite existing file with the same name.