@lincyaw/addon-exec-jupyter 0.0.0-stage → 1.0.0-rc.2

package/src/shared/kernel-lifecycle.ts

@@ -0,0 +1,154 @@
+import type { Kernel, ServerConnection } from '@jupyterlab/services'
+import { RUNS_DIR } from '../domain/config.ts'
+import { loadJupyterServices } from './load-services.ts'
+import { responseStatus } from './refusal.ts'
+
+const CONNECT_TIMEOUT_MS = 30_000
+
+export interface JupyterKernelHandle {
+  id: string
+  dir: string
+  connection: Kernel.IKernelConnection
+}
+
+export type ShutdownJupyterKernel = (kernel: string, directory: string, settings: ServerConnection.ISettings) => Promise<void>
+
+export interface JupyterKernelLifecycle {
+  readonly disposed: boolean
+  start(settings: ServerConnection.ISettings): Promise<JupyterKernelHandle>
+  shutdown(handle: JupyterKernelHandle): Promise<void>
+  dispose(): Promise<void>
+}
+
+function randomId(): string {
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`
+}
+
+/**
+ * Starts kernels, each with its own directory under presmium-runs/, and shuts them down with their directory.
+ * Disposing shuts down every kernel, those still starting too; `shutdown` can hand the shutdown to another party.
+ */
+export function createJupyterKernelLifecycle(options: { kernelName: string, shutdown?: ShutdownJupyterKernel }): JupyterKernelLifecycle {
+  const live = new Set<JupyterKernelHandle>()
+  const starting = new Set<Promise<JupyterKernelHandle>>()
+  const shuttingDown = new Map<JupyterKernelHandle, Promise<void>>()
+  let disposed = false
+  let disposing: Promise<void> | undefined
+
+  const start = (settings: ServerConnection.ISettings): Promise<JupyterKernelHandle> => {
+    if (disposed) return Promise.reject(new Error('the Jupyter environment has been disposed'))
+    const task = (async () => {
+      const { Drive, KernelAPI, KernelConnection } = await loadJupyterServices()
+      const dir = `${RUNS_DIR}/${randomId()}`
+      const drive = new Drive({ serverSettings: settings })
+      let handle: JupyterKernelHandle | undefined
+      await drive.save(RUNS_DIR, { type: 'directory' })
+      try {
+        await drive.save(dir, { type: 'directory' })
+        const model = await KernelAPI.startNew({ name: options.kernelName, path: `${dir}/kernel` } as { name: string }, settings)
+        const connection = new KernelConnection({ model, serverSettings: settings, handleComms: false })
+        handle = { id: model.id, dir, connection }
+        live.add(handle)
+        if (disposed) throw new Error('the Jupyter environment has been disposed')
+        await connected(connection)
+        if (disposed) throw new Error('the Jupyter environment has been disposed')
+        return handle
+      } catch (error) {
+        await (handle ? shutdown(handle) : removeDirectory(settings, dir)).catch(() => {})
+        throw error
+      }
+    })()
+    starting.add(task)
+    void task.then(() => starting.delete(task), () => starting.delete(task))
+    return task
+  }
+
+  const shutdown = (handle: JupyterKernelHandle): Promise<void> => {
+    const known = shuttingDown.get(handle)
+    if (known) return known
+    // Invoke the handoff before yielding: pagehide cannot wait for later continuations.
+    const cleanup = (options.shutdown ?? shutdownJupyterKernel)(handle.id, handle.dir, handle.connection.serverSettings)
+    handle.connection.dispose()
+    const task = cleanup.finally(() => {
+      live.delete(handle)
+      shuttingDown.delete(handle)
+    })
+    shuttingDown.set(handle, task)
+    return task
+  }
+
+  return {
+    get disposed() {
+      return disposed
+    },
+    start,
+    shutdown,
+    dispose() {
+      if (disposing) return disposing
+      disposed = true
+      // Start all known shutdowns synchronously, including keepalive handoffs.
+      const cleanup = [...live].map(handle => shutdown(handle))
+      const pending = [...starting]
+      disposing = (async () => {
+        const results = await Promise.allSettled(cleanup)
+        await Promise.allSettled(pending)
+        const failed = results.find(result => result.status === 'rejected')
+        if (failed?.status === 'rejected') throw failed.reason
+      })()
+      return disposing
+    },
+  }
+}
+
+/** Shuts the kernel down and deletes its directory. */
+export async function shutdownJupyterKernel(kernel: string, directory: string, settings: ServerConnection.ISettings): Promise<void> {
+  const { ServerConnection } = await loadJupyterServices()
+  const response = await ServerConnection.makeRequest(`${settings.baseUrl}api/kernels/${encodeURIComponent(kernel)}`, { method: 'DELETE', keepalive: true }, settings)
+  if (response.status !== 204 && response.status !== 404) throw await ServerConnection.ResponseError.create(response)
+  await removeDirectory(settings, directory)
+}
+
+async function removeDirectory(settings: ServerConnection.ISettings, path: string): Promise<void> {
+  const { Drive } = await loadJupyterServices()
+  const drive = new Drive({ serverSettings: settings })
+  const remove = async (dir: string): Promise<void> => {
+    const model = await drive.get(dir, { content: true })
+    for (const item of Array.isArray(model.content) ? model.content as { path: string, type: string }[] : []) {
+      if (item.type === 'directory') await remove(item.path)
+      else await drive.delete(item.path)
+    }
+    await drive.delete(dir)
+  }
+  try {
+    await remove(path)
+  } catch (error) {
+    if (responseStatus(error) !== 404) throw error
+  } finally {
+    drive.dispose()
+  }
+}
+
+/** Why a connection to Jupyter failed, as a code a reader's text is chosen by (the message is for logs). */
+export type JupyterFailure = 'jupyter-no-answer' | 'jupyter-closed'
+const failure = (code: JupyterFailure, message: string) => Object.assign(new Error(message), { code })
+export const failureCode = (error: unknown): JupyterFailure | undefined => {
+  const code = (error as { code?: unknown } | undefined)?.code
+  return code === 'jupyter-no-answer' || code === 'jupyter-closed' ? code : undefined
+}
+
+function connected(connection: Kernel.IKernelConnection): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => done(failure('jupyter-no-answer', `no answer from the kernel within ${CONNECT_TIMEOUT_MS / 1000} s`)), CONNECT_TIMEOUT_MS)
+    const watch = (_: unknown, status: string) => {
+      if (status === 'disconnected') done(failure('jupyter-closed', 'the kernel\'s WebSocket closed'))
+    }
+    const done = (error?: Error) => {
+      clearTimeout(timer)
+      connection.connectionStatusChanged.disconnect(watch)
+      if (error) reject(error)
+      else resolve()
+    }
+    connection.connectionStatusChanged.connect(watch)
+    connection.info.then(() => done(), (error: unknown) => done(error instanceof Error ? error : new Error(String(error))))
+  })
+}

package/src/shared/kernels.ts

@@ -0,0 +1,234 @@
+import { errorMessage, failedRun, languageId } from '@lincyaw/kernel'
+import type { RunRequest, RunResult } from '@lincyaw/kernel'
+import type { ServerConnection } from '@jupyterlab/services'
+import { argsPrelude } from '../domain/args.ts'
+import { DEFAULT_TIMEOUT_MS } from '../domain/config.ts'
+import { OutputCollector } from '../domain/outputs.ts'
+import { executeCode, writeRunFiles } from './execute.ts'
+import { createJupyterKernelLifecycle, failureCode } from './kernel-lifecycle.ts'
+import type { JupyterFailure, JupyterKernelHandle, ShutdownJupyterKernel } from './kernel-lifecycle.ts'
+import { loadJupyterServices } from './load-services.ts'
+import { isRefused } from './refusal.ts'
+
+export interface JupyterKernelsText {
+  /** `error` is the failure's own words, for logs; `code` is set when the failure is one the reader's text names. */
+  unreachable(error: string, code?: JupyterFailure): string
+  refused: string
+  noKernel(kernel: string, known: string[]): string
+  wrongLanguage(kernel: string, language: string, lang: string): string
+  timedOut(seconds: number): string
+}
+
+export interface JupyterKernelsOptions {
+  executorId: string
+  kernelName: string
+  languages?: string[]
+  settings(): Promise<ServerConnection.ISettings>
+  shutdown?: ShutdownJupyterKernel
+  cleanupFailed?(error: unknown): void
+  refused?(): void
+  text: JupyterKernelsText
+}
+
+export interface JupyterKernelDescription {
+  spec: unknown
+  implementation: string
+  implementationVersion: string
+  language: string
+  languageVersion: string
+}
+
+export interface JupyterKernels {
+  supports(lang: string): boolean
+  run(request: RunRequest, signal?: AbortSignal): Promise<RunResult>
+  endSession(session: string): Promise<void>
+  describe(): Promise<JupyterKernelDescription>
+  probe(): Promise<string | undefined>
+  dispose(): Promise<void>
+}
+
+interface RunSession {
+  kernel?: Promise<JupyterKernelHandle>
+  tail: Promise<unknown>
+}
+
+/** The kernels of a Jupyter environment: one per session, kept until the session ends, and one for each run outside a session. */
+export function createJupyterKernels(options: JupyterKernelsOptions): JupyterKernels {
+  const runSessions = new Map<string, RunSession>()
+  const lifecycle = createJupyterKernelLifecycle({ kernelName: options.kernelName, shutdown: options.shutdown })
+  let specs: Promise<{ language: string, names: string[] }> | undefined
+
+  const failedWith = (reason: string, started = Date.now()) => failedRun(options.executorId, reason, Date.now() - started)
+
+  /** A request to Jupyter failed: the credentials were refused, or the server cannot be reached. */
+  const failedRequest = (error: unknown, started: number): RunResult => {
+    if (isRefused(error)) {
+      options.refused?.()
+      return failedWith(options.text.refused, started)
+    }
+    return failedWith(options.text.unreachable(errorMessage(error), failureCode(error)), started)
+  }
+
+  /** The connection's settings, or the failed run when there are none (no address, refused credentials). */
+  const settingsOrFailedRun = async (): Promise<ServerConnection.ISettings | RunResult> => {
+    try {
+      return await options.settings()
+    } catch (error) {
+      if (isRefused(error)) {
+        options.refused?.()
+        return failedWith(options.text.refused)
+      }
+      return failedWith(errorMessage(error))
+    }
+  }
+
+  const kernelSpecs = async (settings: ServerConnection.ISettings) => {
+    specs ??= loadJupyterServices().then(s => s.KernelSpecAPI.getSpecs(settings)).then(models => ({
+      language: models.kernelspecs[options.kernelName]?.language ?? '',
+      names: Object.keys(models.kernelspecs),
+    }))
+    try {
+      return await specs
+    } catch (error) {
+      specs = undefined
+      throw error
+    }
+  }
+
+  const runIn = async (kernel: () => Promise<JupyterKernelHandle>, request: RunRequest, signal: AbortSignal | undefined, settings: ServerConnection.ISettings, started: number): Promise<RunResult> => {
+    let handle: JupyterKernelHandle
+    try {
+      signal?.throwIfAborted()
+      if (!options.languages) {
+        const { language, names } = await kernelSpecs(settings)
+        if (!names.includes(options.kernelName)) return failedWith(options.text.noKernel(options.kernelName, names), started)
+        if (language && languageId(language) !== languageId(request.lang)) return failedWith(options.text.wrongLanguage(options.kernelName, language, request.lang), started)
+      }
+      signal?.throwIfAborted()
+      handle = await kernel()
+      signal?.throwIfAborted()
+      if (request.files && Object.keys(request.files).length) await writeRunFiles(handle, settings, request.files)
+    } catch (error) {
+      if (signal?.aborted) return failedWith(errorMessage(signal.reason), started)
+      return failedRequest(error, started)
+    }
+    const timeoutMs = request.timeoutMs && request.timeoutMs > 0 ? request.timeoutMs : DEFAULT_TIMEOUT_MS
+    const prelude = argsPrelude(request.args, request.lang)
+    const collector = new OutputCollector()
+    const shutdown = () => lifecycle.shutdown(handle)
+    let status: string
+    let timedOut = false
+    try {
+      if (prelude) await executeCode(handle, prelude, { stdin: '', timeoutMs, signal, shutdown })
+      const outcome = await executeCode(handle, request.code, { stdin: request.stdin ?? '', collector, timeoutMs, signal, shutdown })
+      status = outcome.status
+      timedOut = outcome.timedOut
+    } catch (error) {
+      if (signal?.aborted) return failedWith(errorMessage(signal.reason), started)
+      return failedRequest(error, started)
+    }
+    const { stdout, stderr } = collector.text()
+    return {
+      ok: status === 'ok' && !timedOut,
+      stdout,
+      stderr: timedOut ? `${stderr}${options.text.timedOut(timeoutMs / 1000)}\n` : stderr,
+      exitCode: timedOut ? null : status === 'ok' ? 0 : 1,
+      durationMs: Date.now() - started,
+      timedOut,
+      source: 'live',
+      executorId: options.executorId,
+      outputs: collector.outputs,
+    }
+  }
+
+  const sessionKernel = (runSession: RunSession, settings: ServerConnection.ISettings) => async (): Promise<JupyterKernelHandle> => {
+    const known = runSession.kernel ? await runSession.kernel.catch(() => undefined) : undefined
+    if (known && !known.connection.isDisposed && known.connection.status !== 'dead') return known
+    runSession.kernel = lifecycle.start(settings)
+    runSession.kernel.catch(() => {
+      runSession.kernel = undefined
+    })
+    return runSession.kernel
+  }
+
+  const runOnce = async (request: RunRequest, signal?: AbortSignal): Promise<RunResult> => {
+    const started = Date.now()
+    const settings = await settingsOrFailedRun()
+    if (!('baseUrl' in settings)) return settings
+    let handle: JupyterKernelHandle | undefined
+    try {
+      return await runIn(async () => (handle = await lifecycle.start(settings)), request, signal, settings, started)
+    } finally {
+      if (handle) await lifecycle.shutdown(handle).catch((error) => {
+        if (options.cleanupFailed) options.cleanupFailed(error)
+        else console.warn('[presmium] Jupyter cleanup failed', error)
+      })
+    }
+  }
+
+  return {
+    supports: lang => !options.languages || options.languages.some(l => languageId(l) === languageId(lang)),
+    run(request, signal) {
+      if (signal?.aborted) return Promise.resolve(failedWith(errorMessage(signal.reason)))
+      if (lifecycle.disposed) return Promise.resolve(failedWith('the Jupyter environment has been disposed'))
+      if (!request.session) return runOnce(request, signal)
+      let runSession = runSessions.get(request.session)
+      if (!runSession) {
+        runSession = { tail: Promise.resolve() }
+        runSessions.set(request.session, runSession)
+      }
+      const own = runSession
+      const result = own.tail.then(async () => {
+        const started = Date.now()
+        const settings = await settingsOrFailedRun()
+        if (!('baseUrl' in settings)) return settings
+        return runIn(sessionKernel(own, settings), request, signal, settings, started)
+      })
+      own.tail = result.catch(() => undefined)
+      return result
+    },
+    async endSession(session) {
+      const known = runSessions.get(session)
+      if (!known) return
+      runSessions.delete(session)
+      await known.tail
+      const handle = await known.kernel?.catch(() => undefined)
+      if (handle) await lifecycle.shutdown(handle)
+    },
+    async describe() {
+      const settings = await options.settings()
+      const { ServerConnection } = await loadJupyterServices()
+      const response = await ServerConnection.makeRequest(`${settings.baseUrl}api/kernelspecs/${encodeURIComponent(options.kernelName)}`, {}, settings)
+      if (!response.ok) throw await ServerConnection.ResponseError.create(response)
+      const spec: unknown = await response.json()
+      const handle = await lifecycle.start(settings)
+      try {
+        const info = await handle.connection.info
+        return {
+          spec,
+          implementation: info.implementation,
+          implementationVersion: info.implementation_version,
+          language: info.language_info.name,
+          languageVersion: info.language_info.version,
+        }
+      } finally {
+        await lifecycle.shutdown(handle)
+      }
+    },
+    async probe() {
+      try {
+        const settings = await options.settings()
+        const { names } = await kernelSpecs(settings)
+        return names.includes(options.kernelName) ? undefined : options.text.noKernel(options.kernelName, names)
+      } catch (error) {
+        specs = undefined
+        return isRefused(error) ? options.text.refused : options.text.unreachable(errorMessage(error), failureCode(error))
+      }
+    },
+    dispose() {
+      const disposing = lifecycle.dispose()
+      runSessions.clear()
+      return disposing
+    },
+  }
+}

package/src/shared/load-services.ts

@@ -0,0 +1,9 @@
+type JupyterServices = typeof import('@jupyterlab/services')
+
+let loaded: Promise<JupyterServices> | undefined
+
+/** `@jupyterlab/services`, loaded at its first use. */
+export function loadJupyterServices(): Promise<JupyterServices> {
+  loaded ??= import('@jupyterlab/services')
+  return loaded
+}

package/src/shared/refusal.ts

@@ -0,0 +1,11 @@
+/** The HTTP status of a failed request to Jupyter, when the error carries the response. */
+export function responseStatus(error: unknown): number | undefined {
+  const response = (error as { response?: { status?: unknown } } | undefined)?.response
+  return typeof response?.status === 'number' ? response.status : undefined
+}
+
+/** Whether Jupyter refused the credentials (401 or 403). */
+export function isRefused(error: unknown): boolean {
+  const status = responseStatus(error)
+  return status === 401 || status === 403
+}

package/src/shared/terminals.ts

@@ -0,0 +1,74 @@
+import type { ServerConnection, Terminal } from '@jupyterlab/services'
+import type { TerminalEvents, TerminalSession } from '../domain/terminal-service.ts'
+import { loadJupyterServices } from './load-services.ts'
+
+export async function openTerminal(settings: ServerConnection.ISettings, events: TerminalEvents): Promise<TerminalSession> {
+  const { ServerConnection, TerminalManager } = await loadJupyterServices()
+  const url = `${settings.baseUrl}api/terminals`
+  const client: Terminal.ITerminalAPIClient = {
+    serverSettings: settings,
+    isAvailable: true,
+    async startNew() {
+      const response = await ServerConnection.makeRequest(url, { method: 'POST', body: '{}' }, settings)
+      if (response.status !== 200) throw await ServerConnection.ResponseError.create(response)
+      return await response.json() as Terminal.IModel
+    },
+    async listRunning() {
+      const response = await ServerConnection.makeRequest(url, {}, settings)
+      if (response.status !== 200) throw await ServerConnection.ResponseError.create(response)
+      return await response.json() as Terminal.IModel[]
+    },
+    async shutdown(name) {
+      const response = await ServerConnection.makeRequest(`${url}/${encodeURIComponent(name)}`, { method: 'DELETE' }, settings)
+      if (response.status !== 204 && response.status !== 404) throw await ServerConnection.ResponseError.create(response)
+    },
+  }
+  const manager = new TerminalManager({ serverSettings: settings, terminalAPIClient: client, standby: 'when-hidden' })
+  // The terminal request owns startup errors; readiness may reject during disposal.
+  void manager.ready.catch(() => {})
+  let connection: Awaited<ReturnType<typeof manager.startNew>>
+  try {
+    connection = await manager.startNew()
+  } catch (error) {
+    manager.dispose()
+    throw error
+  }
+  let closed = false
+  let dimensions: [number, number] | undefined
+  const resize = () => {
+    if (!closed && dimensions && connection.connectionStatus === 'connected') connection.send({ type: 'set_size', content: dimensions })
+  }
+  connection.connectionStatusChanged.connect(resize)
+  // The terminal can dispose itself before emitting its final disconnect message.
+  connection.disposed.connect(() => {
+    if (closed) return
+    closed = true
+    manager.dispose()
+    events.closed()
+  })
+  connection.messageReceived.connect((_, message) => {
+    if (message.type === 'stdout' && typeof message.content?.[0] === 'string') events.output(message.content[0])
+  })
+  return {
+    send: data => {
+      if (!closed) connection.send({ type: 'stdin', content: [data] })
+    },
+    resize: (rows, columns) => {
+      dimensions = [rows, columns]
+      resize()
+    },
+    async close() {
+      closed = true
+      try {
+        await connection.shutdown()
+      } catch {
+      }
+      manager.dispose()
+    },
+    abandon() {
+      closed = true
+      void ServerConnection.makeRequest(`${url}/${encodeURIComponent(connection.name)}`, { method: 'DELETE', keepalive: true }, settings).catch(() => {})
+      manager.dispose()
+    },
+  }
+}

package/vite.config.ts

@@ -0,0 +1,4 @@
+import { jupyterWsShim } from './src/node/vite.ts'
+
+// The viewer app's build: `@jupyterlab/services` imports `ws`, which gets the package's own shim.
+export default { plugins: [jupyterWsShim()] }