feat(HyperRequest): Allowing attaching file uploads to HyperRequests

Author: elpete

.github/workflows/pr.yml

@@ -17,7 +17,7 @@ jobs:
     runs-on: ubuntu-latest
     name: Tests
     strategy:
-      fail-fast: true
+      fail-fast: false
       matrix:
         cfengine: ["lucee@5", "adobe@2016", "adobe@2018"]
         coldbox: ["coldbox@6"]
@@ -28,16 +28,16 @@ jobs:
       - name: Setup Java JDK
         uses: actions/setup-java@v1.4.3
         with:
-          java-version: 11 
+          java-version: 11
 
       - name: Set Up CommandBox
         uses: elpete/setup-commandbox@v1.0.0
-      
+
       - name: Install dependencies
         run: |
           box install
           box install ${{ matrix.coldbox }} --noSave
-      
+
       - name: Start server
         run: box server start cfengine=${{ matrix.cfengine }} --noSaveSettings
 
@@ -54,14 +54,14 @@ jobs:
       - name: Setup Java JDK
         uses: actions/setup-java@v1.4.3
         with:
-          java-version: 11 
+          java-version: 11
 
       - name: Set Up CommandBox
         uses: elpete/setup-commandbox@v1.0.0
-      
+
       - name: Install CFFormat
         run: box install commandbox-cfformat
-      
+
       - name: Run CFFormat
         run: box run-script format
 

.github/workflows/prerelease.yml

@@ -11,7 +11,7 @@ jobs:
     if: "!contains(github.event.head_commit.message, '__SEMANTIC RELEASE VERSION UPDATE__')"
     runs-on: ubuntu-latest
     strategy:
-      fail-fast: true
+      fail-fast: false
       matrix:
         cfengine: ["lucee@5", "adobe@2016", "adobe@2018"]
         coldbox: ["coldbox@6"]
@@ -22,16 +22,16 @@ jobs:
       - name: Setup Java JDK
         uses: actions/setup-java@v1.4.3
         with:
-          java-version: 11 
+          java-version: 11
 
       - name: Set Up CommandBox
         uses: elpete/setup-commandbox@v1.0.0
-      
+
       - name: Install dependencies
         run: |
           box install
           box install ${{ matrix.coldbox }} --noSave
-      
+
       - name: Start server
         run: box server start cfengine=${{ matrix.cfengine }} --noSaveSettings
 
@@ -54,17 +54,17 @@ jobs:
   #     - name: Setup Java JDK
   #       uses: actions/setup-java@v1.4.3
   #       with:
-  #         java-version: 11 
+  #         java-version: 11
 
   #     - name: Set Up CommandBox
   #       uses: elpete/setup-commandbox@v1.0.0
-      
+
   #     - name: Install and Configure Semantic Release
   #       run: |
   #         box install commandbox-semantic-release
   #         box config set endpoints.forgebox.APIToken=${{ secrets.FORGEBOX_TOKEN }}
   #         box config set modules.commandbox-semantic-release.plugins='{ "VerifyConditions": "GitHubActionsConditionsVerifier@commandbox-semantic-release", "FetchLastRelease": "ForgeBoxReleaseFetcher@commandbox-semantic-release", "RetrieveCommits": "JGitCommitsRetriever@commandbox-semantic-release", "ParseCommit": "ConventionalChangelogParser@commandbox-semantic-release", "FilterCommits": "DefaultCommitFilterer@commandbox-semantic-release", "AnalyzeCommits": "DefaultCommitAnalyzer@commandbox-semantic-release", "VerifyRelease": "NullReleaseVerifier@commandbox-semantic-release", "GenerateNotes": "GitHubMarkdownNotesGenerator@commandbox-semantic-release", "UpdateChangelog": "FileAppendChangelogUpdater@commandbox-semantic-release", "CommitArtifacts": "NullArtifactsCommitter@commandbox-semantic-release", "PublishRelease": "ForgeBoxReleasePublisher@commandbox-semantic-release", "PublicizeRelease": "GitHubReleasePublicizer@commandbox-semantic-release" }'
-      
+
       # - name: Run Semantic Release
       #   env:
       #     GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/release.yml

@@ -12,7 +12,7 @@ jobs:
     if: "!contains(github.event.head_commit.message, '__SEMANTIC RELEASE VERSION UPDATE__')"
     runs-on: ubuntu-latest
     strategy:
-      fail-fast: true
+      fail-fast: false
       matrix:
         cfengine: ["lucee@5", "adobe@2016", "adobe@2018"]
         coldbox: ["coldbox@6"]
@@ -23,16 +23,16 @@ jobs:
       - name: Setup Java JDK
         uses: actions/setup-java@v1.4.3
         with:
-          java-version: 11 
+          java-version: 11
 
       - name: Set Up CommandBox
         uses: elpete/setup-commandbox@v1.0.0
-      
+
       - name: Install dependencies
         run: |
           box install
           box install ${{ matrix.coldbox }} --noSave
-      
+
       - name: Start server
         run: box server start cfengine=${{ matrix.cfengine }} --noSaveSettings
 
