Offload Oxide scanning to separate process (#1471)

Loading Oxide's .node file into the language server process / VSCode
extension host on Windows marks that .node file as in use. When this
happens you cannot completely delete node_modules (for example by
running `npm ci`).

To work around this we'll fork a new process that can load Oxide, run
its scan(s), and then exit. During initial project discovery we use a
temporarily long lived process that persists for the duration of project
discovery — which may include multiple Oxide scans across projects (and
even versions). Once the project discovery has completed the process
will exit. For any subsequent content scanning (e.g. when CSS changes)
we'll spawn a new, temporary process for that individual scan.

This will ensure that, once the process has exited, the `.node` file is
no longer considered to be in-use and commands like `npm ci` will run
properly.

## Commentary

### Why not use `require.cache`?

Unfortunately, deleting entries from `require.cache` does not unload the
Oxide binary from the process address space.

### Why not worker threads

So, this might work but also might not. You'd still be loading it into
the processes address space so there's a chance that as long as the
process is open — whether the thread has exited or not — the `.node`
file would still be marked as in use.

Additionally, we have some flags set when building Oxide that basically
prevent it from unloading in worker threads due to some bugs in the Rust
standard library. This applies to Linux only iirc so it shouldn't
actually be a problem there but I'd rather keep the mechanism working
consistently across operating systems.

### Communication between processes

The main process and helper communicate using a JSON-RPC protocol —
similar to the one used by language servers/clients — but without any
initialization setup. This is an internal tool and the message format is
not considered stable and may change in any future version.

Communication happens over an IPC channel provided by
`child_process.fork(…)`. As far as I am aware, this uses private file
descriptors shared between processes. No other process should be capable
of "tricking" the helper into loading other `.node` files into its
address space. Only the ones we discover during NPM package resolution
should ever be loaded. Even though the temporary helper isn't active for
very long this was still a concern I had while developing this.

## Test Plan

There are automated tests that verify existing functionality still works
but testing this specific scenario on Windows in an automated fashion
with the current test setup would be a bit annoying so I did some
additional manual testing:

- Set up a small Tailwind CSS v4 project on Windows
- Opened VS Code with the current version of the extension
- Ran `npm ci` in the terminal and watched it fail b/c of the Oxide
`.node` file
- Loaded the new extension through the extension development host
- Repeated the steps
- Ran `npm ci` multiple times to make sure it worked

Author: thecrypticace

packages/tailwindcss-language-server/package.json

@@ -13,8 +13,9 @@
   },
   "homepage": "https://github.com/tailwindlabs/tailwindcss-intellisense/tree/HEAD/packages/tailwindcss-language-server#readme",
   "scripts": {
-    "build": "pnpm run clean && pnpm run _esbuild && pnpm run _esbuild:css",
+    "build": "pnpm run clean && pnpm run _esbuild && pnpm run _esbuild:oxide && pnpm run _esbuild:css",
     "_esbuild": "node ../../esbuild.mjs src/server.ts --outfile=bin/tailwindcss-language-server --minify",
+    "_esbuild:oxide": "node ../../esbuild.mjs src/oxide-helper.ts --outfile=bin/oxide-helper.js --minify",
     "_esbuild:css": "node ../../esbuild.mjs src/language/css.ts --outfile=bin/css-language-server --minify",
     "clean": "rimraf bin",
     "prepublishOnly": "pnpm run build",

packages/tailwindcss-language-server/src/oxide-helper.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+
+import * as rpc from 'vscode-jsonrpc/node'
+import { scan, type ScanOptions, type ScanResult } from './oxide'
+
+let connection = rpc.createMessageConnection(
+  new rpc.IPCMessageReader(process),
+  new rpc.IPCMessageWriter(process),
+)
+
+let scanRequest = new rpc.RequestType<ScanOptions, ScanResult, void>('scan')
+connection.onRequest<ScanOptions, ScanResult, void>(scanRequest, (options) => scan(options))
+
+connection.listen()

packages/tailwindcss-language-server/src/oxide-session.ts

@@ -0,0 +1,93 @@
+import * as rpc from 'vscode-jsonrpc/node'
+import * as proc from 'node:child_process'
+import * as path from 'node:path'
+import * as fs from 'node:fs/promises'
+import { type ScanOptions, type ScanResult } from './oxide'
+
+/**
+ * This helper starts a session in which we can use Oxide in *another process*
+ * to communicate content scanning results.
+ *
+ * Thie exists for two reasons:
+ * - The Oxide API has changed over time so this function presents a unified
+ *   interface that works with all versions of the Oxide API. The results may
+ *   vary but the structure of the results will always be identical.
+ *
+ * - Requiring a native node module on Windows permanently keeps an open handle
+ *   to the binary for the duration of the process. This prevents unlinking the
+ *   file like happens when running `npm ci`. Running an ephemeral process lets
+ *   us sidestep the problem as the process will only be running as needed.
+ */
+export class OxideSession {
+  helper: proc.ChildProcess | null = null
+  connection: rpc.MessageConnection | null = null
+
+  public async scan(options: ScanOptions): Promise<ScanResult> {
+    await this.startIfNeeded()
+
+    return await this.connection.sendRequest('scan', options)
+  }
+
+  async startIfNeeded(): Promise<void> {
+    if (this.connection) return
+
+    // TODO: Can we find a way to not require a build first?
+    // let module = path.resolve(path.dirname(__filename), './oxide-helper.ts')
+
+    let modulePaths = [
+      // Separate Language Server package
+      '../bin/oxide-helper.js',
+
+      // Bundled with the VSCode extension
+      '../dist/oxide-helper.js',
+    ]
+
+    let module: string | null = null
+
+    for (let relativePath of modulePaths) {
+      let filepath = path.resolve(path.dirname(__filename), relativePath)
+
+      if (
+        await fs.access(filepath).then(
+          () => true,
+          () => false,
+        )
+      ) {
+        module = filepath
+        break
+      }
+    }
+
+    if (!module) throw new Error('unable to load')
+
+    let helper = proc.fork(module)
+    let connection = rpc.createMessageConnection(
+      new rpc.IPCMessageReader(helper),
+      new rpc.IPCMessageWriter(helper),
+    )
+
+    helper.on('disconnect', () => {
+      connection.dispose()
+      this.connection = null
+      this.helper = null
+    })
+
+    helper.on('exit', () => {
+      connection.dispose()
+      this.connection = null
+      this.helper = null
+    })
+
+    connection.listen()
+
+    this.helper = helper
+    this.connection = connection
+  }
+
+  async stop() {
+    if (!this.helper) return
+
+    this.helper.disconnect()
+    this.helper.kill()
+  }
+}

packages/tailwindcss-language-server/src/oxide.ts

@@ -111,14 +111,14 @@ interface SourceEntry {
   negated: boolean
 }
 
-interface ScanOptions {
+export interface ScanOptions {
   oxidePath: string
   oxideVersion: string
   basePath: string
   sources: Array<SourceEntry>
 }
 
-interface ScanResult {
+export interface ScanResult {
   files: Array<string>
   globs: Array<GlobEntry>
 }

packages/tailwindcss-language-server/src/project-locator.ts

@@ -16,6 +16,7 @@ import { normalizeDriveLetter, normalizePath, pathToFileURL } from './utils'
 import postcss from 'postcss'
 import * as oxide from './oxide'
 import { analyzeStylesheet, TailwindStylesheet } from './version-guesser'
+import { OxideSession } from './oxide-session'
 
 export interface ProjectConfig {
   /** The folder that contains the project */
@@ -60,7 +61,10 @@ export class ProjectLocator {
     let configs = await this.findConfigs()
 
     // Create a project for each of the config files
-    let results = await Promise.allSettled(configs.map((config) => this.createProject(config)))
+    let session = new OxideSession()
+    let results = await Promise.allSettled(
+      configs.map((config) => this.createProject(config, session)),
+    )
     let projects: ProjectConfig[] = []
 
     for (let result of results) {
@@ -98,6 +102,8 @@ export class ProjectLocator {
       }
     }
 
+    await session.stop()
+
     return projects
   }
 
@@ -148,7 +154,10 @@ export class ProjectLocator {
     }
   }
 
-  private async createProject(config: ConfigEntry): Promise<ProjectConfig | null> {
+  private async createProject(
+    config: ConfigEntry,
+    session: OxideSession,
+  ): Promise<ProjectConfig | null> {
     let tailwind = await this.detectTailwindVersion(config)
 
     let possibleVersions = config.entries.flatMap((entry) => entry.meta?.versions ?? [])
@@ -218,7 +227,12 @@ export class ProjectLocator {
     // Look for the package root for the config
     config.packageRoot = await getPackageRoot(path.dirname(config.path), this.base)
 
-    let selectors = await calculateDocumentSelectors(config, tailwind.features, this.resolver)
+    let selectors = await calculateDocumentSelectors(
+      config,
+      tailwind.features,
+      this.resolver,
+      session,
+    )
 
     return {
       config,
@@ -520,10 +534,11 @@ function contentSelectorsFromConfig(
   entry: ConfigEntry,
   features: Feature[],
   resolver: Resolver,
+  session: OxideSession,
   actualConfig?: any,
 ): AsyncIterable<DocumentSelector> {
   if (entry.type === 'css') {
-    return contentSelectorsFromCssConfig(entry, resolver)
+    return contentSelectorsFromCssConfig(entry, resolver, session)
   }
 
   if (entry.type === 'js') {
@@ -582,6 +597,7 @@ async function* contentSelectorsFromJsConfig(
 async function* contentSelectorsFromCssConfig(
   entry: ConfigEntry,
   resolver: Resolver,
+  session: OxideSession,
 ): AsyncIterable<DocumentSelector> {
   let auto = false
   for (let item of entry.content) {
@@ -606,6 +622,7 @@ async function* contentSelectorsFromCssConfig(
         entry.path,
         sources,
         resolver,
+        session,
       )) {
         yield {
           pattern,
@@ -621,14 +638,15 @@ async function* detectContentFiles(
   inputFile: string,
   sources: SourcePattern[],
   resolver: Resolver,
+  session: OxideSession,
 ): AsyncIterable<string> {
   try {
     let oxidePath = await resolver.resolveJsId('@tailwindcss/oxide', base)
     oxidePath = pathToFileURL(oxidePath).href
     let oxidePackageJsonPath = await resolver.resolveJsId('@tailwindcss/oxide/package.json', base)
     let oxidePackageJson = JSON.parse(await fs.readFile(oxidePackageJsonPath, 'utf8'))
 
-    let result = await oxide.scan({
+    let result = await session.scan({
       oxidePath,
       oxideVersion: oxidePackageJson.version,
       basePath: base,
@@ -654,11 +672,23 @@ async function* detectContentFiles(
       base = normalizeDriveLetter(base)
       yield `${base}/${pattern}`
     }
-  } catch {
-    //
+  } catch (err) {
+    if (isResolutionError(err)) return
+
+    console.error(err)
   }
 }
 
+function isResolutionError(err: unknown): boolean {
+  return (
+    err &&
+    typeof err === 'object' &&
+    'message' in err &&
+    typeof err.message === 'string' &&
+    err.message.includes("Can't resolve")
+  )
+}
+
 type ContentItem =
   | { kind: 'file'; file: string }
   | { kind: 'raw'; content: string }
@@ -812,8 +842,15 @@ export async function calculateDocumentSelectors(
   config: ConfigEntry,
   features: Feature[],
   resolver: Resolver,
+  session?: OxideSession,
   actualConfig?: any,
 ) {
+  let hasTemporarySession = false
+  if (!session) {
+    hasTemporarySession = true
+    session = new OxideSession()
+  }
+
   let selectors: DocumentSelector[] = []
 
   // selectors:
@@ -834,7 +871,13 @@ export async function calculateDocumentSelectors(
   })
 
   // - Content patterns from config
-  for await (let selector of contentSelectorsFromConfig(config, features, resolver, actualConfig)) {
+  for await (let selector of contentSelectorsFromConfig(
+    config,
+    features,
+    resolver,
+    session,
+    actualConfig,
+  )) {
     selectors.push(selector)
   }
 
@@ -876,5 +919,9 @@ export async function calculateDocumentSelectors(
     return 0
   })
 
+  if (hasTemporarySession) {
+    await session.stop()
+  }
+
   return selectors
 }

packages/tailwindcss-language-server/src/projects.ts

@@ -964,6 +964,7 @@ export async function createProjectService(
         projectConfig.config,
         state.features,
         resolver,
+        undefined,
         originalConfig,
       )
     }

packages/tailwindcss-language-server/tests/common.ts

@@ -91,6 +91,18 @@ export async function init(
     projectDetails = project
   })
 
+  // TODO: This shouldn't be needed
+  // The server should either delay requests *or*
+  // openDocument shouldn't return until the project its a part of has been
+  // built otherwise all requests will return nothing and it's not something
+  // we can await directly right now
+  //
+  // Like maybe documentReady should be delayed by project build state?
+  // because otherwise the document isn't really ready anyway
+  let projectBuilt = new Promise<void>((resolve) => {
+    client.conn.onNotification('@/tailwindCSS/projectReloaded', () => resolve())
+  })
+
   return {
     client,
     fixtureUri(fixture: string) {
@@ -130,6 +142,8 @@ export async function init(
         settings,
       })
 
+      await projectBuilt
+
       return {
         get uri() {
           return doc.uri.toString()

packages/vscode-tailwindcss/package.json

@@ -373,7 +373,7 @@
     }
   },
   "scripts": {
-    "_esbuild": "node ../../esbuild.mjs src/extension.ts src/server.ts src/cssServer.ts --outdir=dist",
+    "_esbuild": "node ../../esbuild.mjs src/extension.ts src/server.ts src/cssServer.ts src/oxide-helper.ts --outdir=dist",
     "dev": "concurrently --raw --kill-others \"pnpm run watch\" \"pnpm run check --watch\"",
     "watch": "pnpm run clean && pnpm run _esbuild --watch",
     "build": "pnpm run check && pnpm run clean && pnpm run _esbuild --minify && move-file dist/server.js dist/tailwindServer.js && move-file dist/cssServer.js dist/tailwindModeServer.js",

packages/vscode-tailwindcss/src/oxide-helper.ts

@@ -0,0 +1 @@
+import '@tailwindcss/language-server/src/oxide-helper'