Skip to content

A full-featured download manager.

14.5 KB
Raw Blame
import type { EventBus } from '@core/events/event-bus'
import type { CapabilityHost } from '@core/plugin/capabilities/interface'
import fastifyStatic from '@fastify/static'
import websocket from '@fastify/websocket'
import { BridgeCommands, BridgeQueries } from '@shared/protocol/bridge'
import { Commands } from '@shared/protocol/commands'
import {
  assertTaskInspectorActivityArguments,
  makeProtocolFailure,
  makeProtocolSuccess,
} from '@shared/protocol/errors'
import { Events } from '@shared/protocol/events'
import type {
  CommandHandlerMap,
  Handler,
  QueryHandlerMap,
} from '@shared/protocol/handler-types'
import { OPERATION_CHANNELS } from '@shared/protocol/operation-channels'
import { Queries } from '@shared/protocol/queries'
import { DirectoryPreferencesResultSchema } from '@shared/schemas/directory-preferences'
import { downloadsSettingsResultSchema } from '@shared/schemas/downloads-settings'
import { GeneralSettingsResultSchema } from '@shared/schemas/general-settings'
import {
  type ClientPairingCapabilities,
  clientPairingCapabilitiesSchema,
  WEB_ORIGIN_HEADER,
} from '@shared/schemas/operator-auth'
import {
  CreateServerDirectoryResultSchema,
  ListServerDirectoriesResultSchema,
  ListServerDirectoryLocationsResultSchema,
  ValidateServerDirectoryResultSchema,
  ValidateServerFileResultSchema,
} from '@shared/schemas/server-directory'
import { parseTaskInspectorActivitySnapshot } from '@shared/schemas/task-inspector-activity'
import { torrentRpcBodyLimitSchema } from '@shared/schemas/torrent-request-limits'
import Fastify, { type FastifyInstance, type FastifyReply } from 'fastify'
import type { RemoteExtensionConfig } from '../bridge/remote-extension-config'
import type { FnosGatewayOptions } from '../platform/fnos/identity'
import {
  registerTorrentCreator,
  type TorrentCreatorDeps,
} from '../routes/torrent-creator'
import { bindEventHeartbeat } from './event-heartbeat'
import { bindEventBroadcaster } from './events'
import {
  canDeliverExtensionPairingCode,
  canDeliverGatewayExtensionPairingCode,
  filterExtensionPairingSnapshot,
  isExtensionPairingCodeEvent,
} from './extension-pairing-delivery'
import { registerFnosAuth } from './fnos-auth'
import { type NasGatewayOptions, registerNasAuth } from './nas-auth'
import { type OperatorAuthOptions, registerOperatorAuth } from './operator-auth'
import { ServiceUnavailableError } from './service-unavailable-error'
import {
  type CommandRequest,
  RPC_BODY_LIMIT_BYTES,
  registerTorrentCommandRoutes,
} from './torrent-command-routes'
import { createWebBasePath } from './web-base-path'

export { RPC_BODY_LIMIT_BYTES } from './torrent-command-routes'

const directoryResultSchemas = {
  [Commands.SaveDownloadsSettings]: downloadsSettingsResultSchema,
  [Queries.GetDownloadsSettingsDraft]: downloadsSettingsResultSchema,
  [Commands.MutateDirectoryPreferences]: DirectoryPreferencesResultSchema,
  [Commands.SaveGeneralSettings]: GeneralSettingsResultSchema,
  [Queries.GetGeneralSettingsDraft]: GeneralSettingsResultSchema,
  [Queries.GetDirectoryPreferences]: DirectoryPreferencesResultSchema,
  [Queries.ListServerDirectoryLocations]:
    ListServerDirectoryLocationsResultSchema,
  [Commands.CreateServerDirectory]: CreateServerDirectoryResultSchema,
  [Queries.ListServerDirectories]: ListServerDirectoriesResultSchema,
  [Queries.ValidateServerFile]: ValidateServerFileResultSchema,
  [Queries.ValidateServerDirectory]: ValidateServerDirectoryResultSchema,
}

