devpush 0.0.0-stage → 1.0.0-beta.4

package/src/plugins/contract.ts

@@ -0,0 +1,188 @@
+import type { WorkspaceOperation, WorkspaceActor } from './operations'
+
+export interface DeploymentServer {
+  id: string
+  teamId: string
+  teamSlug: string
+  teamStatus: string
+  handle: string
+  status: string
+  publicAddress: string | null
+  publicIpv4: string | null
+  publicIpv6: string | null
+  agentCapabilities?: string[] | null
+}
+
+export type GeneratedHostnameInput = {
+  server: DeploymentServer
+  projectName: string
+} & (
+  | { kind: 'project' }
+  | { kind: 'environment'; environmentSlug: string }
+  | { kind: 'branch'; branch: string }
+  | { kind: 'deployment'; deploymentId: string }
+)
+
+export interface GeneratedHostname {
+  hostname: string
+  https: boolean
+}
+
+export type CertificateResult =
+  | { status: 'configuration'; dnsNames: string[] }
+  | { status: 'pending'; retryAfter: number }
+  | { status: 'ready'; certificatePem: string; expiresAt: string }
+
+interface DeploymentWorkspace {
+  createdAt: number
+  personalOwnerId?: string | null
+  image?: string | null
+  color?: string
+  id: string
+  slug: string
+  name: string
+  status: string
+  serverCount: number
+  /** Latest server creation/deletion timestamp, independent of heartbeats. */
+  serverCountChangedAt?: number
+  memberCount: number
+}
+
+export type { WorkspaceOperation, WorkspaceActor } from './operations'
+
+export interface PreparedNotification {
+  from: string
+  to: string
+  subject: string
+  text: string
+  html: string
+}
+
+export interface PluginContext {
+  defer?: (work: () => Promise<unknown>) => void
+  /** Render once before persisting a retryable transactional notification. */
+  prepareNotification?: (input: {
+    userId: string
+    subject: string
+    message: string
+    action?: { label: string; url: string }
+  }) => Promise<PreparedNotification | null>
+  /** Generic transactional delivery: recipient policy belongs to the caller. */
+  notifyUser?: (input: {
+    userId: string
+    subject: string
+    message: string
+    action?: { label: string; url: string }
+    idempotencyKey: string
+    prepared?: PreparedNotification
+  }) => Promise<boolean>
+  listWorkspaceOwners?: (teamId: string) => Promise<string[]>
+  readWorkspace?: (teamId: string) => Promise<DeploymentWorkspace | null>
+  authorizeWorkspace?: (
+    userId: string,
+    teamSlug: string,
+  ) => Promise<{ id: string; slug: string; name: string; role: string } | null>
+  hasServerRouting: (serverId: string) => Promise<boolean>
+  readServer: (serverId: string) => Promise<DeploymentServer | null>
+  listServers: (input: {
+    afterId?: string
+    limit: number
+  }) => Promise<DeploymentServer[]>
+}
+
+export interface RuntimeLogLimits {
+  bytesPerMinute: number
+  bytesPerDay: number
+  rowsPerDay: number
+}
+
+export interface PluginServices {
+  /** Optional installation policy; core authenticates and scopes logs before applying it. */
+  runtimeLogLimits?: (teamId: string) => RuntimeLogLimits
+
+  workspaceAccess?: {
+    run: <T>(
+      input: {
+        teamId: string
+        operation: WorkspaceOperation
+        actor: WorkspaceActor
+      },
+      action: () => Promise<T>,
+    ) => Promise<T>
+  }
+  handleRequest?: (
+    request: Request,
+    session: { userId: string; email: string } | null,
+  ) => Promise<Response>
+
+  generateHostname?: (
+    input: GeneratedHostnameInput,
+  ) => Promise<GeneratedHostname>
+  serverLifecycle?: {
+    reconcile: (server: DeploymentServer) => Promise<void>
+    maintain: () => Promise<void>
+  }
+  certificates?: {
+    request: (input: {
+      server: DeploymentServer
+      csrPem?: string
+      installedCertificateSha256?: string
+    }) => Promise<CertificateResult>
+  }
+}
+
+export function validatePluginServices(value: unknown): PluginServices {
+  if (!value || typeof value !== 'object' || Array.isArray(value))
+    throw new Error('Plugin services must be an object.')
+  const services = value as Record<string, unknown>
+  const allowed = new Set([
+    'generateHostname',
+    'serverLifecycle',
+    'certificates',
+    'workspaceAccess',
+    'handleRequest',
+    'runtimeLogLimits',
+  ])
+  if (Object.keys(value).some((key) => !allowed.has(key)))
+    throw new Error('Unknown devpush plugin service.')
+  if (
+    services.generateHostname !== undefined &&
+    typeof services.generateHostname !== 'function'
+  )
+    throw new Error('Invalid generated hostname service.')
+  if (
+    services.serverLifecycle !== undefined &&
+    !hasMethods(services.serverLifecycle, ['reconcile', 'maintain'])
+  )
+    throw new Error('Invalid server lifecycle service.')
+  if (
+    services.certificates !== undefined &&
+    !hasMethods(services.certificates, ['request'])
+  )
+    throw new Error('Invalid certificate service.')
+  if (
+    services.workspaceAccess !== undefined &&
+    !hasMethods(services.workspaceAccess, ['run'])
+  )
+    throw new Error('Invalid workspace access service.')
+  if (
+    services.handleRequest !== undefined &&
+    typeof services.handleRequest !== 'function'
+  )
+    throw new Error('Invalid plugin request service.')
+  if (
+    services.runtimeLogLimits !== undefined &&
+    typeof services.runtimeLogLimits !== 'function'
+  )
+    throw new Error('Invalid runtime log limits service.')
+  return Object.freeze(value)
+}
+
+function hasMethods(value: unknown, methods: ReadonlyArray<string>) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false
+  const record = value as Record<string, unknown>
+  return (
+    Object.keys(record).every((key) => methods.includes(key)) &&
+    methods.every((key) => typeof record[key] === 'function')
+  )
+}

