BoxLang 🚀 A New JVM Dynamic Language Learn More...

CBStorages

v3.1.0+1 Modules


Copyright Since 2005 ColdBox Platform by Luis Majano and Ortus Solutions, Corp
www.coldbox.org | www.ortussolutions.com


Welcome to the cbStorages Module

The cbstorages module will provide you with a collection of smart 😉 storage services that will enhance the capabilities of the major ColdFusion (CFML) scopes:

  • Application
  • Cache
  • Cgi
  • Client
  • Cookie
  • Request
  • Session

Enhancement Capabilities

  • Consistent API for dealing with all persistent scopes
  • The CacheStorage allows you to leverage distributed caches like Couchbase, Redis, ehCache, etc for distributed session management. It can act as a distributed session scope.
  • The CookieStorage can do automatic encryption/decryption, httpOnly, security and much more.
  • Ability to retrieve and clear all values stored in a scope
  • Ability to deal with complex and simple values by leveraging JSON serialization
  • Much More

License

Apache License, Version 2.0.

Requirements

  • Lucee 5+
  • ColdFusion 2018+

Installation

Use CommandBox to install

box install cbstorages

WireBox Mappings

The module registers the following storage mappings:

  • applicationStorage@cbstorages - For application based storage
  • CGIStorage@cbstorages - For cgi based storage (read-only)
  • clientStorage@cbstorages - For client based storage
  • cookieStorage@cbstorages - For cookie based storage
  • sessionStorage@cbstorages - For session based storage
  • cacheStorage@cbstorages - For CacheBox based storage simulating session/client
  • requestStorage@cbstorages - For request based storage

You can check out the included API Docs to see all the functions you can use for persistence.

Settings

Some storages require further configuration via your configuration file config/ColdBox.cfc under the moduleSettings in a cbStorages structure:

cbStorages : {
	cacheStorage : {
		// The CacheBox registered cache to store data in
		cachename          : "template",
		// The default timeout of the session bucket, defaults to 60
		timeout            : 60,
		// The identifierProvider is a closure/udf that will return a unique identifier according to your rules
		// If you do not provide one, then we will search in session, cookie and url for the ColdFusion identifier.
		// identifierProvider : function(){}
		identifierProvider : "" // If it's a simple value, we ignore it.
	},

	// Cookie Storage settings
	cookieStorage : {
		// Matches the secure attribute of cfcookie, ssl only
		secure 				: false,
		// If yes, sets cookie as httponly so that it cannot be accessed using JavaScripts
		httpOnly			: true,
		// Applicable global cookie domain
		domain 				: "",
		// Use encryption of values
		useEncryption 		: false,
		// The unique seeding key to use: keep it secret, keep it safe
		encryptionSeed 		: "CBStorages",
		// The algorithm to use: https://cfdocs.org/encrypt
		encryptionAlgorithm : "CFMX_COMPAT",
		// The encryption encoding to use
		encryptionEncoding 	: "Base64"
	}
}

CacheStorage Unique Tracking Identifiers

The CacheStorage leverages a discovery algorithm to determine a user's request in order to store their session information. The discovery order is the following:

  1. identifierProvider closure/lambda/udf
  2. Session identifiers
  3. Cookie identifiers
  4. URL identifiers
  5. Create a unique request identifier

You can use the identifierProvider in order to give the storage the unique identifier you want to use. This is useful if you do your own tracking your way. If not, we will use the ColdFusion approaches of jsessionID or cfid/cftoken.

identifierProvider = function(){
	return cookie.myTrackingCookie;
}

Storage Methods

All storages must adhere to our interface, but each of them can extend as they see please. Here is the basic interface for all storages:

/**
 * Copyright Ortus Solutions, Corp
 * www.ortussolutions.com
 * ---
 * This is the main storage interface all cbStorages should implement
 */
interface {