function sendRpcValue(reply: FastifyReply, value: unknown) {
  // Fastify sends strings as plain text and undefined without a JSON body.
  // Every renderer RPC response must be consumable with Response.json().
  return reply.type('application/json').send(JSON.stringify(value ?? null))
}

async function directoryRpc(
  channel: string,
  body: unknown,
  handler: Handler
): Promise<unknown> {
  const schema =
    directoryResultSchemas[channel as keyof typeof directoryResultSchemas]
  const args =
    typeof body === 'object' && body !== null && 'args' in body
      ? body.args
      : undefined
  if (
    !Array.isArray(args) ||
    args.length !== 1 ||
    Object.keys(body as object).some((key) => key !== 'args')
  ) {
    return { ok: false, error: { code: 'invalidPath' } }
  }
  try {
    return schema.parse(await handler(args[0]))
  } catch {
    return {
      ok: false,
      error: {
        code:
          channel === Commands.CreateServerDirectory
            ? 'creationOutcomeUnknown'
            : 'unavailable',
      },
    }
  }
}

export interface AppOptions {
  torrentCreator?: TorrentCreatorDeps
  /** Supported pairing surfaces, independent of the user's enable switch. */
  clientPairing?: ClientPairingCapabilities
  basePath?: string
  fnosGateway?: FnosGatewayOptions
  nasGateway?: NasGatewayOptions
  /** Torrent-only RPC budget; defaults to 8 MiB, configurable from 2 to 64 MiB. */
  torrentBodyLimitBytes?: number
  commandHandlers?: CommandHandlerMap
  queryHandlers?: QueryHandlerMap
  /**
   * When set, gates the control plane (`/rpc/*`, `/api/*`, `/rpc/events`) on the
   * machine-owner operator token (Spec 9). Omitting it leaves the app open —
   * only for unit tests / embedding; the server entry ALWAYS provides it.
   */
  operatorAuth?: OperatorAuthOptions
  /**
   * `bridge:*` command/query handlers (Spec 7b). Kept separate from the generic
   * Command/Query maps because bridge channels have their own prefix + types.
   * The route falls back to these. Passed by reference so the server can
   * populate them AFTER the (non-fatal, later-bootstrapped) bridge comes up.
   */
  bridgeCommandHandlers?: Record<string, Handler>
  bridgeQueryHandlers?: Record<string, Handler>
  remoteExtensionConfig?: RemoteExtensionConfig
  eventBus?: EventBus
  getHiddenNotificationKinds?: () => readonly string[]
  pluginLogSource?: Pick<CapabilityHost, 'subscribeLog'>
  rendererDir?: string
  healthCheck?: () => { ok: boolean } | Promise<{ ok: boolean }>
}

