Separation Of Concerns When Consuming Amazon SQS Queues In Lucee CFML 5.3.8.201

Application.cfc

component
	output = false
	hint = "I define the application settings and event handlers."
	{

	// Configure the application settings.
	this.name = "ColorSwatchesQueueDemo";
	this.applicationTimeout = createTimeSpan( 0, 1, 0, 0 );
	this.sessionManagement = false;
	this.setClientCookies = false;

	this.mappings = {
		"/swatches": "./swatches",
		"/vendor": "../../vendor"
	};

	// ---
	// LIFE-CYCLE METHODS.
	// ---

	/**
	* I get called once when the application is being initialized.
	*/
	public void function onApplicationStart() {

		var config = deserializeJson( fileRead( "./config.json" ) );

		// This service generates color swatches and KNOWS NOTHING about Amazon SQS.
		application.colorSwatchService = new ColorSwatchService();

		// This service interacts specifically with the "color-swatch-queue" but KNOWS
		// NOTHING about color watches, how they are used within this application, or how
		// the queue will be monitored on an ongoing basis.
		application.sqsClient = new SqsClient(
			classLoader = new AwsClassLoader(),
			accessID = config.aws.accessID,
			secretKey = config.aws.secretKey,
			region = config.aws.region,
			queueName = config.aws.queue, // This component instance if QUEUE SPECIFIC.
			defaultWaitTime = 20,
			defaultVisibilityTimeout = 60
		);

		// This service is the TRANSLATION GLUE between the Amazon SQS client and the
		// application's business logic. However, it KNOWS NOTHING about how the queue
		// will be monitored on an ongoing basis.
		application.colorSwatchQueueService = new ColorSwatchQueueService(
			sqsClient = application.sqsClient,
			colorSwatchService = application.colorSwatchService
		);

		// For this demo, this scheduled task will be the only thing in the application
		// that manages the monitoring of the queue over the long-term. However, it
		// doesn't actually know anything about the queue, the color swatches, or how
		// they are used within the application - the scheduled task ONLY KNOWS about the
		// ColorSwatchQueueService component (and its ".processNewMessages()" method).
		schedule
			action = "update"
			task = "ColorSwatchQueueManager"
			operation = "HTTPRequest"
			url = "http://#cgi.server_name#:#cgi.server_port#/demos/color-swatches/color-swatch-queue-manager.cfm"
			startDate = "2021-09-10"
			startTime = "00:00 AM"
			interval = 10 // Every 10 seconds (smallest increment allowed in Lucee CFML).
		;

	}


	/**
	* I get called once when the request is being initialized.
	*/
	public void function onRequestStart() {

		// If the INIT flag is defined, restart the application in order to refresh the
		// in-memory cache of components.
		if ( url.keyExists( "init" ) ) {

			applicationStop();
			location( url = cgi.script_name, addToken = false );

		}

	}

}

color-swatch-queue-manager.cfm

<cfscript>

	// This template is being invoked as a ColdFusion Scheduled Task that fires every
	// 10-seconds (the smallest scheduled task increment in Lucee CFML). This means that
	// any given request will almost always be overlapping with the previous, still-
	// executing request. As such, let's use a no-error lock to synchronize our
	// monitoring of the color swatch queue.
	lock
		name = "color-swatch-queue-manager"
		type = "exclusive"
		timeout = 1
		throwOnTimeout = false
		{

		systemOutput( "Start polling color-swatch-queue for new messages.", true );

		// When we ask the queue service to process new messages, it only processes one
		// batch of new messages at a time. This way, we can separate the concern of
		// processing new messages from the concern of polling the queue over a long
		// period of time. Due to the constraints of the web server, requests timeout if
		// they run for too long. As such, we have to explicitly increase the timeout of
		// this page so that it doesn't get terminated forcefully by the server.
		// --
		// NOTE: For the demo, I'm using a relatively low-number so that as I edit this
		// template and I don't have to restart the server to kill this thread. But, in a
		// production setting, I would use a rather large number.
		maxRuntimeInSeconds = 100;
		maxTickCount = ( getTickCount() + ( maxRuntimeInSeconds * 1000 ) );

		// Increase the execution timeout for this web-server request.
		setting
			requestTimeout = maxRuntimeInSeconds
		;

		// Since each call to the queue service will only process a single batch of new
		// messages, we have to continually loop in order to keep polling the queue.
		while ( getTickCount() <= maxTickCount ) {

			systemOutput( "LOOP: Checking color-swatch-queue for new messages.", true );

			application.colorSwatchQueueService.processNewMessages();

		}

		systemOutput( "LOOP: Exiting long-polling while-loop.", true );

	}

	// If a previous instance of the scheduled task was still polling the message queue,
	// the lock will have failed to be obtained.
	if ( ! cflock.succeeded ) {

		systemOutput( "Lock failure, color-swatch-queue monitoring already in place.", true, true );

	}

