Using Amazon S3 As Temporary Storage In Lucee CFML 5.3.6.61

<cfscript>

	jarPaths = directoryList(
		path = expandPath( "../aws-s3-sdk/" ),
		recurse = true,
		listInfo = "path",
		type = "file",
		filter = "*.jar"
	);

	s3Client = new S3Client(
		awsAccessID = server.aws.accessID,
		awsSecretKey = server.aws.secretKey,
		awsRegion = server.aws.region,
		awsBucket = server.aws.bucket,
		jarPaths = jarPaths
	);

	// ------------------------------------------------------------------------------- //
	// ------------------------------------------------------------------------------- //

	// Let's create a bunch of test files that we can subsequently delete, yay!
	for ( i = 1 ; i <= 25 ; i++ ) {

		moment = dateConvert( "local2utc", now() );
		// When we later "list" the objects in the "/ttl/" prefix, AWS will always return
		// the objects in lexicographic (alphabetical) order. As such, we want to store
		// the objects using a fixed-width date/time prefix. This way, the "oldest"
		// objects will always be the first ones returned during list-pagination.
		dateToken = moment.dateFormat( "yyyy-mm-dd" );
		timeToken = moment.timeFormat( "HH-mm-ss" );
		uuidToken = createUUID().lcase();

		// NOTE: We're adding a path-delimiter between the Date and Time just to make the
		// AWS console easier to navigate (since it will group the common date-prefixes
		// into a "folder like" structures in which each date is its own folder).
		resourcePath = "/ttl/#dateToken#/#timeToken#-uuid-#uuidToken#.txt";

		s3Client.putObject(
			resourcePath,
			charsetDecode( "Hello world, testing with #resourcePath#.", "utf-8" ),
			"text/plain"
		);

	}

</cfscript>

<cfscript>

	jarPaths = directoryList(
		path = expandPath( "../aws-s3-sdk/" ),
		recurse = true,
		listInfo = "path",
		type = "file",
		filter = "*.jar"
	);

	s3Client = new S3Client(
		awsAccessID = server.aws.accessID,
		awsSecretKey = server.aws.secretKey,
		awsRegion = server.aws.region,
		awsBucket = server.aws.bucket,
		jarPaths = jarPaths
	);

	// ------------------------------------------------------------------------------- //
	// ------------------------------------------------------------------------------- //

	// The objects located under the "TTL" path-prefix are stored with a fixed-width
	// date/time prefix. As such, the lexicographic (alphabetical) order of the Listing
	// will ensure that the oldest files are returned first. Therefore, we are going to
	// keep getting (and deleting) the first page of objects until we hit one that is too
	// young to delete.
	do {

		// NOTE: For this exploration, I'm using low numbers (MaxKeys and Cutoffs). But,
		// in a production environment, I'd use larger values.

		// NOTE: When listing the objects, we don't need to use a "continuation key"
		// because we are DELETING the oldest objects within each do-while iteration. As
		// such, every "next" iteration of this loop just has to get the oldest files
		// that STILL EXIST (which, lexicographically, are going to be the first ones
		// returned in the list operation).
		results = s3Client.listObjects(
			resourcePathPrefix = "/ttl/",
			maxKeys = 5
		);

		// The AWS API returns the "lastModified" date in the UTC timezone. As such, we
		// have to convert the local date to UTC when calculating the cutoff.
		// --
		// NOTE: In a production environment, the server would likely running in UTC as
		// well and this step would be superfluous. However, I like to leave my local
		// development environment running in EST so that I can more easily spot date-
		// handling errors in my logic. Meaning, I don't want my code to ASSUME that it
		// is running in UTC - I want it to always convert to UTC explicitly.
		cutoffAt = now().add( "n", -3 );
		cutoffAtUTC = dateConvert( "local2utc", cutoffAt );

		pathsToDelete = results.objects
			// Limit to objects older than the cut-off.
			.filter(
				( summary ) => {

					return( summary.lastModified < cutoffAtUTC );

				}
			)
			// Map the object summaries to raw S3 paths (which we will delete).
			.map(
				( summary ) => {

					return( summary.key );

				}
			)
		;

		// If this batch of object listings resulted in any S3 objects to delete, we can
		// perform a multi-object delete of up to 1,000 keys (the max number of keys
		// allowed by AWS at the time of this writing).
		if ( pathsToDelete.len() ) {

			echo( "PATHS: <br />" );
			echo( pathsToDelete.toList( "<br />" ) );
			echo( "<br /><br />" );

			s3Client.deleteObjects( pathsToDelete );

		}

		// Since we are going to continue looping until we hit an object that is too
		// young to delete, we know that we can short-circuit the process if the filtered
		// paths don't match the raw results. The moment we have more results than we
		// have paths to delete, we know that the current iteration came across an object
		// that crossed-over the cutoff-line (ie, was too young to delete).
		doContinueDeleting = (
			results.isTruncated &&
			( pathsToDelete.len() == results.objects.len() )
		);

	} while ( doContinueDeleting );
	
	echo( "Done deleting." );

</cfscript>