export async function createApp(
  opts: AppOptions = {}
): Promise<FastifyInstance> {
  if (
    [opts.fnosGateway, opts.nasGateway, opts.operatorAuth].filter(Boolean)
      .length > 1
  )
    throw new Error('Authentication modes are mutually exclusive')
  const clientPairing =
    opts.clientPairing === undefined
      ? undefined
      : clientPairingCapabilitiesSchema.parse(opts.clientPairing)
  const webPath = createWebBasePath(opts.basePath)
  const app = Fastify({
    logger: false,
    bodyLimit: RPC_BODY_LIMIT_BYTES,
    requestTimeout: 120_000,
    rewriteUrl: webPath.rewriteUrl,
  })
  webPath.register(app)
  // Register the deny-by-default operator gate FIRST so its onRequest hook runs
  // before every route (including /api/* added by the caller post-createApp and
  // the /rpc/events WS upgrade).
  const nasGateway = opts.nasGateway ?? opts.fnosGateway
  const operatorSessions = opts.nasGateway
    ? registerNasAuth(app, opts.nasGateway, clientPairing)
    : opts.fnosGateway
      ? registerFnosAuth(app, opts.fnosGateway, clientPairing)
      : opts.operatorAuth
        ? registerOperatorAuth(app, {
            ...opts.operatorAuth,
            clientPairing: clientPairing ?? opts.operatorAuth.clientPairing,
          })
        : undefined
  if (!operatorSessions) {
    app.get('/rpc/auth/status', async () => ({
      authed: true,
      mode: 'unrestricted',
      canLogout: false,
      ...(clientPairing ? { clientPairing } : {}),
    }))
  }
  if (opts.torrentCreator)
    registerTorrentCreator(app, opts.torrentCreator, (req) =>
      operatorSessions?.principal(req)
    )
  const commands = opts.commandHandlers ?? {}
  const queries = opts.queryHandlers ?? {}
  const bridgeCommands = opts.bridgeCommandHandlers ?? {}
  const bridgeQueries = opts.bridgeQueryHandlers ?? {}

  app.get('/healthz', async (_request, reply) => {
    const health = opts.healthCheck ? await opts.healthCheck() : { ok: true }
    return reply.code(health.ok ? 200 : 503).send(health)
  })

  const dispatchCommand = async (
    channel: string,
    req: CommandRequest,
    reply: FastifyReply
  ) => {
    const handler =
      commands[channel as keyof typeof commands] ?? bridgeCommands[channel]
    if (!handler) return reply.code(404).send({ error: 'unknown channel' })
    if (channel === BridgeCommands.ClaimExtensionPair) {
      reply.header('cache-control', 'no-store')
      const principal = operatorSessions?.principal(req)
      if (
        !(
          principal &&
          (nasGateway
            ? canDeliverGatewayExtensionPairingCode(
                opts.remoteExtensionConfig,
                req.headers[WEB_ORIGIN_HEADER]
              )
            : canDeliverExtensionPairingCode(
                opts.remoteExtensionConfig,
                req,
                principal.id.startsWith('bearer:')
              ))
        )
      )
        return reply
          .code(403)
          .send({ error: 'Pairing code delivery unavailable' })
    }

    if (
      channel === Commands.CreateServerDirectory ||
      channel === Commands.MutateDirectoryPreferences ||
      channel === Commands.SaveGeneralSettings ||
      channel === Commands.SaveDownloadsSettings
    ) {
      return directoryRpc(channel, req.body, handler)
    }
    try {
      if (OPERATION_CHANNELS.has(channel)) {
        const owner = operatorSessions?.principal(req)
        if (!owner) return reply.code(401).send({ error: 'unauthorized' })
        return sendRpcValue(reply, await handler(owner, req.body?.args?.[0]))
      }
      return sendRpcValue(reply, await handler(...(req.body?.args ?? [])))
    } catch (err) {
      req.log.error({ err }, 'command handler failed')
      return reply
        .code(err instanceof ServiceUnavailableError ? 503 : 500)
        .send({ error: (err as Error).message })
    }
  }

  await registerTorrentCommandRoutes(
    app,
    dispatchCommand,
    torrentRpcBodyLimitSchema.parse(opts.torrentBodyLimitBytes)
  )
  app.post<{ Params: { channel: string }; Body: { args?: unknown[] } }>(
    '/rpc/command/:channel',
    (req, reply) => dispatchCommand(req.params.channel, req, reply)
  )

  app.post<{ Params: { channel: string }; Body: { args?: unknown[] } }>(
    '/rpc/query/:channel',
    async (req, reply) => {
      const usesSharedEnvelope =
        req.params.channel === Queries.GetTaskInspectorActivity
      // An installation without a pairing surface has no pending requests.
      // Once configured, NAS hosts use the ordinary operator-gated inbox.
      if (
        nasGateway &&
        !clientPairing?.cli &&
        !clientPairing?.extension &&
        req.params.channel === BridgeQueries.ListPendingPairRequests
      )
        return []
      const handler =
        queries[req.params.channel as keyof typeof queries] ??
        bridgeQueries[req.params.channel]
      if (!handler) return reply.code(404).send({ error: 'unknown channel' })
      if (
        req.params.channel === Queries.ListServerDirectories ||
        req.params.channel === Queries.ValidateServerDirectory ||
        req.params.channel === Queries.ValidateServerFile ||
        req.params.channel === Queries.GetDirectoryPreferences ||
        req.params.channel === Queries.GetGeneralSettingsDraft ||
        req.params.channel === Queries.GetDownloadsSettingsDraft ||
        req.params.channel === Queries.ListServerDirectoryLocations
      ) {
        return directoryRpc(req.params.channel, req.body, handler)
      }
      try {
        const args = req.body?.args
        if (usesSharedEnvelope) {
          assertTaskInspectorActivityArguments(args)
        }
        const value = await handler(...(args ?? []))
        if (
          req.params.channel === BridgeQueries.ListPendingPairRequests &&
          !(
            operatorSessions?.principal(req) &&
            canDeliverExtensionPairingCode(
              opts.remoteExtensionConfig,
              req,
              operatorSessions?.principal(req)?.id.startsWith('bearer:') ===
                true
            )
          )
        ) {
          return filterExtensionPairingSnapshot(value)
        }
        if (!usesSharedEnvelope) return sendRpcValue(reply, value)
        const snapshot = parseTaskInspectorActivitySnapshot(value)
        if (!snapshot) {
          throw new Error('Invalid Task Inspector Activity snapshot')
        }
        return makeProtocolSuccess(snapshot)
      } catch (err) {
        req.log.error({ err }, 'query handler failed')
        if (usesSharedEnvelope) {
          return reply.code(200).send(makeProtocolFailure(err))
        }
        return reply
          .code(err instanceof ServiceUnavailableError ? 503 : 500)
          .send({ error: (err as Error).message })
      }
    }
  )

  if (opts.eventBus) {
    const broadcaster = bindEventBroadcaster(
      opts.eventBus,
      opts.getHiddenNotificationKinds
    )
    const unsubscribePluginLogs = opts.pluginLogSource?.subscribeLog(
      (pluginId, entry) => {
        broadcaster.broadcast(`${Events.PluginLog}:${pluginId}`, [entry])
      }
    )
    if (unsubscribePluginLogs) {
      app.addHook('onClose', async () => unsubscribePluginLogs())
    }
    await app.register(websocket)
    app.get('/rpc/events', { websocket: true }, (socket, request) => {
      const session = operatorSessions?.bindSocket(request, socket)
      const allowPairingCode =
        operatorSessions?.principal(request) !== undefined &&
        canDeliverExtensionPairingCode(
          opts.remoteExtensionConfig,
          request,
          operatorSessions?.principal(request)?.id.startsWith('bearer:') ===
            true
        )
      broadcaster.register(
        socket,
        session?.eligible,
        (channel, args) =>
          allowPairingCode || !isExtensionPairingCodeEvent(channel, args)
      )
      const stopHeartbeat = bindEventHeartbeat(socket)
      const cleanup = () => {
        stopHeartbeat()
        broadcaster.unregister(socket)
        session?.dispose()
      }
      socket.on('close', cleanup)
      socket.on('error', cleanup)
    })
  }

  if (opts.rendererDir) {
    await app.register(fastifyStatic, {
      root: opts.rendererDir,
      prefix: '/',
      wildcard: false,
    })
    // SPA fallback: return index.html for any GET that isn't /rpc/* or /healthz.
    app.setNotFoundHandler(async (req, reply) => {
      const isGet = req.method === 'GET'
      const isRpc = req.url.startsWith('/rpc/')
      const isHealth = req.url === '/healthz'
      const isApi = req.url.startsWith('/api/')
      if (
        isGet &&
        !isRpc &&
        !isApi &&
        !isHealth &&
        (!webPath.basePath || req.url.split('?')[0] === '/')
      ) {
        return reply.sendFile('index.html')
      }
      return reply.code(404).send({ error: 'not found' })
    })
  }

  return app
}