sea: support sea.getRawAsset()

This patch adds support for `sea.getRawAsset()` which is similar to `sea.getAsset()` but returns the raw asset in an array buffer without copying. Users should avoid writing to the returned array buffer. If the injected section is not marked as writable or not aligned, writing to the raw asset is likely to result in a crash. PR-URL: #50960 Refs: nodejs/single-executable#68 Reviewed-By: Antoine du Hamel <[email protected]> Reviewed-By: Stephen Belanger <[email protected]>

Author: joyeecheung

doc/api/single-executable-applications.md

@@ -219,6 +219,8 @@ const image = getAsset('a.jpg');
 const text = getAsset('b.txt', 'utf8');
 // Returns a Blob containing the asset.
 const blob = getAssetAsBlob('a.jpg');
+// Returns an ArrayBuffer containing the raw asset without copying.
+const raw = getRawAsset('a.jpg');
 ```
 
 See documentation of the [`sea.getAsset()`][] and [`sea.getAssetAsBlob()`][]
@@ -316,6 +318,27 @@ An error is thrown when no matching asset can be found.
  * `type`{string} An optional mime type for the blob.
 * Returns:{Blob}
 
+### `sea.getRawAsset(key)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+This method can be used to retrieve the assets configured to be bundled into the
+single-executable application at build time.
+An error is thrown when no matching asset can be found.
+
+Unlike `sea.getRawAsset()` or `sea.getAssetAsBlob()`, this method does not
+return a copy. Instead, it returns the raw asset bundled inside the executable.
+
+For now, users should avoid writing to the returned array buffer. If the
+injected section is not marked as writable or not aligned properly,
+writes to the returned array buffer is likely to result in a crash.
+
+* `key`{string} the key for the asset in the dictionary specified by the
+ `assets` field in the single-executable application configuration.
+* Returns:{string|ArrayBuffer}
+
 ### `require(id)` in the injected main script is not file based
 
 `require()` in the injected main script is not the same as the [`require()`][]

lib/sea.js

@@ -71,5 +71,6 @@ function getAssetAsBlob(key, options){
 module.exports={
  isSea,
  getAsset,
+ getRawAsset,
  getAssetAsBlob,
 };

test/fixtures/sea/get-asset-raw.js

@@ -0,0 +1,31 @@
+'use strict';
+
+const{ isSea, getAsset, getRawAsset }=require('node:sea');
+const{ readFileSync }=require('fs');
+constassert=require('assert');
+
+assert(isSea());
+
+{
+assert.throws(()=>getRawAsset('nonexistent'),{
+code: 'ERR_SINGLE_EXECUTABLE_APPLICATION_ASSET_NOT_FOUND'
+});
+assert.throws(()=>getRawAsset(null),{
+code: 'ERR_INVALID_ARG_TYPE'
+});
+assert.throws(()=>getRawAsset(1),{
+code: 'ERR_INVALID_ARG_TYPE'
+});
+}
+
+{
+// Check that the asset embedded is the same as the original.
+constassetOnDisk=readFileSync(process.env.__TEST_PERSON_JPG);
+constassetCopy=getAsset('person.jpg')
+constassetCopyBuffer=Buffer.from(assetCopy);
+assert.deepStrictEqual(assetCopyBuffer,assetOnDisk);
+
+// Check that the copied asset is the same as the raw one.
+constrawAsset=getRawAsset('person.jpg');
+assert.deepStrictEqual(rawAsset,assetCopy);
+}

test/fixtures/sea/get-asset.js

@@ -77,6 +77,8 @@ const binaryAssetOnDisk = readFileSync(process.env.__TEST_PERSON_JPG);
 {
 constactualAsset=getAsset('utf8_test_text.txt','utf8')
 assert.strictEqual(actualAsset,textAssetOnDisk);
+// Log it out so that the test could compare it and see if
+// it's encoded/decoded correctly in the SEA.
 console.log(actualAsset);
 }
 

test/sequential/sequential.status

@@ -51,6 +51,7 @@ test-performance-eventloopdelay: PASS, FLAKY
 
 [$system==linux && $arch==ppc64]
 # https://github.com/nodejs/node/issues/50740
+test-single-executable-application-assets-raw: PASS, FLAKY
 test-single-executable-application-assets: PASS, FLAKY
 test-single-executable-application-disable-experimental-sea-warning: PASS, FLAKY
 test-single-executable-application-empty: PASS, FLAKY

test/sequential/test-single-executable-application-assets-raw.js

@@ -0,0 +1,73 @@
+'use strict';
+
+constcommon=require('../common');
+
+const{
+ injectAndCodeSign,
+ skipIfSingleExecutableIsNotSupported,
+}=require('../common/sea');
+
+skipIfSingleExecutableIsNotSupported();
+
+// This tests the snapshot support in single executable applications.
+consttmpdir=require('../common/tmpdir');
+
+const{ copyFileSync, writeFileSync, existsSync }=require('fs');
+const{
+ spawnSyncAndExitWithoutError,
+}=require('../common/child_process');
+constassert=require('assert');
+constfixtures=require('../common/fixtures');
+
+tmpdir.refresh();
+if(!tmpdir.hasEnoughSpace(120*1024*1024)){
+common.skip('Not enough disk space');
+}
+
+constconfigFile=tmpdir.resolve('sea-config.json');
+constseaPrepBlob=tmpdir.resolve('sea-prep.blob');
+constoutputFile=tmpdir.resolve(process.platform==='win32' ? 'sea.exe' : 'sea');
+
+{
+tmpdir.refresh();
+copyFileSync(fixtures.path('sea','get-asset-raw.js'),tmpdir.resolve('sea.js'));
+copyFileSync(fixtures.path('person.jpg'),tmpdir.resolve('person.jpg'));
+writeFileSync(configFile,`
+{
+ "main": "sea.js",
+ "output": "sea-prep.blob",
+ "assets":{
+ "person.jpg": "person.jpg"
+ }
+ }
+ `,'utf8');
+
+spawnSyncAndExitWithoutError(
+process.execPath,
+['--experimental-sea-config','sea-config.json'],
+{
+env: {
+NODE_DEBUG_NATIVE: 'SEA',
+ ...process.env,
+},
+cwd: tmpdir.path
+},
+{});
+
+assert(existsSync(seaPrepBlob));
+
+copyFileSync(process.execPath,outputFile);
+injectAndCodeSign(outputFile,seaPrepBlob);
+
+spawnSyncAndExitWithoutError(
+outputFile,
+{
+env: {
+ ...process.env,
+NODE_DEBUG_NATIVE: 'SEA',
+__TEST_PERSON_JPG: fixtures.path('person.jpg'),
+}
+},
+{}
+);
+}