@sjcrh/proteinpaint-front 2.207.1 → 2.208.0

package/README.md

@@ -11,33 +11,30 @@ an embedder.
 
 ## Usage
 
-The recommended usage is to include a postinstall script in your project as follows.
-```json
-	"scripts": {
-		"postinstall": "proteinpaint-front https://my.host.tld"
-	}
-```
+This package is used inside a ppfull container (https://github.com/stjude/proteinpaint/pkgs/container/ppfull).
+The container image ensures that a matching proteinpaint-server is used to serve the data as expected by 
+proteinpaint-client code. Standalone usage outside of a ppfull container is not recommended. From within
+the container, the command below is used:
 
-You can manually test your project's postinstall lifecyle script by running the following
-to extract the Proteinpaint bundles, with the correct public path for the dynamically 
-loaded Proteinpaint bundles.
 ```bash
 npx proteinpaint-front [URL_PUBLIC_PATH]
 ```
 
-If you omit the URL_PUBLIC_PATH argument above, then it will default to `'.'`, which assumes that the bundle is served by 
-the same PP server. But note that in this case, the web bundle or server host may NOT be embedded or used as host from 
-other domains, even if CORS is allowed, since script bundles will not be sourced properly and loaded dynamically.
+See `init.js` for details. If the URL_PUBLIC_PATH argument is omitted above, then it will default to `'.'`, 
+which assumes that the bundle is served by the same PP server. But note that in this case, the web bundle or 
+server host may NOT be embedded or used as host from other domains, even if CORS is allowed, since script 
+bundles will not be sourced properly and loaded dynamically.
 
-Note that you can serve the web bundle using the Proteinpaint server or any web server,
-see the example in the Develop section.
 
 ## Develop
 
+The usual dev workflow typically focuses on the client workspace development. For troubleshooting builds
+for production, the following may be performed:
+
 ```bash
-# must run the module bundling of proteinpaint-client
-cd ../client
-npm run rollw
+# must run the module bundling of proteinpaint-client, either from sjpp dev process or below
+cd ../client 
+npm run dev
 
 # in another terminal
 cd ../front

package/init.js

@@ -11,49 +11,98 @@ if (URLPATH.endsWith('/')) URLPATH = URLPATH.slice(0, -1)
 const publicBinOnly = process.argv.includes('--publicBinOnly')
 
 const CWD = process.cwd()
+const PUBLIC_DIR = `${CWD}/public`
+// The client bundle is generated into a PER-CONTAINER dir at CWD/bin — a sibling of public/, in the
+// container's own writable layer, NOT under any mount — and is served at /bin by the server, which
+// routes /bin to CWD/bin when it exists (see the server's serverconfig binDir + app.middlewares.js).
+//
+// It is deliberately NOT written into public/: when several instances bind-mount the SAME public/,
+// regenerating a shared public/bin at startup makes them clobber one another (one instance's recursive
+// rmdir races another's tar extract -> "ENOTEMPTY, Directory not empty: .../public/bin", crashing a
+// startup). Generating per-container removes the shared write entirely, so concurrent starts can't race
+// — no lock or cross-instance key needed. It also makes a rolling deploy safe: init never mutates the
+// shared public/bin, so instances still on an older release keep serving their own public/bin while new
+// instances serve their CWD/bin. An older image that has no CWD/bin also still works — the server falls
+// back to serving /bin from public/bin.
+const BIN_DIR = `${CWD}/bin`
+// A distinctively named marker written LAST, only after the bundle is fully extracted AND its __PP_URL__
+// placeholder is replaced. It serves two purposes:
+//   - completion: reuse requires it, so a container that stops mid-generation (after tar creates
+//     proteinpaint.js but before the URL rewrite, or on a partial extraction) regenerates on its next
+//     start instead of reusing a partial/unpatched bundle forever — which the health gate can't catch,
+//     since an unpatched or incomplete proteinpaint.js still returns 200.
+//   - ownership: the server publishes CWD/bin at /bin ONLY when this marker is present (see the server's
+//     app.middlewares.js), so launching the server package from a consumer project never exposes an
+//     unrelated CWD/bin (e.g. that project's own bin/ scripts) over HTTP. The name is distinctive so it
+//     won't collide with a consumer's files.
+const BIN_READY = `${BIN_DIR}/.pp-bundle-ready`
 
 console.log('CWD', CWD)
 try {
-	if (!fs.existsSync(`${CWD}/public`)) {
+	if (!fs.existsSync(PUBLIC_DIR)) {
 		console.log(`making a public directory at ${CWD}`)
-		fs.mkdirSync(`${CWD}/public`)
-	}
-	if (fs.existsSync(`${CWD}/public/bin`)) {
-		console.log(`removing the old public/bin at ${CWD}`)
-		// should update as part of v16 upgrade
-		fs.rmdirSync(`${CWD}/public/bin`, { recursive: true, force: true }, () => {})
+		fs.mkdirSync(PUBLIC_DIR)
 	}
+	// index.html / cards are ensured independently of the bundle below (idempotent, and needed even when
+	// the bundle is reused), so a skipped regeneration still leaves the public scaffolding in place.
 	if (!publicBinOnly) {
-		if (!fs.existsSync(`${CWD}/public/index.html`)) {
+		if (!fs.existsSync(`${PUBLIC_DIR}/index.html`)) {
 			console.log(`creating a public/index.html file`)
-			fs.copyFileSync(path.join(__dirname, './public/index.html'), `${CWD}/public/index.html`)
+			fs.copyFileSync(path.join(__dirname, './public/index.html'), `${PUBLIC_DIR}/index.html`)
 		}
-		if (!fs.existsSync(`${CWD}/public/cards`)) {
+		if (!fs.existsSync(`${PUBLIC_DIR}/cards`)) {
 			console.log(`Copying cards into public/cards folder`)
-			execSync(`cp -r ${CWD}/node_modules/@sjcrh/proteinpaint-front/public/cards ${CWD}/public/cards`, {
+			execSync(`cp -r ${CWD}/node_modules/@sjcrh/proteinpaint-front/public/cards ${PUBLIC_DIR}/cards`, {
 				stdio: 'inherit'
 			})
 		}
 	}
-	const tar = ps.spawnSync('tar', [`-xzf`, `${__dirname}/bundles.tgz`, `-C`, `${CWD}`], { encoding: 'utf8' })
-	if (tar.status !== 0) {
-		throw new Error(`Tar command failed with exit code ${tar.status}: ${tar.stderr}`)
-	}
-	if (tar.stderr) {
-		console.warn('Tar command warnings:', tar.stderr)
-	}
-	console.log(`Setting the dynamic bundle path to ${URLPATH}`)
-	const codeFile = `${CWD}/public/bin/proteinpaint.js`
-	// remember the modified time before setting the bundle public path
-	const mtime = fs.statSync(codeFile).mtime
-	const code = fs.readFileSync(codeFile, { encoding: 'utf8' })
-	const newcode = code.replace(`__PP_URL__`, `${URLPATH}/bin/`)
-	fs.writeFileSync(codeFile, newcode, { encoding: 'utf8' })
-	try {
-		// reset the atime and mtime to the original mtime before setting the bundle publit path
-		fs.utimesSync(codeFile, mtime, mtime)
-	} catch (e) {
-		console.log('--- !!! unable to reset the mtime for the extracted proteinpaint bundle: ', e)
+
+	// Generate the bundle into CWD/bin only if it isn't already there. CWD/bin is in the container's
+	// writable layer, so it persists across restarts of THIS container (reuse) and is empty in any freshly
+	// created container (regenerate) — including after an image update, which always yields a new
+	// container. Because CWD/bin is per-container, there is no shared directory to race on.
+	//
+	// NOTE: reuse is keyed on the completion marker (a fully extracted, URL-patched bundle), not on its
+	// version or URL. That is correct for the normal container lifecycle (a new image, or a changed URL,
+	// arrives with a new container and hence an empty CWD/bin). It would be stale only if the SAME
+	// container were reused across a bundle or URL change — e.g. CWD/bin persisted via a mounted volume,
+	// or serverconfig.json remounted with a different URL and merely restarted — uncommon, and outside
+	// this simple scheme.
+	if (fs.existsSync(BIN_READY)) {
+		console.log(`bundle already present and complete at ${BIN_DIR}; reusing it`)
+	} else {
+		if (fs.existsSync(BIN_DIR)) {
+			console.log(`removing an incomplete ${BIN_DIR}`)
+			fs.rmSync(BIN_DIR, { recursive: true, force: true })
+		}
+		// bundles.tgz contains public/bin/*; --strip-components=1 drops the leading public/ so the files
+		// land in CWD/bin/* (this container's private bin), not in the shared public/.
+		const tar = ps.spawnSync('tar', [`-xzf`, `${__dirname}/bundles.tgz`, `-C`, `${CWD}`, `--strip-components=1`], {
+			encoding: 'utf8'
+		})
+		if (tar.status !== 0) {
+			throw new Error(`Tar command failed with exit code ${tar.status}: ${tar.stderr}`)
+		}
+		if (tar.stderr) {
+			console.warn('Tar command warnings:', tar.stderr)
+		}
+		console.log(`Setting the dynamic bundle path to ${URLPATH}`)
+		const codeFile = `${BIN_DIR}/proteinpaint.js`
+		// remember the modified time before setting the bundle public path
+		const mtime = fs.statSync(codeFile).mtime
+		const code = fs.readFileSync(codeFile, { encoding: 'utf8' })
+		const newcode = code.replace(`__PP_URL__`, `${URLPATH}/bin/`)
+		fs.writeFileSync(codeFile, newcode, { encoding: 'utf8' })
+		try {
+			// reset the atime and mtime to the original mtime before setting the bundle public path
+			fs.utimesSync(codeFile, mtime, mtime)
+		} catch (e) {
+			console.log('--- !!! unable to reset the mtime for the extracted proteinpaint bundle: ', e)
+		}
+		// mark generation complete LAST (see BIN_READY above): a crash before this leaves no marker, so
+		// the next start regenerates rather than reusing a partial or unpatched bundle.
+		fs.writeFileSync(BIN_READY, '')
 	}
 } catch (e) {
 	console.error(e)

package/package.json

@@ -1,19 +1,20 @@
 {
 	"name": "@sjcrh/proteinpaint-front",
-	"version": "2.207.1",
+	"version": "2.208.0",
 	"browser": "src/app.js",
 	"main": "src/index.js",
 	"bin": "init.js",
 	"scripts": {
-		"dev": "./dev.sh &",
+		"dev": "./dev.sh",
 		"//TODO": "# delete webpack use, once esbuild migration is fully tested and unlikely to be reverted",
 		"client-dist": "if ! -d ../client/dist; then cd ../client; npm pack; fi",
-		"prepack": "npm run client-dist && rm -rf public/bin && rm -rf *.tgz && webpack && tar -czf bundles.tgz public/bin",
+		"prepack": "npm run client-dist && rm -rf public/bin && rm -rf *.tgz && webpack && tar -czf bundles.tgz public/bin && npm pkg set _buildTime=$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+		"postpack": "npm pkg delete _buildTime",
 		"test:unit": "echo 'TODO: front unit tests'",
 		"test:integration": "echo 'TODO: front integration tests'"
 	},
 	"devDependencies": {
-		"@sjcrh/proteinpaint-client": "2.207.1",
+		"@sjcrh/proteinpaint-client": "2.208.0",
 		"webpack": "^5.76.0",
 		"webpack-cli": "^4.9.2",
 		"webpack-node-externals": "^3.0.0"
@@ -30,5 +31,6 @@
 		"type": "git",
 		"url": "https://github.com/stjude/proteinpaint",
 		"directory": "front"
-	}
+	},
+	"_buildTime": "2026-09-13T18:12:02Z"
 }

package/public/index.html

@@ -8,7 +8,7 @@
   best practice is to use <script defer> or to put script tags before </body> end tag and
   just before the runproteinpaint() call
   -->
-  <script src="/bin/front/proteinpaint.js" charset="utf-8"></script>
+  <script src="/bin/proteinpaint.js" charset="utf-8"></script>
 </head>
 <body style="margin:0px;width:100%;height:100%">
 	
@@ -18,6 +18,7 @@
 
 <script>
 runproteinpaint({
+	//host: 'http://localhost:3000',
 	host: 'https://proteinpaint.stjude.org',
 	holder:document.getElementById('aaa'),
 	parseurl:true,