Feat: Sandbox details events table

spec/openapi.argus.yaml

@@ -309,6 +309,13 @@ paths:
           schema:
             type: boolean
             default: false
+        - name: types
+          in: query
+          required: false
+          schema:
+            type: array
+            items:
+              type: string
       responses:
         "200":
           description: Successfully returned the sandbox events
@@ -357,6 +364,13 @@ paths:
           schema:
             type: boolean
             default: false
+        - name: types
+          in: query
+          required: false
+          schema:
+            type: array
+            items:
+              type: string
       responses:
         "200":
           description: Successfully returned the sandbox events

src/app/dashboard/[teamSlug]/sandboxes/[sandboxId]/events/page.tsx

@@ -0,0 +1,5 @@
+import { SandboxEventsView } from '@/features/dashboard/sandbox/events'
+
+export default function SandboxEventsPage() {
+  return <SandboxEventsView />
+}

src/configs/urls.ts

@@ -32,6 +32,8 @@ export const PROTECTED_URLS = {
     `/dashboard/${teamSlug}/sandboxes/${sandboxId}/monitoring`,
   SANDBOX_MONITORING: (teamSlug: string, sandboxId: string) =>
     `/dashboard/${teamSlug}/sandboxes/${sandboxId}/monitoring`,
+  SANDBOX_EVENTS: (teamSlug: string, sandboxId: string) =>
+    `/dashboard/${teamSlug}/sandboxes/${sandboxId}/events`,
   SANDBOX_LOGS: (teamSlug: string, sandboxId: string) =>
     `/dashboard/${teamSlug}/sandboxes/${sandboxId}/logs`,
   SANDBOX_FILESYSTEM: (teamSlug: string, sandboxId: string) =>
@@ -77,6 +79,8 @@ export const HELP_URLS = {
   BUILD_TEMPLATE:
     'https://e2b.dev/docs/sandbox-template#4-build-your-sandbox-template',
   START_COMMAND: 'https://e2b.dev/docs/sandbox-template/start-cmd',
+  SANDBOX_LIFECYCLE_EVENTS:
+    'https://e2b.dev/docs/sandbox/lifecycle-events-api',
 }
 
 export const BASE_URL = process.env.VERCEL_ENV

src/core/modules/sandboxes/lifecycle-event-types.ts

@@ -0,0 +1,96 @@
+import { z } from 'zod'
+
+const SANDBOX_LIFECYCLE_EVENT_TYPE_VALUES: [
+  'sandbox.lifecycle.created',
+  'sandbox.lifecycle.updated',
+  'sandbox.lifecycle.paused',
+  'sandbox.lifecycle.resumed',
+  'sandbox.lifecycle.killed',
+] = [
+  'sandbox.lifecycle.created',
+  'sandbox.lifecycle.updated',
+  'sandbox.lifecycle.paused',
+  'sandbox.lifecycle.resumed',
+  'sandbox.lifecycle.killed',
+]
+
+const SANDBOX_LIFECYCLE_EVENT_URL_VALUES: [
+  'created',
+  'updated',
+  'paused',
+  'resumed',
+  'killed',
+] = ['created', 'updated', 'paused', 'resumed', 'killed']
+
+const sandboxLifecycleEventTypeSchema = z.enum(
+  SANDBOX_LIFECYCLE_EVENT_TYPE_VALUES
+)
+const sandboxLifecycleEventUrlValueSchema = z.enum(
+  SANDBOX_LIFECYCLE_EVENT_URL_VALUES
+)
+
+type SandboxLifecycleEventType = z.infer<typeof sandboxLifecycleEventTypeSchema>
+type SandboxLifecycleEventUrlValue = z.infer<
+  typeof sandboxLifecycleEventUrlValueSchema
+>
+
+const SANDBOX_LIFECYCLE_EVENT_LABELS: Record<
+  SandboxLifecycleEventType,
+  string
+> = {
+  'sandbox.lifecycle.created': 'Created',
+  'sandbox.lifecycle.updated': 'Updated',
+  'sandbox.lifecycle.paused': 'Paused',
+  'sandbox.lifecycle.resumed': 'Resumed',
+  'sandbox.lifecycle.killed': 'Killed',
+}
+
+const SANDBOX_LIFECYCLE_EVENT_TYPE_TO_URL_VALUE: Record<
+  SandboxLifecycleEventType,
+  SandboxLifecycleEventUrlValue
+> = {
+  'sandbox.lifecycle.created': 'created',
+  'sandbox.lifecycle.updated': 'updated',
+  'sandbox.lifecycle.paused': 'paused',
+  'sandbox.lifecycle.resumed': 'resumed',
+  'sandbox.lifecycle.killed': 'killed',
+}
+
+const SANDBOX_LIFECYCLE_EVENT_URL_VALUE_TO_TYPE: Record<
+  SandboxLifecycleEventUrlValue,
+  SandboxLifecycleEventType
+> = {
+  created: 'sandbox.lifecycle.created',
+  updated: 'sandbox.lifecycle.updated',
+  paused: 'sandbox.lifecycle.paused',
+  resumed: 'sandbox.lifecycle.resumed',
+  killed: 'sandbox.lifecycle.killed',
+}
+
+/** Returns a lifecycle event label. Example: "sandbox.lifecycle.created" -> "Created". */
+const getSandboxLifecycleEventLabel = (type: string) => {
+  const parsedType = sandboxLifecycleEventTypeSchema.safeParse(type)
+  if (!parsedType.success) return type
+  return SANDBOX_LIFECYCLE_EVENT_LABELS[parsedType.data]
+}
+
+const getSandboxLifecycleEventTypeFromUrlValue = (value: string | null) => {
+  if (!value) return null
+
+  const parsedUrlValue = sandboxLifecycleEventUrlValueSchema.safeParse(value)
+  if (parsedUrlValue.success) {
+    return SANDBOX_LIFECYCLE_EVENT_URL_VALUE_TO_TYPE[parsedUrlValue.data]
+  }
+
+  const parsedType = sandboxLifecycleEventTypeSchema.safeParse(value)
+  if (parsedType.success) {
+    return parsedType.data
+  }
+
+  return null
+}
+
+const getSandboxLifecycleEventUrlValue = (type: SandboxLifecycleEventType) =>
+  SANDBOX_LIFECYCLE_EVENT_TYPE_TO_URL_VALUE[type]
+
+export { getSandboxLifecycleEventLabel, getSandboxLifecycleEventTypeFromUrlValue, getSandboxLifecycleEventUrlValue, SANDBOX_LIFECYCLE_EVENT_LABELS, SANDBOX_LIFECYCLE_EVENT_TYPE_VALUES, SANDBOX_LIFECYCLE_EVENT_URL_VALUES, sandboxLifecycleEventTypeSchema, sandboxLifecycleEventUrlValueSchema, type SandboxLifecycleEventType, type SandboxLifecycleEventUrlValue }

src/core/modules/sandboxes/repository.server.ts

@@ -3,6 +3,7 @@
 import { SUPABASE_AUTH_HEADERS } from '@/configs/api'
 import type { components as DashboardComponents } from '@/contracts/dashboard-api'
 import type { components as InfraComponents } from '@/contracts/infra-api'
+import type { SandboxLifecycleEventType } from '@/core/modules/sandboxes/lifecycle-event-types'
 import type {
   SandboxEventModel,
   Sandboxes,
@@ -36,6 +37,13 @@
   endUnixMs: number
 }
 
+export interface ListSandboxLifecycleEventsOptions {
+  offset?: number
+  limit?: number
+  orderAsc?: boolean
+  types?: SandboxLifecycleEventType[]
+}
+
 export interface SandboxesRepository {
   getSandboxLogs(
     sandboxId: string,
@@ -56,6 +64,10 @@
   getSandboxLifecycleEvents(
     sandboxId: string
   ): Promise<RepoResult<SandboxEventModel[]>>
+  listSandboxLifecycleEvents(
+    sandboxId: string,
+    options?: ListSandboxLifecycleEventsOptions
+  ): Promise<RepoResult<SandboxEventModel[]>>
   getSandboxMetrics(
     sandboxId: string,
     options: GetSandboxMetricsOptions
@@ -89,6 +101,62 @@
     authHeaders: SUPABASE_AUTH_HEADERS,
   }
 ): SandboxesRepository {
+  /** Fetches one sandbox lifecycle events page. Example: { offset: 20, limit: 20 } -> the next 20 events. */
+  const listSandboxLifecycleEventsPage = async (
+    sandboxId: string,
+    options: ListSandboxLifecycleEventsOptions = {}
+  ): Promise<RepoResult<SandboxEventModel[]>> => {
+    const result = await deps.infraClient.GET('/events/sandboxes/{sandboxID}', {
+      params: {
+        path: {
+          sandboxID: sandboxId,
+        },
+        query: {
+          offset: options.offset,
+          limit: options.limit,
+          orderAsc: options.orderAsc,
+          types: options.types,
+        },
+      },
+      headers: {
+        ...deps.authHeaders(scope.accessToken, scope.teamId),
+      },
+      cache: 'no-store',
+    })
+
+    if (!result.response.ok || result.error) {
+      const status = result.response.status
+
+      l.error({
+        key: 'repositories:sandboxes:list_sandbox_lifecycle_events:infra_error',
+        error: result.error,
+        team_id: scope.teamId,
+        context: {
+          status,
+          path: '/events/sandboxes/{sandboxID}',
+          sandbox_id: sandboxId,
+          offset: options.offset,
+          limit: options.limit,
+          order_asc: options.orderAsc,
+          types: options.types,
+        },
+      })
+
+      return err(
+        repoErrorFromHttp(
+          status,
+          status === 404
+            ? SANDBOX_NOT_FOUND_MESSAGE
+            : (result.error?.message ??
+                'Failed to fetch sandbox lifecycle events'),
+          result.error
+        )
+      )
+    }
+
+    return ok(result.data ?? [])
+  }
+
   return {
     async getSandboxLogs(sandboxId, options = {}) {
       const result = await deps.infraClient.GET(
@@ -239,57 +307,16 @@
         pageIndex < SANDBOX_EVENTS_MAX_PAGES;
         pageIndex += 1, offset += SANDBOX_EVENTS_PAGE_SIZE
       ) {
-        try {
-          const result = await deps.infraClient.GET(
-            '/events/sandboxes/{sandboxID}',
-            {
-              params: {
-                path: {
-                  sandboxID: sandboxId,
-                },
-                query: {
-                  offset,
-                  limit: SANDBOX_EVENTS_PAGE_SIZE,
-                  orderAsc: true,
-                },
-              },
-              headers: {
-                ...deps.authHeaders(scope.accessToken, scope.teamId),
-              },
-              cache: 'no-store',
-            }
-          )
-
-          if (!result.response.ok || result.error) {
-            l.warn({
-              key: 'repositories:sandboxes:get_sandbox_lifecycle_events:infra_error',
-              error: result.error,
-              team_id: scope.teamId,
-              context: {
-                status: result.response.status,
-                path: '/events/sandboxes/{sandboxID}',
-                sandbox_id: sandboxId,
-                offset,
-                limit: SANDBOX_EVENTS_PAGE_SIZE,
-              },
-            })
-            break
-          }
-
-          const page = result.data ?? []
-          lifecycleEvents.push(
-            ...page.filter((event) =>
-              event.type.startsWith(SANDBOX_LIFECYCLE_EVENT_PREFIX)
-            )
-          )
+        const result = await listSandboxLifecycleEventsPage(sandboxId, {
+          offset,
+          limit: SANDBOX_EVENTS_PAGE_SIZE,
+          orderAsc: true,
+        })
 
-          if (page.length < SANDBOX_EVENTS_PAGE_SIZE) {
-            break
-          }
-        } catch (error) {
+        if (!result.ok) {
           l.warn({
-            key: 'repositories:sandboxes:get_sandbox_lifecycle_events:infra_exception',
-            error,
+            key: 'repositories:sandboxes:get_sandbox_lifecycle_events:infra_error',
+            error: result.error,
             team_id: scope.teamId,
             context: {
               path: '/events/sandboxes/{sandboxID}',
@@ -300,10 +327,24 @@
           })
           break
         }
+
+        const page = result.data
+        lifecycleEvents.push(
+          ...page.filter((event) =>
+            event.type.startsWith(SANDBOX_LIFECYCLE_EVENT_PREFIX)
+          )
+        )
+
+        if (page.length < SANDBOX_EVENTS_PAGE_SIZE) {
+          break
+        }
       }
 
       return ok(lifecycleEvents)
     },
+    async listSandboxLifecycleEvents(sandboxId, options = {}) {
+      return listSandboxLifecycleEventsPage(sandboxId, options)
+    },
     async getSandboxMetrics(sandboxId, options) {
       const startUnixSeconds = Math.floor(options.startUnixMs / 1000)
       const endUnixSeconds = Math.floor(options.endUnixMs / 1000)

src/core/server/api/routers/sandbox.ts

@@ -1,5 +1,6 @@
 import { millisecondsInDay } from 'date-fns/constants'
 import { z } from 'zod'
+import { SANDBOX_LIFECYCLE_EVENT_TYPE_VALUES } from '@/core/modules/sandboxes/lifecycle-event-types'
 import {
   deriveSandboxLifecycleFromEvents,
   mapApiSandboxRecordToModel,
@@ -29,6 +30,44 @@
 export const sandboxRouter = createTRPCRouter({
   // QUERIES
 
+  events: sandboxRepositoryProcedure
+    .input(
+      z.object({
+        sandboxId: SandboxIdSchema,
+        offset: z.number().int().min(0).optional(),
+        limit: z.number().int().min(1).max(100).optional(),
+        orderAsc: z.boolean().optional(),
+        type: z.enum(SANDBOX_LIFECYCLE_EVENT_TYPE_VALUES).optional(),
+      })
+    )
+    .query(async ({ ctx, input }) => {
+      const { sandboxId, type } = input
+      const offset = input.offset ?? 0
+      const limit = input.limit ?? 20
+      const orderAsc = input.orderAsc ?? false
+
+      const eventsResult = await ctx.sandboxesRepository.listSandboxLifecycleEvents(
+        sandboxId,
+        {
+          offset,
+          limit,
+          orderAsc,
+          types: type ? [type] : undefined,
+        }
+      )
+      if (!eventsResult.ok) {
+        throwTRPCErrorFromRepoError(eventsResult.error)
+      }
+
+      return {
+        events: eventsResult.data,
+        hasNextPage: eventsResult.data.length === limit,
+        hasPreviousPage: offset > 0,
+        limit,
+        offset,
+      }
+    }),
+
   details: sandboxRepositoryProcedure
     .input(
       z.object({