Writing a Custom CDN Type

Add a CDN type to your project by adding a component to your project under /projects/yourproject/packages/cdn/.

The name of the component will the the name of the CDN type. FarCry takes care of details like checking file uniqueness, interfacing with outher CDN types, and handling uploads - you just need to provide the basic file operations. Note that in this document REQ denotes arguments that will always be provided, and OPT denotes arguments that will sometimes be provided.

init

ArgumentDescription
cdn REQThe singleton CDN api component. This may be useful if you want to create a CDN which fronts other CDNs, but in most cases you can ignore it.
engine REQ"coldfusion" or "railo". You can use this if your CDN will need to do things differently in each engine.

This function will be called once on application initialisation.

validateConfig

ArgumentDescription
config REQThe config as specified with setLocation. As well as CDN specific properties, it will also contain name (location name) and cdn (CDN type).

Use this function to check that a particular config is valid. There are two main things to remember when writing this function:

  • don't be afraid to throw an error if a setting is invalid - better that the developer know there's a problem with their setup right away

    <cfset application.fapi.throw(message="no '{1}' value defined",type="cdnconfigerror",detail=serializeJSON(arguments.config),substituteValues=[ 'bucket' ]) />
  • the struct returned from this function replaces the struct provided by the developer - use this opportunity to clean up and normalize the settings

    <cfset arguments.config.fullpath = replace(arguments.config.fullpath,"\","/","ALL") />
    
    <cfif right(arguments.config.fullpath,1) eq "/">
        <cfset arguments.config.fullpath = left(arguments.config.fullpath,len(arguments.config.fullpath)-1) />
    </cfif>

ioFileExists

ArgumentDescription
config REQThe config struct for the location being queried.
file REQThe file being queried.

Should return true or false.

ioGetFileSize

ArgumentDescription
config REQThe config struct for the location being queried.
file REQThe file being queried.

Should return an integer value representing the size of the file in bytes.

ioGetFileLocation

ArgumentDescription
config REQThe config struct for the location being queried.
file REQThe file being queried.
admin REQIndicates that the path is for use in the webtop. This is useful when it's appropriate to use a different path in the webtop, such as when the CDN has a cache in front.

Should return a struct in one of the following formats:

Redirect:

{
    method : "redirect",
    path : "[file url]"
}

Stream:

This struct should only be returned for files accessible via the local file system.

{
    method : "stream",
    path : "[full local file path]"
}

ioWriteFile

ArgumentDescription
config REQThe config struct for the location being queried.
file REQThe file being written.
data REQThe data being written.
datatype REQThe type of data being written. One of text, binary, and image.
quality REQThe image quality (only necessary for writing JPEG images). A number between 0 and 1.

Should write to the specified file, creating it if it doesn't exist, overwriting it if it does.

ioReadFile

ArgumentDescription
config REQThe config struct for the location being queried.
file REQThe file being read.
datatype REQThe type of data being read. One of text, binary, and image.

Should read from the specified file.

ioMoveFile

ArgumentDescription
source_config OPT The config for the source.
source_file OPTThe source file.
source_localpath OPTThe sources full local path.
dest_config OPT The config for the destination.
dest_file OPTThe destination file.
dest_localpath OPTThe destinations full local path.

This function will always be provided:

  • source_config and source_file OR source_localpath
  • dest_config and dest_file OR dest_localpath

In practice this means that the function needs to handle each of the following cases:

  • move a file from the local file system to the CDN
  • move a file from the CDN to the local file system
  • move a file to a different place on the same type of CDN

ioCopyFile

ArgumentDescription
source_config OPT The config for the source.
source_file OPTThe source file.
source_localpath OPTThe sources full local path.
dest_config OPT The config for the destination.
dest_file OPTThe destination file.
dest_localpath OPTThe destinations full local path.

This function will always be provided:

  • source_config and source_file OR source_localpath
  • dest_config and dest_file OR dest_localpath

In practice this means that the function needs to handle each of the following cases:

  • copy a file from the local file system to the CDN
  • copy a file from the CDN to the local file system
  • copy a file to a different place on the same type of CDN

ioDeleteFile

ArgumentDescription
config REQThe config struct for the location being queried.
file REQThe file being deleted.

Should remove the specified file from the CDN.

ioDirectoryExists

ArgumentDescription
config REQThe config struct for the location being queried.
dir REQThe directory being queried.

Should return true or false. Some CDNs that only have directories by implication, like S3, may always return true.

ioCreateDirectory

ArgumentDescription
config REQThe config struct for the location being queried.
dir REQThe directory being created.

Should create the specified directory. Some CDNs that only have directories by implication, like S3, may do nothing.

ioGetDirectoryListing

ArgumentDescription
config REQThe config struct for the location being queried.
dir REQThe sub directory being queried. May be an empty string.

Should return a query containing a "file" field. This result must:

  • contain every file under the specified directory (recursively)
  • only contain filenames that are valid when passed into any other CDN function
  • not contain any directories