package/src/plugins/default.server.ts

@@ -0,0 +1,4 @@
+import type { ServerPluginEntry } from './server'
+
+const plugins: readonly ServerPluginEntry[] = []
+export default plugins

package/src/plugins/default.ui.ts

@@ -0,0 +1,4 @@
+import type { ClientPluginEntry } from './client'
+
+const plugins: readonly ClientPluginEntry[] = []
+export default plugins

package/src/plugins/operations.ts

@@ -0,0 +1,45 @@
+import type { TeamRole } from '../lib/team-role'
+
+/** Generic workspace effects; product policies remain in plugins. */
+export const workspaceOperations = [
+  'workspace.update',
+  'workspace.delete',
+  'workspace.leave',
+  'member.invite',
+  'member.accept',
+  'member.role',
+  'member.remove',
+  'member.revoke',
+  'owner.transfer',
+  'project.create',
+  'project.update',
+  'project.delete',
+  'environment.update',
+  'variable.update',
+  'domain.update',
+  'domain.verify',
+  'deployment.create',
+  'backup.policy.save',
+  'backup.policy.delete',
+  'backup.storage.save',
+  'backup.storage.delete',
+  'backup.run',
+  'backup.restore',
+  'backup.claim',
+  'restore.claim',
+  'server.create',
+  'server.delete',
+  'server.update',
+  'server.enable',
+  'server.disable',
+  'server.enroll',
+  'credential.create',
+  'credential.rotate',
+] as const
+export type WorkspaceOperation = (typeof workspaceOperations)[number]
+export type WorkspaceActor =
+  | { kind: 'user'; userId: string; roleCeiling?: TeamRole }
+  | {
+      kind: 'system'
+      source: 'github.push' | 'backup.schedule' | 'agent' | 'maintenance'
+    }

package/src/plugins/server.ts

