Writing a Custom CDN Type
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
Argument | Description |
---|---|
cdn REQ | The 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
Argument | Description |
---|---|
config REQ | The 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
Argument | Description |
---|---|
config REQ | The config struct for the location being queried. |
file REQ | The file being queried. |
Should return true or false.
ioGetFileSize
Argument | Description |
---|---|
config REQ | The config struct for the location being queried. |
file REQ | The file being queried. |
Should return an integer value representing the size of the file in bytes.
ioGetFileLocation
Argument | Description |
---|---|
config REQ | The config struct for the location being queried. |
file REQ | The file being queried. |
admin REQ | Indicates 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
Argument | Description |
---|---|
config REQ | The config struct for the location being queried. |
file REQ | The file being written. |
data REQ | The data being written. |
datatype REQ | The type of data being written. One of text, binary, and image. |
quality REQ | The 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
Argument | Description |
---|---|
config REQ | The config struct for the location being queried. |
file REQ | The file being read. |
datatype REQ | The type of data being read. One of text, binary, and image. |
Should read from the specified file.
ioMoveFile
Argument | Description |
---|---|
source_config OPT | The config for the source. |
source_file OPT | The source file. |
source_localpath OPT | The sources full local path. |
dest_config OPT | The config for the destination. |
dest_file OPT | The destination file. |
dest_localpath OPT | The 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
Argument | Description |
---|---|
source_config OPT | The config for the source. |
source_file OPT | The source file. |
source_localpath OPT | The sources full local path. |
dest_config OPT | The config for the destination. |
dest_file OPT | The destination file. |
dest_localpath OPT | The 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
Argument | Description |
---|---|
config REQ | The config struct for the location being queried. |
file REQ | The file being deleted. |
Should remove the specified file from the CDN.
ioDirectoryExists
Argument | Description |
---|---|
config REQ | The config struct for the location being queried. |
dir REQ | The directory being queried. |
Should return true or false. Some CDNs that only have directories by implication, like S3, may always return true.
ioCreateDirectory
Argument | Description |
---|---|
config REQ | The config struct for the location being queried. |
dir REQ | The directory being created. |
Should create the specified directory. Some CDNs that only have directories by implication, like S3, may do nothing.
ioGetDirectoryListing
Argument | Description |
---|---|
config REQ | The config struct for the location being queried. |
dir REQ | The 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