</cfscript>

ColorSwatchQueueService.cfc

component
	output = false
	hint = "I provide methods for interacting with the color-swatch-queue - I GLUE the concept of the queue to larger application context."
	{

	/**
	* I initialize the color swatch queue service with the given SQS client. Note that
	* the SQS client is assumed to be created specifically for the color-swatch-queue
	* in Amazon SQS.
	*/
	public void function init(
		required any sqsClient,
		required any colorSwatchService
		) {

		variables.sqsClient = arguments.sqsClient;
		variables.colorSwatchService = arguments.colorSwatchService;

	}

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

	/**
	* I create and persist a new message for processing the given HEX color.
	*/
	public void function addMessage( required string hexColor ) {

		sqsClient.sendMessage(
			serializeJson({
				hexColor: hexColor
			})
		);

	}


	/**
	* I delete the given message from the queue.
	*/
	public void function deleteMessage( required struct message ) {

		sqsClient.deleteMessage( message.receiptHandle );

	}


	/**
	* I process the given message, translating the message into an interaction with the
	* rest of the application logic. In this case, we're generating a color swatch image
	* for the hexColor contained within the SQS message.
	*/
	public void function processMessage( required struct message ) {

		var body = deserializeJson( message.body );
		var hexColor = body.hexColor;
		var filename = getFilenameForHex( hexColor );
		var destination = expandPath( "/swatches/#filename#" );

		systemOutput( "Generating color swatch for ###hexColor.ucase()#", true );

		colorSwatchService.generateSwatchFile( hexColor, destination );

	}


	/**
	* I look for new messages on the queue.
	* 
	* CAUTION: While this request will block-and-wait for new messages to arrive (if
	* waitTime argument is non-zero), it will do so only once. We are not putting the
	* onus of continual polling inside this component. Instead, we are placing that
	* responsibility in another area of the app (in this demo, a scheduled task).
	*/
	public void function processNewMessages(
		numeric maxNumberOfMessages = 3,
		numeric waitTime = 20,
		numeric visibilityTimeout = 10
		) {

		var messages = sqsClient.receiveMessages( argumentCollection = arguments );

		for ( var message in messages ) {

			// Since we are gathering more than one message at a time in this demo (in
			// order to reduce the dollars-and-cents cost of making API calls to Amazon
			// SQS), we want to wrap each message processing in a try-catch so that one
			// "poison pill" doesn't prevent the other messages from being processed.
			try {

				processMessage( message );

			} catch ( any error ) {

				systemOutput( "A color-swatch-queue message failed to process.", true, true );
				systemOutput( message, true, true );
				systemOutput( error, true, true );

			}

			deleteMessage( message );

		}

	}

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

	/**
	* I generate a natural-sort-friendly filename for the given hexColor.
	*/
	private string function getFilenameForHex( required string hexColor ) {

		// For this demo, we know that the files are going to be read directly off of the
		// local file-system. As such, if we prefix each color swatch with a date/time
		// stamp, we know that we can list the newest swatches first using an alpha-
		// numeric sort on the file names.
		return( now().dateTimeFormat( "yyyy-mm-dd HH-nn-ss" ) & "-" & hexColor.right( 6 ) & ".png" );

	}

}

ColorSwatchService.cfc

