vite-plugin-taro 0.2.2 → 0.3.0

package/src/node/targets/wx/dev-server/update-server-state.ts

@@ -0,0 +1,183 @@
+/**
+ * Pure host-side stop-and-wait protocol state machine.
+ *
+ * It retains versioned Rolldown deltas and selects one missing range for the active App Service. HTTP and filesystem
+ * effects are represented as commands and handled by update-transport.ts.
+ */
+type WxUpdateDelta = {
+    version: number
+    code: string
+}
+
+export type WxUpdateBatch = {
+    buildId: string
+    sessionId: string
+    fromVersion: number
+    targetVersion: number
+    deltas: WxUpdateDelta[]
+}
+
+type WxUpdateServerState = {
+    buildId: string
+    hostVersion: number
+    retainedDeltaBytes: number
+    deltas: WxUpdateDelta[]
+    activeSessionId?: string
+    retiredSessionIds: string[]
+    inFlight?: Pick<WxUpdateBatch, 'sessionId' | 'fromVersion' | 'targetVersion'>
+}
+
+type WxUpdateServerEvent =
+    | { type: 'delta-added'; code: string; bytes?: number }
+    | { type: 'client-registered'; buildId: string; sessionId: string; version: number }
+    | { type: 'client-reported'; buildId: string; sessionId: string; version: number }
+    | { type: 'batch-publish-failed'; sessionId: string; targetVersion: number }
+    | { type: 'full-build-committed'; buildId: string }
+
+export type WxUpdateServerCommand =
+    | { type: 'publish-batch'; batch: WxUpdateBatch }
+    | { type: 'request-full-build'; reason: 'client-version-ahead' | 'invalid-client-version' }
+    | { type: 'ignore-client'; reason: 'stale-build' | 'retired-session' | 'unknown-session' }
+
+type WxUpdateServerTransition = {
+    state: WxUpdateServerState
+    commands: WxUpdateServerCommand[]
+}
+
+export function createWxUpdateServerState(buildId: string): WxUpdateServerState {
+    return {
+        buildId,
+        hostVersion: 0,
+        retainedDeltaBytes: 0,
+        deltas: [],
+        retiredSessionIds: []
+    }
+}
+
+export function transitionWxUpdateServer(
+    state: WxUpdateServerState,
+    event: WxUpdateServerEvent
+): WxUpdateServerTransition {
+    switch (event.type) {
+        case 'delta-added': {
+            const version = state.hostVersion + 1
+            return transition({
+                ...state,
+                hostVersion: version,
+                retainedDeltaBytes: state.retainedDeltaBytes + (event.bytes ?? event.code.length),
+                deltas: [...state.deltas, { version, code: event.code }]
+            })
+        }
+        case 'client-registered':
+            return registerClient(state, event)
+        case 'client-reported':
+            return reportClient(state, event)
+        case 'batch-publish-failed':
+            if (state.inFlight?.sessionId !== event.sessionId || state.inFlight.targetVersion !== event.targetVersion) {
+                return transition(state)
+            }
+            return transition({ ...state, inFlight: undefined })
+        case 'full-build-committed':
+            return transition(createWxUpdateServerState(event.buildId))
+    }
+}
+
+function registerClient(
+    state: WxUpdateServerState,
+    client: { buildId: string; sessionId: string; version: number }
+): WxUpdateServerTransition {
+    const rejected = rejectClient(state, client)
+    if (rejected) return rejected
+    if (state.retiredSessionIds.includes(client.sessionId)) {
+        return command(state, { type: 'ignore-client', reason: 'retired-session' })
+    }
+    if (state.activeSessionId === client.sessionId) return transition(state)
+
+    const retiredSessionIds = state.activeSessionId
+        ? [...new Set([...state.retiredSessionIds, state.activeSessionId])]
+        : state.retiredSessionIds
+    const registered = {
+        ...state,
+        activeSessionId: client.sessionId,
+        retiredSessionIds,
+        inFlight: undefined
+    }
+    return transition(registered)
+}
+
+function reportClient(
+    state: WxUpdateServerState,
+    client: { buildId: string; sessionId: string; version: number }
+): WxUpdateServerTransition {
+    const rejected = rejectClient(state, client)
+    if (rejected) return rejected
+    if (state.retiredSessionIds.includes(client.sessionId)) {
+        return command(state, { type: 'ignore-client', reason: 'retired-session' })
+    }
+    if (client.sessionId !== state.activeSessionId) {
+        return command(state, { type: 'ignore-client', reason: 'unknown-session' })
+    }
+    return synchronizeClient(state, client.version)
+}
+
+function rejectClient(
+    state: WxUpdateServerState,
+    client: { buildId: string; version: number }
+): WxUpdateServerTransition | undefined {
+    if (client.buildId !== state.buildId) {
+        return command(state, { type: 'ignore-client', reason: 'stale-build' })
+    }
+    if (!Number.isInteger(client.version) || client.version < 0) {
+        return command(state, { type: 'request-full-build', reason: 'invalid-client-version' })
+    }
+    if (client.version > state.hostVersion) {
+        return command(state, { type: 'request-full-build', reason: 'client-version-ahead' })
+    }
+}
+
+function synchronizeClient(state: WxUpdateServerState, clientVersion: number): WxUpdateServerTransition {
+    let synchronized = state
+    const inFlight = state.inFlight
+    if (inFlight) {
+        if (clientVersion === inFlight.fromVersion) {
+            const batch = createBatch(state, clientVersion, inFlight.targetVersion)
+            return command(state, { type: 'publish-batch', batch })
+        }
+        if (clientVersion !== inFlight.targetVersion) {
+            return command(state, { type: 'request-full-build', reason: 'invalid-client-version' })
+        }
+        synchronized = { ...state, inFlight: undefined }
+    }
+    if (clientVersion >= synchronized.hostVersion) return transition(synchronized)
+
+    const batch = createBatch(synchronized, clientVersion, synchronized.hostVersion)
+    return command(
+        {
+            ...synchronized,
+            inFlight: {
+                sessionId: batch.sessionId,
+                fromVersion: batch.fromVersion,
+                targetVersion: batch.targetVersion
+            }
+        },
+        { type: 'publish-batch', batch }
+    )
+}
+
+function createBatch(state: WxUpdateServerState, fromVersion: number, targetVersion: number): WxUpdateBatch {
+    return {
+        buildId: state.buildId,
+        sessionId: state.activeSessionId!,
+        fromVersion,
+        targetVersion,
+        deltas: state.deltas.filter((delta) => delta.version > fromVersion && delta.version <= targetVersion)
+    }
+}
+
+function transition(state: WxUpdateServerState): WxUpdateServerTransition {
+    return { state, commands: [] }
+}
+
+function command(state: WxUpdateServerState, value: WxUpdateServerCommand): WxUpdateServerTransition {
+    return { state, commands: [value] }
+}