	/**
	 * Set a new variable in storage
	 *
	 * @name The name of the data key
	 * @value The value of the data to store
	 *
	 * @return cbstorages.models.IStorage
	 */
	any function set( required name, required value );

	/**
	 * Do a multi-set using a target structure of name-value pairs
	 *
	 * @map A struct of name value pairs to store
	 *
	 * @return cbstorages.models.IStorage
	 */
	any function setMulti( required struct map );

	/**
	 * Get a new variable in storage if it exists, else return default value, else will return null.
	 *
	 * @name The name of the data key
	 * @defaultValue The default value to return if not found in storage
	 */
	any function get( required name, defaultValue );

	/**
	 * Triest to get a value from the storage, if it does not exist, then it will
	 * call the `produce` closure/lambda to produce the required value and store it
	 * in the storage using the passed named key.
	 *
	 * @name The name of the key to get
	 * @produce The closure/lambda to execute that should produce the value
	 */
	any function getOrSet( required name, required any produce );

	/**
	 * Get multiple values from the storage using the keys argument which can be a list or an array
	 *
	 * @keys A list or array of keys to get from the storage
	 */
	struct function getMulti( required keys );

	/**
	 * Delete a variable in the storage
	 *
	 * @name The name of the data key
	 */
	boolean function delete( required name );

	/**
	 * Delete multiple keys from the storage
	 *
	 * @keys A list or array of keys to delete from the storage
	 *
	 * @return A struct of the keys and a boolean value if they where removed or not
	 */
	struct function deleteMulti( required keys );

	/**
	 * Verifies if the named storage key exists
	 *
	 * @name The name of the data key
	 */
	boolean function exists( required name );

	/**
	 * Clear the entire storage
	 *
	 * @return cbstorages.models.IStorage
	 */
	any function clearAll();

	/**
	 * Get the size of the storage
	 */
	numeric function getSize();

	/**
	 * Get the list of keys stored in the storage
	 */
	array function getKeys();

	/**
	 * Verifies if the storage is empty or not
	 */
	boolean function isEmpty();

	/****************************************** STORAGE METHODS ******************************************/

	/**
	 * Get the entire storage scope structure, basically means return all the keys
	 */
	struct function getStorage();

	/**
	 * Remove the storage completely, different from clear, this detaches the entire storage
	 *
	 * @return cbstorages.models.IStorage
	 */
	any function removeStorage();

	/**
	 * Check if storage exists
	 */
	boolean function storageExists();

	/**
	 * Create the storage
	 *
	 *
	 * @return cbstorages.models.IStorage
	 */
	any function createStorage();

}

Copyright Since 2005 ColdBox Framework by Luis Majano and Ortus Solutions, Corp www.ortussolutions.com


HONOR GOES TO GOD ABOVE ALL

Because of His grace, this project exists. If you don't like this, then don't read it, its not for you.

"Therefore being justified by faith, we have peace with God through our Lord Jesus Christ: By whom also we have access by faith into this grace wherein we stand, and rejoice in hope of the glory of God. And not only so, but we glory in tribulations also: knowing that tribulation worketh patience; And patience, experience; and experience, hope: And hope maketh not ashamed; because the love of God is shed abroad in our hearts by the Holy Ghost which is given unto us. ." Romans 5:5

THE DAILY BREAD

"I am the way, and the truth, and the life; no one comes to the Father, but by me (JESUS)" Jn 14:1-12

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.


Unreleased

3.1.0 - 2024-03-11

Added

  • Github actions updates
  • Github support files
  • Contribution guidelines
  • Adobe 2023 builds
  • Lucee 6 builds

Fixed

  • Consolidated lockNames so there are no missing ones used by the abstract cache.

[3.0.1] => 2023-MAR-27

Fixed

  • Cookie is being set twice. Appears twice in response headers, one of them does not have the attributes (only the value)

[3.0.0] => 2022-OCT-4

Added

  • New ortus module support

Changed

  • Removed ACF 2016 support

[2.6.1] => 2021-JUL-23