component
	output = false
	hint = "I provide a simple wrapper for the S3 Client JDK classes."
	{

	/**
	* I initialize the S3 Client wrapper with the given configuration.
	*/
	public void function init(
		required string awsAccessID,
		required string awsSecretKey,
		required string awsRegion,
		required string awsBucket,
		required array jarPaths
		) {

		variables.awsAccessID = arguments.awsAccessID;
		variables.awsSecretKey = arguments.awsSecretKey;
		variables.awsRegion = arguments.awsRegion;
		variables.awsBucket = arguments.awsBucket;
		variables.jarPaths = arguments.jarPaths;

		variables.s3Client = createS3Client();

	}

	// ---
	// PUBLIC METHODS.
	// ---

	/**
	* I delete the objects located at the given paths.
	* 
	* CAUTION: At the time of this writing, a maximum of 1,000 paths can be deleted at
	* one time.
	* 
	* @resourcePaths I am the collection of keys to delete.
	*/
	public struct function deleteObjects( required array resourcePaths ) {

		var normalizedPaths = resourcePaths.map(
			( resourcePath ) => {

				return( normalizeResourcePath( resourcePath ) );

			}
		);

		var deleteConfig = loadClass( "com.amazonaws.services.s3.model.DeleteObjectsRequest" )
			.init( awsBucket )
			.withQuiet( true )
			.withKeys( javaCast( "string[]", normalizedPaths ) )
		;

		var awsResponse = s3Client.deleteObjects( deleteConfig );

		return({
			awsResponse: awsResponse
		});

	}

	/**
	* I return a paginated list of objects located under the given prefix.
	* 
	* @resourcePathPrefix I am the key-prefix as which to search.
	* @continuationToken I am the continuation token for an existing pagination.
	* @maxKeys I am the maximum number of objects to return in a given page.
	*/
	public struct function listObjects(
		required string resourcePathPrefix,
		string continuationToken = "",
		numeric maxKeys = 1000
		) {

		var listConfig = loadClass( "com.amazonaws.services.s3.model.ListObjectsV2Request" )
			.init()
			.withBucketName( awsBucket )
			.withPrefix( normalizeResourcePath( resourcePathPrefix ) )
			.withMaxKeys( maxKeys )
		;

		// If a list of results has been truncated (ie, there are more objects at the
		// given prefix than there are maxKeys), then we can provide a "cursor" at which
		// to get the next set of objects.
		if ( continuationToken.len() ) {

			listConfig.withContinuationToken( continuationToken );

		}

		var awsResponse = s3Client.listObjectsV2( listConfig );

		var objects = awsResponse.getObjectSummaries().map(
			( summary ) => {

				return({
					bucket: summary.getBucketName(),
					key: summary.getKey(),
					size: summary.getSize(),
					// NOTE: The AWS API returns the dates in UTC/GMT timezone. However,
					// the AWS SDK appears to parse them into the server's local
					// timezone. As such, let's convert them back to UTC for the sake of
					// consistency with our date-handling.
					lastModified: dateConvert( "local2utc", summary.getLastModified() )
				});

			}
		);

		return({
			objects: objects,
			maxKeys: awsResponse.getMaxKeys(),
			isTruncated: awsResponse.isTruncated(),
			continuationToken: awsResponse.getNextContinuationToken(),
			awsResponse: awsResponse
		});

	}


	/**
	* I store the given object / binary payload at the given path.
	* 
	* @resourcePath I am the key at which to store the object.
	* @resourceContent I am the object data being stored.
	* @resouceContentType I am the content/mime-type associated with the object.
	*/
	public struct function putObject(
		required string resourcePath,
		required binary resourceContent,
		required string resouceContentType
		) {

		var objectMetadata = loadClass( "com.amazonaws.services.s3.model.ObjectMetadata" )
			.init()
		;
		objectMetadata.setSSEAlgorithm( objectMetadata.AES_256_SERVER_SIDE_ENCRYPTION );
		objectMetadata.setContentLength( arrayLen( resourceContent ) );
		objectMetadata.setContentType( resouceContentType );

		var normalizedPath = normalizeResourcePath( resourcePath );
		var resourceStream = asByteArrayInputStream( resourceContent );
		var awsResponse = s3Client.putObject( awsBucket, normalizedPath, resourceStream, objectMetadata );

		return({
			awsResponse: awsResponse
		});

	}


	// ---
	// PRIVATE METHODS.
	// ---

	/**
	* I create a byte-array input stream from the given binary value.
	* 
	* @value I am the binary payload being wrapped.
	*/
	private any function asByteArrayInputStream( required binary value ) {

		return( createObject( "java", "java.io.ByteArrayInputStream" ).init( value ) );

	}


	/**
	* I create the S3 Client instance that this component is wrapping.
	*/
	private any function createS3Client() {

		// Load some class that we'll use for static references.
		var ProtocolClass = loadClass( "com.amazonaws.Protocol" );
		var RegionClass = loadClass( "com.amazonaws.regions.Region" );
		var RegionsClass = loadClass( "com.amazonaws.regions.Regions" );

		var clientConfig = loadClass( "com.amazonaws.ClientConfiguration" ).init();
		clientConfig.setProtocol( ProtocolClass.HTTPS );
		clientConfig.setMaxErrorRetry( 4 );

		var clientCredentials = loadClass( "com.amazonaws.auth.BasicAWSCredentials" )
			.init( awsAccessID, awsSecretKey )
		;

		var clientOptions = loadClass( "com.amazonaws.services.s3.S3ClientOptions" )
			.init()
			.withPathStyleAccess( true )
		;

		var clientRegion = RegionClass.getRegion( RegionsClass.fromName( awsRegion ) );

		var s3Client = loadClass( "com.amazonaws.services.s3.AmazonS3Client" )
			.init( clientCredentials, clientConfig )
		;
		s3Client.setS3ClientOptions( clientOptions );
		s3Client.setRegion( clientRegion );

		return( s3Client );

	}


	/**
	* I load the Java class with the given name (using the AWS SDK JAR files).
	* 
	* @className I am the class to load.
	*/
	private any function loadClass( required string className ) {

		return( createObject( "java", className, jarPaths ) );

	}


	/**
	* I normalize the given path, stripping off any leading slashes.
	* 
	* @resourcePath I am the path being normalized.
	*/
	private string function normalizeResourcePath( required string resourcePath ) {

		return( resourcePath.reReplace( "^[\\/]+", "", "one" ) );

	}

}