@@ -0,0 +1,197 @@
+import { pluginApiVersion } from './version'
+import { validatePluginServices } from './contract'
+import type {
+  PluginContext,
+  PluginServices,
+  WorkspaceOperation,
+  WorkspaceActor,
+} from './contract'
+
+export type {
+  CertificateResult,
+  DeploymentServer,
+  GeneratedHostnameInput,
+  RuntimeLogLimits,
+  WorkspaceActor,
+  WorkspaceOperation,
+  PluginContext,
+  PluginServices,
+  PreparedNotification,
+} from './contract'
+
+export interface ServerPlugin {
+  apiVersion: typeof pluginApiVersion
+  create: (
+    environment: Readonly<Record<string, string | undefined>>,
+    context: PluginContext,
+  ) => PluginServices
+}
+export interface ServerPluginEntry {
+  id: string
+  implementation: ServerPlugin
+}
+
+export function defineServerPlugin(
+  create: ServerPlugin['create'],
+): Readonly<ServerPlugin> {
+  if (typeof create !== 'function')
+    throw new Error('Plugin create must be a function.')
+  return Object.freeze({ apiVersion: pluginApiVersion, create })
+}
+
+/** Compose trusted static plugins. Core permissions still precede every policy. */
+export function composeServerPlugins(
+  entries: readonly ServerPluginEntry[],
+  environment: Readonly<Record<string, string | undefined>>,
+  context: PluginContext,
+): PluginServices {
+  const environmentSnapshot = Object.freeze({ ...environment })
+  const ids = new Set<string>()
+  const services = entries.map(({ id, implementation }) => {
+    if (ids.has(id)) throw new Error(`Duplicate server plugin: ${id}`)
+    ids.add(id)
+    if (
+      (implementation.apiVersion as number) !== pluginApiVersion ||
+      typeof implementation.create !== 'function'
+    )
+      throw new Error(`Incompatible server plugin: ${id}`)
+    return {
+      id,
+      value: validatePluginServices(
+        implementation.create(environmentSnapshot, context),
+      ),
+    }
+  })
+  function exclusive<
+    TKey extends 'generateHostname' | 'certificates' | 'runtimeLogLimits',
+  >(key: TKey): PluginServices[TKey] {
+    const providers = services.filter(({ value }) => value[key])
+    if (providers.length > 1)
+      throw new Error(
+        `Conflicting ${key} providers: ${providers.map(({ id }) => id).join(', ')}`,
+      )
+    return providers[0]?.value[key]
+  }
+  const policies = services.flatMap(({ id, value }) =>
+    value.workspaceAccess ? [{ id, policy: value.workspaceAccess }] : [],
+  )
+  const lifecycle = services.flatMap(({ value }) =>
+    value.serverLifecycle ? [value.serverLifecycle] : [],
+  )
+  return {
+    generateHostname: exclusive('generateHostname'),
+    certificates: exclusive('certificates'),
+    runtimeLogLimits: exclusive('runtimeLogLimits'),
+    ...(policies.length
+      ? {
+          workspaceAccess: {
+            async run<T>(
+              input: {
+                teamId: string
+                operation: WorkspaceOperation
+                actor: WorkspaceActor
+              },
+              action: () => Promise<T>,
+            ) {
+              const policyInput = Object.freeze({
+                ...input,
+                actor: Object.freeze({ ...input.actor }),
+              })
+              let actionSucceeded = false
+              const invoke = async (index: number): Promise<T> => {
+                const entry = policies[index]
+                if (!entry) {
+                  const value = await action()
+                  actionSucceeded = true
+                  return value
+                }
+                let calls = 0
+                let closed = false
+                let downstream: Promise<T> | undefined
+                try {
+                  await entry.policy.run(policyInput, () => {
+                    if (calls !== 0)
+                      throw new Error(
+                        `Plugin ${entry.id} invoked its mutation more than once.`,
+                      )
+                    if (closed)
+                      throw new Error(
+                        `Plugin ${entry.id} invoked its mutation after returning.`,
+                      )
+                    calls++
+                    downstream = invoke(index + 1)
+                    // Await it below even when a faulty provider forgets to do so.
+                    void downstream.catch(() => {})
+                    return downstream
+                  })
+                } catch (error) {
+                  closed = true
+                  if (downstream) await downstream.catch(() => {})
+                  if (actionSucceeded && error instanceof WorkspacePolicyError)
+                    throw new Error(
+                      `Plugin ${entry.id} rejected an already completed mutation.`,
+                    )
+                  throw error
+                } finally {
+                  closed = true
+                }
+                if (!downstream)
+                  throw new Error(
+                    `Plugin ${entry.id} did not invoke or reject its mutation.`,
+                  )
+                return downstream
+              }
+              return invoke(0)
+            },
+          },
+        }
+      : {}),
+    ...(lifecycle.length
+      ? {
+          serverLifecycle: {
+            async reconcile(server) {
+              for (const service of lifecycle) await service.reconcile(server)
+            },
+            async maintain() {
+              const results = await Promise.allSettled(
+                lifecycle.map((service) =>
+                  Promise.resolve().then(() => service.maintain()),
+                ),
+              )
+              const failures = results.filter(
+                (result) => result.status === 'rejected',
+              )
+              if (failures.length)
+                throw new AggregateError(
+                  failures.map((result) => result.reason),
+                  'Plugin maintenance failed.',
+                )
+            },
+          },
+        }
+      : {}),
+    async handleRequest(request, session) {
+      const id = /^\/api\/plugins\/([^/]+)(?:\/|$)/.exec(
+        new URL(request.url).pathname,
+      )?.[1]
+      const handler = services.find((service) => service.id === id)?.value
+        .handleRequest
+      return handler
+        ? handler(request, session)
+        : new Response('Not found', { status: 404 })
+    },
+  }
+}
+
+/** A deliberate policy refusal. Provider/internal errors must use ordinary errors. */
+export class WorkspacePolicyError extends Error {
+  name = 'WorkspacePolicyError'
+  constructor(
+    readonly reason: 'restricted' | 'limit' | 'busy',
+    readonly publicDetails?: { message: string; recoveryUrl?: string },
+  ) {
+    super('Workspace policy rejected the operation.')
+  }
+}
+
+export { workspaceOperations } from './operations'

package/src/plugins/version.ts

@@ -0,0 +1 @@
+export const pluginApiVersion = 3