@@ -55,18 +55,18 @@ jobs:
       - name: Setup Java JDK
         uses: actions/setup-java@v1.4.3
         with:
-          java-version: 11 
+          java-version: 11
 
       - name: Set Up CommandBox
         uses: elpete/setup-commandbox@v1.0.0
-      
+
       - name: Install and Configure Semantic Release
         run: |
           box install commandbox-semantic-release
           box config set endpoints.forgebox.APIToken=${{ secrets.FORGEBOX_TOKEN }}
           box config set modules.commandbox-semantic-release.targetBranch=main
           box config set modules.commandbox-semantic-release.plugins='{ "VerifyConditions": "GitHubActionsConditionsVerifier@commandbox-semantic-release", "FetchLastRelease": "ForgeBoxReleaseFetcher@commandbox-semantic-release", "RetrieveCommits": "JGitCommitsRetriever@commandbox-semantic-release", "ParseCommit": "ConventionalChangelogParser@commandbox-semantic-release", "FilterCommits": "DefaultCommitFilterer@commandbox-semantic-release", "AnalyzeCommits": "DefaultCommitAnalyzer@commandbox-semantic-release", "VerifyRelease": "NullReleaseVerifier@commandbox-semantic-release", "GenerateNotes": "GitHubMarkdownNotesGenerator@commandbox-semantic-release", "UpdateChangelog": "FileAppendChangelogUpdater@commandbox-semantic-release", "CommitArtifacts": "NullArtifactsCommitter@commandbox-semantic-release", "PublishRelease": "ForgeBoxReleasePublisher@commandbox-semantic-release", "PublicizeRelease": "GitHubReleasePublicizer@commandbox-semantic-release" }'
-      
+
       - name: Run Semantic Release
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

README.md

@@ -496,6 +496,18 @@ Check if the request has a query parameter with the given name.
 | ---- | ------ | -------- | ------- | ----------------------------------------- |
 | name | string | true     |         | The name of the query parameter to check. |
 
+##### `attach`
+
+Attaches a file to the Hyper request.
+Also sets the Content-Type as `multipart/form-data`.
+Multiple files can be attached by calling `attach` multiple times before calling a send method.
+
+| Name     | Type   | Required | Default | Description                                       |
+| -------- | ------ | -------- | ------- | ------------------------------------------------- |
+| name     | string | true     |         | The name of the file being uploaded.              |
+| path     | string | true     |         | The absolute path to the file to be uploaded.     |
+| mimeType | string | false    |         | An optional mime type to associate with the file. |
+
 ##### `setThrowOnError`
 
 Sets the throw on error property for the request. If true, error codes and status

models/CfhttpHttpClient.cfc

