🐛 Make Conduit#serveFile() actually call the options.onError callback when an error occurs

Author: skerit

CHANGELOG.md

@@ -6,6 +6,7 @@
 * Plugin load failures will not stop Alchemy from starting
 * `die()` will now wait 1 synchronous second before exiting
 * Fix SettingValue » GroupValue conversion in settings system
+* Make `Conduit#serveFile()` actually call the `options.onError` callback when an error occurs
 
 ## 1.4.0 (2026-01-21)
 

lib/class/conduit.js

@@ -2153,7 +2153,7 @@ Conduit.setTypedMethod([Types.String, Types.Object.optional()], function serveFi
  *
  * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    0.2.0
- * @version  1.4.0
+ * @version  1.4.1
  *
  * @param    {Alchemy.Inode.File}   file      The file to serve
  * @param    {Object}               options   Options, including headers
@@ -2171,6 +2171,9 @@ Conduit.setTypedMethod([Types.Alchemy.Inode.File, Types.Object.optional()], asyn
 	} catch (err) {
 
 		if (err.code == 'ENOENT') {
+			if (options.onError) {
+				return options.onError(err);
+			}
 			return this.notFound(err);
 		}
 

test/26-conduit.js

@@ -1,5 +1,6 @@
 const assert = require('assert');
 const libfs = require('fs');
+const libpath = require('path');
 
 let post_pledge;
 
@@ -74,6 +75,83 @@ describe('Controller', function() {
 			await testFormSubmission(post_pledge, 'addfiles');
 		});
 	});
+
+	describe('#serveFile', function() {
+
+		let serve_file_pledge;
+
+		before(() => {
+			Router.add({
+				name    : 'ConduitTest#serveFileTest',
+				paths   : '/conduit/serve_file_test',
+				methods : 'get',
+			});
+
+			ConduitTestController.setAction(async function serveFileTest(conduit) {
+				let use_on_error = conduit.param('use_on_error') === 'true';
+				let file_path = conduit.param('file_path');
+
+				// Create an Inode.File instance
+				let file = new Classes.Alchemy.Inode.File(file_path);
+
+				let options = {};
+
+				if (use_on_error) {
+					options.onError = (err) => {
+						// Custom error handling: return a JSON response with error info
+						conduit.setHeader('content-type', 'application/json');
+						conduit.end(JSON.stringify({
+							custom_error: true,
+							error_code: err.code,
+							error_message: err.message
+						}));
+					};
+				}
+
+				return conduit.serveFile(file, options);
+			});
+		});
+
+		it('should call onError callback when serving a non-existent File object', async function() {
+
+			let non_existent_path = libpath.resolve(__dirname, 'does_not_exist_' + Date.now() + '.txt');
+			let url = global.getRouteUrl('ConduitTest#serveFileTest');
+			url += '?use_on_error=true&file_path=' + encodeURIComponent(non_existent_path);
+
+			let { response, body } = await harness.fetch(url);
+
+			// The onError callback should have been called, returning a JSON response
+			// instead of the default 404 notFound behavior
+			assert.strictEqual(response.statusCode, 200, 'Should return 200 because onError handled it');
+			
+			// Body may already be parsed as JSON by Blast.fetch
+			let parsed = typeof body === 'string' ? JSON.parse(body) : body;
+			assert.strictEqual(parsed.custom_error, true, 'Should have custom_error flag');
+			assert.strictEqual(parsed.error_code, 'ENOENT', 'Should have ENOENT error code');
+		});
+
+		it('should call notFound when onError is not provided for non-existent File', async function() {
+
+			let non_existent_path = libpath.resolve(__dirname, 'does_not_exist_' + Date.now() + '.txt');
+			let url = global.getRouteUrl('ConduitTest#serveFileTest');
+			url += '?use_on_error=false&file_path=' + encodeURIComponent(non_existent_path);
+
+			// Without onError, notFound should be called, returning 404
+			// Blast.fetch throws on 4xx/5xx status codes, so we need to catch the error
+			let threw = false;
+			let errorNumber;
+			
+			try {
+				await harness.fetch(url);
+			} catch (err) {
+				threw = true;
+				errorNumber = err.number;
+			}
+
+			assert.strictEqual(threw, true, 'Should throw an error for 404');
+			assert.strictEqual(errorNumber, 404, 'Should return 404 when file not found and no onError');
+		});
+	});
 });
 
 async function testFormSubmission(post_pledge, enctype) {