Fixed

  • Added params to the cache storage settings to avoid missing setting exceptions

[2.6.0] => 2021-JUL-22

Added

  • New setting for cacheStorage : identifierProvider which can be a closure/lambda/udf that returns a unique tracking identifier for user requests.
  • Improved session detection and fallback to request tracking if no session/cookie/url tracking is discovered thanks to @elpete : https://github.com/coldbox-modules/cbstorages/pull/15/files
  • Migration to github actions for CI process
  • Adobe 2021 automated support

[2.5.0] => 2021-APR-01

  • Added sameSite argument to setting cookies

[2.4.0] => 2020-NOV-30

Added

  • Set expires is not defaulted to 0 which eliminates the cookie. It is now expiring as it should using the browser session as the key indicator.

[2.3.0] => 2020-NOV-13

Added

  • Changelog publishing
  • Refactored lock timeouts to be part of the AbstractStorage thanks to @wpdebruin

Fixed

  • Invalid argument when using getOrSet thanks to @wpdebruin
  • Apply cookies in reverse order so the one with all the attributes is last and is persisted by Eric Peterson [email protected]

[2.2.0] => 2020-JUL-09

Added

  • New module layouts and helpers
  • Github auto release notes publishing
  • More formatting goodness
  • New Changelogs
  • [BOX-77] Add CGI scope wrapper to cbStorages

[2.1.0] => 2020-FEB-03

  • improvement : Remove numeric typing on expiry for CookieStorage: The numeric typing on the expires argument will still allow a date object to pass through ( strangely ), but prevents the pass through of the textual arguments allowed by CFCookie: https://helpx.adobe.com/coldfusion/cfml-reference/coldfusion-tags/tags-c/cfcookie.html
  • improvement : Added formatting and linting scripts
  • bug : Fixed toMaster script so it could pull master incase of divergence

[2.0.1]

  • bug : CCM-54 - Left over bug on session storage looking at app storage

[2.0.0]

  • feature : All storages now implement a common interface : IStorage
  • feature : New interface brings new storageWide methods: setMulti(), getOrSet(), getMulti(), deleteMulti(), getSize(), getkeys(), isEmpty()
  • feature,compat : ColdBox 4/5 approach to settings instead of in the root, in the moduleSettings
  • improvement,compat : All tag based default values where named default but renamed to defaultValue to have consistency.
  • improvement : Dropped Lucee4.5 and ACF11 support
  • improvement : Script migrations
  • feature : Added support for httpOnly and secure cookies in the cookie storage.
  • improvement : Added option to specify path when deleting a cookie. Without this option, the cookie is never deleted when specifying a path when creating a cookie. https://github.com/coldbox-modules/cbstorages/pull/7 (@donbellamy)
  • improvement : TestBox 3 upgrade
  • improvement : Mark all storages as serializable=false to avoid serialization issues
  • compat : Removed ClusterStorage as this was a lucee only feature that actually never released.
  • compat : The following methods have been renamed: setVar() => set(), getVar() => get(), and deleteVar() => delete()

[1.5.0]

[1.4.0]

  • Updated to leverage workbench module template
  • Remove useless entry points thanks to @tropicalista
  • Make default cache for CacheStorage to be the template cache instead of default

[1.3.0]

  • Updated API docs with a syntax typo
  • New RequestStorage thanks to Dan Murphy
  • Updated travis process for self-publishing

[1.2.0]

  • Update build process
  • Updated dependencies
  • Added new storage: CacheStorage to allow you to simulate session/client on a distributed cache via CacheBox.

[1.1.0]

  • Travis integration
  • DocBox updates
  • Build process updates

[1.0.0]

  • Create first module version

$ box install cbstorages

No collaborators yet.
     
  • {{ getFullDate("2014-04-30T20:22:49Z") }}
  • {{ getFullDate("2024-03-11T09:51:45Z") }}
  • 16,098
  • 578,486