package/src/node/targets/wx/dev-server/update-transport.ts

@@ -0,0 +1,261 @@
+/**
+ * Adapts the pure server protocol to Vite HTTP middleware and literal update-file publication.
+ * HTTP messages contain metadata only; executable JavaScript reaches DevTools through the injected file writer.
+ */
+import { randomBytes } from 'node:crypto'
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { ViteDevServer } from 'vite'
+import {
+    createWxUpdateServerState,
+    transitionWxUpdateServer,
+    type WxUpdateBatch,
+    type WxUpdateServerCommand
+} from './update-server-state.ts'
+
+const endpointPath = '/__vite_plugin_taro_wx_update__'
+// Keep the host response below update-client.ts's 30-second wx.request timeout.
+const pollTimeout = 25_000
+
+type PendingPoll = {
+    response: ServerResponse
+    timeout: NodeJS.Timeout
+}
+
+type UpdateRequest = {
+    token?: unknown
+    action?: unknown
+    buildId?: unknown
+    sessionId?: unknown
+    version?: unknown
+}
+
+export class WxUpdateTransport {
+    private state = createWxUpdateServerState(createId())
+    private readonly token = createId()
+    private readonly pendingPolls = new Map<string, PendingPoll>()
+    private closed = false
+
+    constructor(
+        private readonly server: ViteDevServer,
+        private readonly requestFullBuild: () => void,
+        private readonly writeUpdateFile: (buildId: string, source: string) => Promise<void>
+    ) {}
+
+    get retainedDeltaCount(): number {
+        return this.state.hostVersion
+    }
+
+    get retainedDeltaBytes(): number {
+        return this.state.retainedDeltaBytes
+    }
+
+    install(): void {
+        this.server.middlewares.use(endpointPath, this.handleRequest)
+    }
+
+    close(): void {
+        this.closed = true
+        this.respondToAll({ type: 'rebuilding' })
+    }
+
+    addDelta(code: string): void {
+        this.apply({ type: 'delta-added', code, bytes: Buffer.byteLength(code) })
+        this.respondToAll({ type: 'changed' })
+    }
+
+    createBuildId(): string {
+        return createId()
+    }
+
+    isCurrentBuild(buildId: string): boolean {
+        return this.state.buildId === buildId
+    }
+
+    commitFullBuild(buildId: string): void {
+        this.apply({ type: 'full-build-committed', buildId })
+        this.respondToAll({ type: 'rebuilding' })
+    }
+
+    /** Generates late-bound App metadata after Vite has selected its actual listening port. */
+    createControlSource(buildId = this.state.buildId): string {
+        const address = this.server.httpServer?.address()
+        const port = address && typeof address !== 'string' ? address.port : this.server.config.server.port
+        return `globalThis.__VITE_PLUGIN_TARO_WX_CONTROL__ = ${JSON.stringify({
+            url: `http://localhost:${port}${endpointPath}`,
+            token: this.token,
+            buildId
+        })};\n`
+    }
+
+    private readonly handleRequest = async (request: IncomingMessage, response: ServerResponse): Promise<void> => {
+        if (this.closed || request.method !== 'POST') {
+            respond(response, 404, { type: 'not-found' })
+            return
+        }
+
+        let body: UpdateRequest
+        try {
+            body = JSON.parse(await readBody(request)) as UpdateRequest
+        } catch {
+            respond(response, 400, { type: 'invalid-request' })
+            return
+        }
+        if (body.token !== this.token || !isClientReport(body)) {
+            respond(response, 403, { type: 'forbidden' })
+            return
+        }
+
+        if (body.action === 'rebuild') {
+            this.requestFullBuild()
+            respond(response, 202, { type: 'rebuilding' })
+            return
+        }
+        if (body.action === 'register') {
+            const transition = this.apply({
+                type: 'client-registered',
+                buildId: body.buildId,
+                sessionId: body.sessionId,
+                version: body.version
+            })
+            if (transition.some((command) => command.type === 'request-full-build')) this.requestFullBuild()
+            respond(response, 200, { type: 'registered' })
+            return
+        }
+        if (body.action !== 'poll') {
+            respond(response, 400, { type: 'invalid-request' })
+            return
+        }
+
+        const commands = this.apply({
+            type: 'client-reported',
+            buildId: body.buildId,
+            sessionId: body.sessionId,
+            version: body.version
+        })
+        await this.executePollCommands(body.sessionId, commands, response)
+    }
+
+    private async executePollCommands(
+        sessionId: string,
+        commands: WxUpdateServerCommand[],
+        response: ServerResponse
+    ): Promise<void> {
+        const publish = commands.find((command) => command.type === 'publish-batch')
+        if (publish?.type === 'publish-batch') {
+            try {
+                await this.writeBatch(publish.batch)
+                respond(response, 200, { type: 'batch-published', targetVersion: publish.batch.targetVersion })
+            } catch {
+                this.apply({
+                    type: 'batch-publish-failed',
+                    sessionId: publish.batch.sessionId,
+                    targetVersion: publish.batch.targetVersion
+                })
+                respond(response, 500, { type: 'publish-failed' })
+            }
+            return
+        }
+        if (commands.some((command) => command.type === 'request-full-build')) {
+            this.requestFullBuild()
+            respond(response, 202, { type: 'rebuilding' })
+            return
+        }
+        if (commands.some((command) => command.type === 'ignore-client')) {
+            respond(response, 409, { type: 'rebuilding' })
+            return
+        }
+        this.holdPoll(sessionId, response)
+    }
+
+    private holdPoll(sessionId: string, response: ServerResponse): void {
+        const previous = this.pendingPolls.get(sessionId)
+        if (previous) this.finishPoll(sessionId, previous, { type: 'changed' })
+
+        let pending: PendingPoll
+        pending = {
+            response,
+            timeout: setTimeout(() => this.finishPoll(sessionId, pending, { type: 'idle' }), pollTimeout)
+        }
+        this.pendingPolls.set(sessionId, pending)
+        response.on('close', () => this.finishPoll(sessionId, pending))
+    }
+
+    private respondToAll(value: { type: string }): void {
+        for (const [sessionId, pending] of this.pendingPolls) this.finishPoll(sessionId, pending, value)
+    }
+
+    private finishPoll(sessionId: string, pending: PendingPoll, value?: { type: string }): void {
+        if (this.pendingPolls.get(sessionId) !== pending) return
+        clearTimeout(pending.timeout)
+        this.pendingPolls.delete(sessionId)
+        if (value) respond(pending.response, 200, value)
+    }
+
+    private apply(event: Parameters<typeof transitionWxUpdateServer>[1]): WxUpdateServerCommand[] {
+        const transition = transitionWxUpdateServer(this.state, event)
+        this.state = transition.state
+        return transition.commands
+    }
+
+    private async writeBatch(batch: WxUpdateBatch): Promise<void> {
+        await this.writeUpdateFile(batch.buildId, renderBatch(batch, createId()))
+    }
+}
+
+/** Renders executable code for update.js; this source is never included in an HTTP response. */
+function renderBatch(batch: WxUpdateBatch, nonce: string): string {
+    return `// ${nonce}\nglobalThis.__VITE_PLUGIN_TARO_WX_UPDATE_CLIENT__.receiveBatch(${JSON.stringify({
+        buildId: batch.buildId,
+        fromVersion: batch.fromVersion,
+        targetVersion: batch.targetVersion
+    })}, () => {
+${indent(batch.deltas.map((delta) => delta.code).join('\n'), 4)}
+});\n`
+}
+
+function indent(value: string, spaces: number): string {
+    const prefix = ' '.repeat(spaces)
+    return value
+        .split('\n')
+        .map((line) => `${prefix}${line}`)
+        .join('\n')
+}
+
+function isClientReport(value: UpdateRequest): value is {
+    token: string
+    action: 'register' | 'poll' | 'rebuild'
+    buildId: string
+    sessionId: string
+    version: number
+} {
+    return (
+        typeof value.token === 'string' &&
+        typeof value.action === 'string' &&
+        typeof value.buildId === 'string' &&
+        typeof value.sessionId === 'string' &&
+        typeof value.version === 'number'
+    )
+}
+
+async function readBody(request: IncomingMessage): Promise<string> {
+    const chunks: Buffer[] = []
+    let size = 0
+    for await (const chunk of request) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)
+        size += buffer.length
+        if (size > 64 * 1024) throw new Error('WX update request body is too large.')
+        chunks.push(buffer)
+    }
+    return Buffer.concat(chunks).toString('utf8')
+}
+
+function respond(response: ServerResponse, status: number, body: unknown): void {
+    if (response.writableEnded) return
+    response.statusCode = status
+    response.setHeader('content-type', 'application/json')
+    response.end(JSON.stringify(body))
+}
+
+function createId(): string {
+    return randomBytes(16).toString('hex')
+}

package/src/node/targets/wx/dev-server/vite-bundled-dev-adapter.ts

@@ -0,0 +1,203 @@
+import path from 'node:path'
+import type { ResolvedConfig, ViteDevServer } from 'vite'
+import { wxPagePreloadFile, wxUpdateControlFile, wxUpdateFile } from '../development-files.ts'
+import type { WxOutputFile } from './output.ts'
+import { wxRolldownRuntimeSource } from './rolldown-runtime-source.ts'
+
+const clientId = 'vite-plugin-taro-wx'
+
+/** HMR boundary shape returned by Vite's private WX DevEngine integration. */
+type WxDevEngineBoundary = {
+    boundary: string
+    acceptedVia: string
+}
+
+/** Update result shape returned by Vite's private bundled-development engine. */
+export type WxDevEngineUpdate =
+    | { type: 'Noop' }
+    | { type: 'FullReload'; reason?: string }
+    | {
+          type: 'Patch'
+          code: string
+          filename: string
+          hmrBoundaries: WxDevEngineBoundary[]
+      }
+
+type WxDevEngineInternal = {
+    registerModules(clientId: string, modules: string[]): void
+    ensureCurrentBuildFinish(): Promise<void>
+    ensureLatestBuildOutput(): Promise<unknown>
+    getBundleState(): Promise<{ lastBuildErrored: boolean }>
+    triggerFullBuild(): void
+}
+
+type WxRolldownOptions = {
+    output?: Record<string, unknown> | Array<Record<string, unknown>>
+    experimental?: {
+        devMode?: boolean | Record<string, unknown>
+        [key: string]: unknown
+    }
+    [key: string]: unknown
+}
+
+type WxDevEngineClient = {
+    send(payload: unknown): void
+}
+
+type ViteBundledDevInternal = {
+    _devEngine?: WxDevEngineInternal
+    clients: {
+        setupIfNeeded(client: WxDevEngineClient, clientId: string): void
+    }
+    getRolldownOptions(): Promise<WxRolldownOptions>
+    storeOutputFiles(output: WxOutputFile[]): void
+    handleHmrOutput(client: WxDevEngineClient, files: string[], output: WxDevEngineUpdate, info?: unknown): void
+    listen(): Promise<void>
+}
+
+type ViteBundledDevCallbacks = {
+    onOutput(output: WxOutputFile[]): void
+    onPatch(files: string[], output: WxDevEngineUpdate): boolean
+    onError(message: string): void
+    waitForInitialBundle(): Promise<void>
+}
+
+/** Isolates the private Vite bundled-development API used by the WX session. */
+export class ViteBundledDevAdapter {
+    private bundledDev: ViteBundledDevInternal | undefined
+
+    constructor(
+        private readonly config: ResolvedConfig,
+        private readonly server: ViteDevServer,
+        private readonly callbacks: ViteBundledDevCallbacks
+    ) {}
+
+    install(): void {
+        const bundledDev = this.server.environments.client.bundledDev as unknown as ViteBundledDevInternal | undefined
+        if (!bundledDev) throw new Error('vite-plugin-taro requires Vite bundled development for WX development.')
+        if (
+            typeof bundledDev.getRolldownOptions !== 'function' ||
+            typeof bundledDev.storeOutputFiles !== 'function' ||
+            typeof bundledDev.handleHmrOutput !== 'function'
+        ) {
+            throw new Error('vite-plugin-taro does not support this Vite bundled-development API shape.')
+        }
+        this.bundledDev = bundledDev
+        this.installOptions(bundledDev)
+        this.installOutput(bundledDev)
+        this.installPatches(bundledDev)
+        this.installListener(bundledDev)
+    }
+
+    registerBundleModules(output: WxOutputFile[]): number {
+        const moduleIds = new Set<string>()
+        for (const item of output) {
+            if (item.type !== 'chunk') continue
+            for (const id of Object.keys(item.modules ?? {})) moduleIds.add(toStableModuleId(id, this.config.root))
+        }
+        this.registerModules([...moduleIds])
+        return moduleIds.size
+    }
+
+    registerPatchModules(code: string): void {
+        const moduleIds = new Set<string>()
+        for (const match of code.matchAll(/create(?:Esm|Cjs)Initializer\("([^"]+)"/g)) moduleIds.add(match[1])
+        this.registerModules([...moduleIds])
+    }
+
+    private registerModules(moduleIds: string[]): void {
+        if (moduleIds.length) this.bundledDev?._devEngine?.registerModules(clientId, moduleIds)
+    }
+
+    async rebuild(): Promise<void> {
+        const engine = this.bundledDev?._devEngine
+        if (!engine) return
+        engine.triggerFullBuild()
+        await engine.ensureLatestBuildOutput()
+    }
+
+    private installOptions(bundledDev: ViteBundledDevInternal): void {
+        const getRolldownOptions = bundledDev.getRolldownOptions.bind(bundledDev)
+        bundledDev.getRolldownOptions = async () => {
+            const options = await getRolldownOptions()
+            if (!options.output) options.output = {}
+            const output = getFirstOutput(options)
+            const configuredOutput = this.config.build.rolldownOptions.output
+            const desiredOutput = Array.isArray(configuredOutput) ? configuredOutput[0] : configuredOutput
+            Object.assign(output, desiredOutput, {
+                format: 'cjs',
+                sourcemap: false,
+                minify: false,
+                banner: createWxDevelopmentBanner
+            })
+            options.experimental ??= {}
+            options.experimental.devMode = {
+                ...(typeof options.experimental.devMode === 'object' ? options.experimental.devMode : {}),
+                lazy: false,
+                // Rolldown compiles this source into runtime.js before any Taro/React module executes.
+                implement: wxRolldownRuntimeSource
+            }
+            return options
+        }
+    }
+
+    private installOutput(bundledDev: ViteBundledDevInternal): void {
+        const storeOutputFiles = bundledDev.storeOutputFiles.bind(bundledDev)
+        bundledDev.storeOutputFiles = (output) => {
+            storeOutputFiles(output)
+            this.callbacks.onOutput(output)
+        }
+    }
+
+    private installPatches(bundledDev: ViteBundledDevInternal): void {
+        const handleHmrOutput = bundledDev.handleHmrOutput.bind(bundledDev)
+        bundledDev.handleHmrOutput = (client, files, output, info) => {
+            if (output.type === 'Noop') return
+            if (this.callbacks.onPatch(files, output)) handleHmrOutput(client, files, output, info)
+        }
+    }
+
+    private installListener(bundledDev: ViteBundledDevInternal): void {
+        const listen = bundledDev.listen.bind(bundledDev)
+        bundledDev.listen = async () => {
+            await listen()
+            bundledDev.clients.setupIfNeeded({ send: (payload) => this.handlePayload(payload) }, clientId)
+            const engine = bundledDev._devEngine
+            if (!engine) throw new Error('vite-plugin-taro expected Vite to initialize the WX DevEngine.')
+            await engine.ensureCurrentBuildFinish()
+            if ((await engine.getBundleState()).lastBuildErrored) {
+                throw new Error('The initial WX bundled-development build failed.')
+            }
+            await this.callbacks.waitForInitialBundle()
+        }
+    }
+
+    private handlePayload(payload: unknown): void {
+        if (typeof payload !== 'object' || payload === null) return
+        const candidate = payload as { type?: unknown; err?: { message?: unknown } }
+        if (candidate.type === 'error' && typeof candidate.err?.message === 'string') {
+            this.callbacks.onError(candidate.err.message)
+        }
+    }
+}
+
+function toStableModuleId(id: string, root: string): string {
+    const normalizedId = id.replace(/\\/g, '/')
+    if (normalizedId.startsWith('\0') || !path.posix.isAbsolute(normalizedId)) return normalizedId
+    return path.posix.relative(root.replace(/\\/g, '/'), normalizedId)
+}
+
+function getFirstOutput(options: WxRolldownOptions): Record<string, unknown> {
+    if (!Array.isArray(options.output)) return options.output as Record<string, unknown>
+    const output = options.output[0] ?? {}
+    options.output[0] = output
+    return output
+}
+
+/** Adds native direct dependencies whose execution order cannot be represented through the Rolldown graph. */
+function createWxDevelopmentBanner(chunk: { fileName: string }): string {
+    if (chunk.fileName === 'app.js') return `require(${JSON.stringify(`./${wxUpdateControlFile}`)});`
+    if (!chunk.fileName.startsWith('pages/') || !chunk.fileName.endsWith('.js')) return ''
+    const prefix = '../'.repeat(chunk.fileName.split('/').length - 1)
+    return `require(${JSON.stringify(`${prefix}runtime.js`)});require(${JSON.stringify(`${prefix}${wxPagePreloadFile}`)});require(${JSON.stringify(`${prefix}${wxUpdateFile}`)});`
+}

package/src/node/targets/wx/development-files.ts

@@ -0,0 +1,11 @@
+/** Plugin-owned files added only to a WX development output. */
+export const wxDevelopmentDirectory = 'vpt-hmr'
+
+/** App-only metadata containing the local transport URL, token, and build ID. */
+export const wxUpdateControlFile = `${wxDevelopmentDirectory}/control.js`
+
+/** Stable page-component initialization required before replaying retained updates. */
+export const wxPagePreloadFile = `${wxDevelopmentDirectory}/preload.js`
+
+/** The one mutable, literal JavaScript update dependency required by every page. */
+export const wxUpdateFile = `${wxDevelopmentDirectory}/update.js`