component
	output = false
	hint = "I generate color swatch images from 6-digit hexadecimal color values."
	{

	/**
	* I initialize the color swatch service.
	*/
	public void function init() {

		variables.swatchWidth = 200;
		variables.swatchHeight = 150;

	}

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

	/**
	* I generate and return a color swatch image for the given hexadecimal value.
	*/
	public struct function generateSwatch( required string hexColor ) {

		var normalizedHex = ( "##" & hexColor.right( 6 ).ucase() );
		var annotationFont = {
			font: "monospace",
			size: 16
		};
		var labelWidth = 92;
		var labelHeight = 36;

		var swatch = imageNew( "", swatchWidth, swatchHeight, "rgb", normalizedHex )
			.setAntialiasing( true )
			.setDrawingColor( "ffffff" )
			.drawRect( 0, ( swatchHeight - labelHeight ), labelWidth, labelHeight, true )
			.setDrawingColor( "000000" )
			.drawText( normalizedHex, 10, ( swatchHeight - 11 ), annotationFont )
		;

		return( swatch );

	}


	/**
	* I generate a color swatch image for the given hexadecimal value and save it to the
	* given filename.
	*/
	public void function generateSwatchFile(
		required string hexColor,
		required string destination
		) {

		var quality = 1;
		var overwrite = true;
		var noMetaData = true;

		// NOTE: Instead of passing-in variables to the .write() method, I would normally
		// just used named-arguments. However, it seems that attempting to call the
		// .write() method with named arguments throws an error. Perhaps the documented
		// argument names are wrong.
		generateSwatch( hexColor )
			.write( destination, quality, overwrite, noMetaData )
		;

	}

}

index.cfm

<cfscript>

	param name="form.hexColor" type="string" default="";

	// If we have a new hex color to process, put it on the message queue - a background
	// thread will monitor the queue for new messages and generate the color swatch image
	// asynchronously.
	if ( form.hexColor.len() ) {

		application.colorSwatchQueueService.addMessage( form.hexColor );

	}

	// Query for the existing color swatches. Since we don't have a database, we'll just
	// read the images right off of the file-system.
	swatches = directoryList(
		path = expandPath( "/swatches" ),
		listInfo = "name",
		type = "file",
		filter = "*.png"
	);
	swatches.sort( "textnocase", "desc" );

</cfscript>
<cfoutput>

	<!doctype html>
	<html lang="en">
	<head>
		<meta charset="utf-8" />
		<title>
			Separation Of Concerns When Consuming Amazon SQS Queues In Lucee CFML 5.3.8.201
		</title>
		<link rel="stylesheet" type="text/css" href="./index.css" />
		<!---
			If we just submitted a hexColor, let's automatically refresh the page in a
			few seconds. For this particular demo, a few seconds is all it takes for the
			ColdFusion application to poll the queue, get the new messages, and generate
			the associated color swatch image. Refreshing the page will, therefore, read
			the new image off the file-system.
		--->
		<cfif form.hexColor.len()>
			<meta http-equiv="refresh" content="2" />
		</cfif>
	</head>
	<body>

		<h1>
			Separation Of Concerns When Consuming Amazon SQS Queues In Lucee CFML 5.3.8.201
		</h1>

		<form method="post" action="./index.cfm">
			<input
				type="text"
				name="hexColor"
				placeholder="Enter hex color..."
				size="20"
				maxlength="6"
				autofocus
			/>
			<button type="submit">
				Generate swatch
			</button>
		</form>

		<hr />

		<h2>
			Existing Swatches
		</h2>

		<ul>
			<cfloop value="filename" array="#swatches#">
				<li>
					<img src="./swatches/#filename#" />
				</li>
			</cfloop>
		</ul>

	</body>
	</html>

</cfoutput>

logs.txt

[INFO ] Start polling color-swatch-queue for new messages.
[INFO ] LOOP: Checking color-swatch-queue for new messages.
[ERROR] Lock failure, color-swatch-queue monitoring already in place.
[INFO ] Generating color swatch for #FF3366
[INFO ] LOOP: Checking color-swatch-queue for new messages.
[ERROR] Lock failure, color-swatch-queue monitoring already in place.
[INFO ] Generating color swatch for #00AACC
[INFO ] LOOP: Checking color-swatch-queue for new messages.
[INFO ] Generating color swatch for #3399CC
[INFO ] LOOP: Checking color-swatch-queue for new messages.
[ERROR] Lock failure, color-swatch-queue monitoring already in place.
[INFO ] Generating color swatch for #00FFCC
[INFO ] LOOP: Checking color-swatch-queue for new messages.
[INFO ] Generating color swatch for #FF0088
[INFO ] LOOP: Checking color-swatch-queue for new messages.
[ERROR] Lock failure, color-swatch-queue monitoring already in place.
[INFO ] Generating color swatch for #9F0CAA
[INFO ] LOOP: Checking color-swatch-queue for new messages.
[ERROR] Lock failure, color-swatch-queue monitoring already in place.
[ERROR] Lock failure, color-swatch-queue monitoring already in place.