@@ -78,6 +78,12 @@ component implements="HyperHttpClientInterface" {
 		cfhttp( attributeCollection = attrCollection ) {
 			var headers = req.getHeaders();
 			for ( var name in headers ) {
+				// we want to skip adding a Content-Type header when there are files
+				// so that the CFML engines can add the correct boundary to the Content-Type
+				if ( name == "Content-Type" && !req.getFiles().isEmpty() ) {
+					continue;
+				}
+
 				cfhttpparam(
 					type  = "header",
 					name  = name,
@@ -94,6 +100,18 @@ component implements="HyperHttpClientInterface" {
 				);
 			}
 
+			for ( var file in req.getFiles() ) {
+				var fileAttrCollection = {
+					type : "file",
+					name : file.name,
+					file : file.path
+				};
+				if ( file.keyExists( "mimeType" ) && !isNull( file.mimeType ) ) {
+					fileAttrCollection[ "mimeType" ] = file.mimeType;
+				}
+				cfhttpparam( attributeCollection = fileAttrCollection );
+			}
+
 			if ( req.hasBody() ) {
 				if ( req.getBodyFormat() == "json" ) {
 					cfhttpparam( type = "body", value = req.prepareBody() );

models/HyperRequest.cfc

@@ -97,6 +97,11 @@ component accessors="true" {
 	 */
 	property name="queryParams";
 
+	/**
+	 * An array of files to upload for the request.
+	 */
+	property name="files" type="array";
+
 	/**
 	 * Flag to throw on a cfhttp error.
 	 */
@@ -150,6 +155,7 @@ component accessors="true" {
 		variables.queryParams = createObject( "java", "java.util.LinkedHashMap" ).init();
 		variables.headers     = createObject( "java", "java.util.LinkedHashMap" ).init();
 		variables.headers.put( "Content-Type", "application/json" );
+		variables.files              = [];
 		variables.requestCallbacks   = [];
 		variables.responseCallbacks  = [];
 		// This is overwritten by the HyperBuilder if WireBox exists.
@@ -521,6 +527,35 @@ component accessors="true" {
 		return this;
 	}
 
+	/**
+	 * Attaches a file to the Hyper request.
+	 * Also sets the Content-Type as `multipart/form-data`.
+	 * Multiple files can be attached by calling `attach` multiple times before calling a send method.
+	 *
+	 * @name      The name of the file being uploaded.
+	 * @path      The absolute path to the file to be uploaded.
+	 * @mimeType  An optional mime type to associate with the file.
+	 *
+	 * @returns   The HyperRequest instance.
+	 */
+	function attach(
+		required string name,
+		required string path,
+		string mimeType
+	) {
+		setBodyFormat( "formFields" );
+		setContentType( "multipart/form-data" );
+		var fileInfo = {
+			name : arguments.name,
+			path : arguments.path
+		};
+		if ( !isNull( arguments.mimeType ) ) {
+			fileInfo[ "mimeType" ] = arguments.mimeType;
+		}
+		variables.files.append( fileInfo );
+		return this;
+	}
+
 	/**
 	 * A convenience method to set the Content-Type header.
 	 *
@@ -629,6 +664,7 @@ component accessors="true" {
 		variables.queryParams = createObject( "java", "java.util.LinkedHashMap" ).init();
 		variables.headers     = createObject( "java", "java.util.LinkedHashMap" ).init();
 		variables.headers.put( "Content-Type", "application/json" );
+		variables.files             = [];
 		variables.requestCallbacks  = [];
 		variables.responseCallbacks = [];
 		return this;
@@ -662,11 +698,11 @@ component accessors="true" {
 		return this;
 	}
 
-    /**
-     * Clones the current request into a new HyperRequest.
-     * 
-     * @returns A new HyperRequest instance cloned from this one.
-     */
+	/**
+	 * Clones the current request into a new HyperRequest.
+	 *
+	 * @returns A new HyperRequest instance cloned from this one.
+	 */
 	public HyperRequest function clone() {
 		var req = new HyperRequest();
 		req.setInterceptorService( variables.interceptorService );
@@ -684,6 +720,7 @@ component accessors="true" {
 		req.setReferrer( isNull( variables.referrer ) ? javacast( "null", "" ) : variables.referrer );
 		req.setHeaders( variables.headers.clone() );
 		req.setQueryParams( variables.queryParams.clone() );
+		req.setFiles( duplicate( variables.files ) );
 		req.setThrowOnError( variables.throwOnError );
 		req.setClientCert( isNull( variables.clientCert ) ? javacast( "null", "" ) : variables.clientCert );
 		req.setClientCertPassword(

models/HyperResponse.cfc

@@ -92,10 +92,10 @@ component accessors="true" {
 	function json() {
 		if ( !isJSON( getData() ) ) {
 			throw(
-                type = "DeserializeJsonException",
-                message = "The response is not json.",
-                detail = getData()
-            );
+				type    = "DeserializeJsonException",
+				message = "The response is not json.",
+				detail  = getData()
+			);
 		}
 		return deserializeJSON( getData() );
 	}

tests/Application.cfc

@@ -15,4 +15,10 @@ component {
     this.mappings[ "/app" ] = testsPath & "resources/app";
     this.mappings[ "/coldbox" ] = testsPath & "resources/app/coldbox";
     this.mappings[ "/testbox" ] = rootPath & "/testbox";
+
+    // function onRequestStart() {
+    //     applicationStop();
+    //     abort;
+    // }
+
 }

tests/resources/app/config/Coldbox.cfc

@@ -36,7 +36,8 @@ component {
 			// Application Aspects
 			handlerCaching           : false,
 			eventCaching             : false,
-			viewCaching              : false
+			viewCaching              : false,
+			customErrorTemplate      : "/coldbox/system/exceptions/BugReport.cfm"
 		};
 
 		// custom settings
@@ -84,7 +85,7 @@ component {
 	 * Development environment
 	 */
 	function development() {
-		coldbox.customErrorTemplate = "/coldbox/system/includes/BugReport.cfm";
+		coldbox.customErrorTemplate = "/coldbox/system/exceptions/BugReport.cfm";
 	}
 
 }

tests/resources/app/handlers/api.cfc

@@ -35,4 +35,47 @@ component {
 		);
 	}
 
+	function photos( event, rc, prc ) {
+		if ( !event.valueExists( "smallPhoto" ) ) {
+			return event.renderData(
+				type       = "text",
+				statusCode = 422,
+				data       = "A `smallPhoto` is required."
+			);
+		}
+
+		if ( !event.valueExists( "largePhoto" ) ) {
+			return event.renderData(
+				type       = "text",
+				statusCode = 422,
+				data       = "A `largePhoto` is required."
+			);
+		}
+
+		var smallPhoto = fileUpload(
+			getTempDirectory(),
+			"smallPhoto",
+			"*",
+			"overwrite"
+		);
+
+		var largePhoto = fileUpload(
+			getTempDirectory(),
+			"largePhoto",
+			"*",
+			"overwrite"
+		);
+
+		return event.renderData(
+			type       = "json",
+			statusCode = 201,
+			data       = {
+				"id"          : 777,
+				"smallPhoto"  : smallPhoto.serverFile,
+				"largePhoto"  : largePhoto.serverFile,
+				"description" : rc.description
+			}
+		);
+	}
+
 }