feat(schedule-details): SLICE-2 — describeSchedule gRPC + GET route handler

Wire DescribeSchedule into the gRPC client and expose a typed GET handler:

- Add DescribeScheduleRequest/Response imports + describeSchedule method to
  GRPCClusterMethods type and getClusterServicesMethods (scheduleService)
- Add describeSchedule: jest.fn() to grpc-cluster-methods mock
- Route handler describe-schedule.ts: GET /api/domains/[domain]/[cluster]/schedules/[scheduleId]
  calls grpcClusterMethods.describeSchedule, returns DTO; logs and maps GRPCErrors
- Fixtures: running schedule, paused schedule (with pauseInfo.pausedBy + reason),
  no-next-run variant — covers chart gutter + banner (SLICE-8.3 / SLICE-9) test needs
- Node tests: happy path, paused state, NOT_FOUND → 404, generic error → 500

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: Assem-Uber

src/app/api/domains/[domain]/[cluster]/schedules/[scheduleId]/route.ts

@@ -0,0 +1,18 @@
+import { type NextRequest } from 'next/server';
+
+import { describeSchedule } from '@/route-handlers/describe-schedule/describe-schedule';
+import { type RouteParams } from '@/route-handlers/describe-schedule/describe-schedule.types';
+import { routeHandlerWithMiddlewares } from '@/utils/route-handlers-middleware';
+import routeHandlersDefaultMiddlewares from '@/utils/route-handlers-middleware/config/route-handlers-default-middlewares.config';
+
+export async function GET(
+  request: NextRequest,
+  options: { params: RouteParams }
+) {
+  return routeHandlerWithMiddlewares(
+    describeSchedule,
+    request,
+    options,
+    routeHandlersDefaultMiddlewares
+  );
+}

src/route-handlers/describe-schedule/__fixtures__/mock-describe-schedule-response.ts

@@ -0,0 +1,77 @@
+import { type DescribeScheduleResponse } from '@/__generated__/proto-ts/uber/cadence/api/v1/DescribeScheduleResponse';
+
+export function getMockDescribeScheduleResponse(
+  overrides: Partial<DescribeScheduleResponse> = {}
+): DescribeScheduleResponse {
+  return {
+    spec: {
+      cronExpression: '0 * * * *',
+      startTime: null,
+      endTime: null,
+      jitter: null,
+    },
+    action: {
+      startWorkflowAction: {
+        workflowType: { name: 'mock-workflow-type' },
+        taskList: { name: 'mock-task-list', kind: 'TASK_LIST_KIND_NORMAL' },
+        input: null,
+        workflowIdPrefix: 'mock-prefix',
+        executionStartToCloseTimeout: { seconds: '3600', nanos: 0 },
+        taskStartToCloseTimeout: { seconds: '10', nanos: 0 },
+        retryPolicy: null,
+        memo: null,
+        searchAttributes: null,
+      },
+    },
+    policies: {
+      overlapPolicy: 'SCHEDULE_OVERLAP_POLICY_SKIP',
+      catchUpPolicy: 'SCHEDULE_CATCH_UP_POLICY_UNLIMITED',
+      catchUpWindow: null,
+      pauseOnFailure: false,
+      bufferLimit: 0,
+      concurrencyLimit: 0,
+    },
+    state: {
+      paused: false,
+      pauseInfo: null,
+    },
+    info: {
+      lastRunTime: { seconds: '1700000000', nanos: 0 },
+      nextRunTime: { seconds: '1700003600', nanos: 0 },
+      totalRuns: '42',
+      createTime: { seconds: '1699000000', nanos: 0 },
+      lastUpdateTime: { seconds: '1700000000', nanos: 0 },
+      ongoingBackfills: [],
+    },
+    memo: null,
+    searchAttributes: null,
+    ...overrides,
+  };
+}
+
+export const mockRunningDescribeScheduleResponse =
+  getMockDescribeScheduleResponse();
+
+export const mockPausedDescribeScheduleResponse =
+  getMockDescribeScheduleResponse({
+    state: {
+      paused: true,
+      pauseInfo: {
+        reason: 'Paused for maintenance',
+        pausedAt: { seconds: '1700001000', nanos: 0 },
+        pausedBy: 'operator@example.com',
+      },
+    },
+  });
+
+export const mockDescribeScheduleResponseNoNextRun =
+  getMockDescribeScheduleResponse({
+    info: {
+      lastRunTime: { seconds: '1700000000', nanos: 0 },
+      nextRunTime: null,
+      totalRuns: '10',
+      createTime: { seconds: '1699000000', nanos: 0 },
+      lastUpdateTime: { seconds: '1700000000', nanos: 0 },
+      ongoingBackfills: [],
+    },
+  });

src/route-handlers/describe-schedule/__tests__/describe-schedule.node.ts

@@ -0,0 +1,136 @@
+import { status } from '@grpc/grpc-js';
+import { NextRequest } from 'next/server';
+
+import { GRPCError } from '@/utils/grpc/grpc-error';
+import logger from '@/utils/logger';
+import { mockGrpcClusterMethods } from '@/utils/route-handlers-middleware/middlewares/__mocks__/grpc-cluster-methods';
+
+import {
+  mockRunningDescribeScheduleResponse,
+  mockPausedDescribeScheduleResponse,
+} from '../__fixtures__/mock-describe-schedule-response';
+import { describeSchedule } from '../describe-schedule';
+import { type Context, type RequestParams } from '../describe-schedule.types';
+
+jest.mock('@/utils/logger');
+
+describe(describeSchedule.name, () => {
+  beforeEach(() => {
+    jest.resetAllMocks();
+  });
+
+  it('calls describeSchedule and returns the response for a running schedule', async () => {
+    const { res, mockDescribeSchedule } = await setup({
+      response: mockRunningDescribeScheduleResponse,
+    });
+
+    expect(mockDescribeSchedule).toHaveBeenCalledWith({
+      domain: 'mock-domain',
+      scheduleId: 'mock-schedule-id',
+    });
+
+    expect(res.status).toEqual(200);
+    const responseJson = await res.json();
+    expect(responseJson.state.paused).toBe(false);
+    expect(responseJson.info.nextRunTime).toBeTruthy();
+  });
+
+  it('returns describe response for a paused schedule', async () => {
+    const { res } = await setup({
+      response: mockPausedDescribeScheduleResponse,
+    });
+
+    expect(res.status).toEqual(200);
+    const responseJson = await res.json();
+    expect(responseJson.state.paused).toBe(true);
+    expect(responseJson.state.pauseInfo.reason).toBe('Paused for maintenance');
+    expect(responseJson.state.pauseInfo.pausedBy).toBe(
+      'operator@example.com'
+    );
+  });
+
+  it('returns 404 when describeSchedule throws a NOT_FOUND GRPCError', async () => {
+    const { res } = await setup({
+      error: new GRPCError('schedule not found', {
+        grpcStatusCode: status.NOT_FOUND,
+      }),
+    });
+
+    expect(res.status).toEqual(404);
+    const responseJson = await res.json();
+    expect(responseJson).toEqual(
+      expect.objectContaining({ message: 'schedule not found' })
+    );
+
+    expect(logger.error).toHaveBeenCalledWith(
+      expect.objectContaining({
+        requestParams: {
+          domain: 'mock-domain',
+          cluster: 'mock-cluster',
+          scheduleId: 'mock-schedule-id',
+        },
+        error: expect.any(GRPCError),
+      }),
+      'Error describing schedule: schedule not found'
+    );
+  });
+
+  it('returns 500 when describeSchedule throws a generic error', async () => {
+    const { res } = await setup({
+      error: new Error('connection reset'),
+    });
+
+    expect(res.status).toEqual(500);
+    const responseJson = await res.json();
+    expect(responseJson).toEqual(
+      expect.objectContaining({ message: 'Error describing schedule' })
+    );
+
+    expect(logger.error).toHaveBeenCalledWith(
+      expect.objectContaining({
+        requestParams: {
+          domain: 'mock-domain',
+          cluster: 'mock-cluster',
+          scheduleId: 'mock-schedule-id',
+        },
+        error: expect.any(Error),
+      }),
+      'Error describing schedule'
+    );
+  });
+});
+
+async function setup({
+  response,
+  error,
+}: {
+  response?: Awaited<
+    ReturnType<typeof mockGrpcClusterMethods.describeSchedule>
+  >;
+  error?: Error;
+} = {}) {
+  const mockDescribeSchedule = jest
+    .spyOn(mockGrpcClusterMethods, 'describeSchedule')
+    .mockImplementationOnce(async () => {
+      if (error) {
+        throw error;
+      }
+      return response ?? mockRunningDescribeScheduleResponse;
+    });
+
+  const res = await describeSchedule(
+    new NextRequest('http://localhost'),
+    {
+      params: {
+        domain: 'mock-domain',
+        cluster: 'mock-cluster',
+        scheduleId: 'mock-schedule-id',
+      },
+    } as RequestParams,
+    {
+      grpcClusterMethods: mockGrpcClusterMethods,
+    } as Context
+  );
+
+  return { res, mockDescribeSchedule };
+}

src/route-handlers/describe-schedule/describe-schedule.ts

@@ -0,0 +1,40 @@
+import { type NextRequest, NextResponse } from 'next/server';
+
+import { getHTTPStatusCode, GRPCError } from '@/utils/grpc/grpc-error';
+import logger, { type RouteHandlerErrorPayload } from '@/utils/logger';
+
+import { type Context, type RequestParams, type RouteParams } from './describe-schedule.types';
+
+export async function describeSchedule(
+  _request: NextRequest,
+  requestParams: RequestParams,
+  ctx: Context
+) {
+  const params = requestParams.params as RouteParams;
+
+  try {
+    const response = await ctx.grpcClusterMethods.describeSchedule({
+      domain: params.domain,
+      scheduleId: params.scheduleId,
+    });
+
+    return NextResponse.json(response);
+  } catch (e) {
+    logger.error<RouteHandlerErrorPayload>(
+      { requestParams: params, error: e },
+      'Error describing schedule' +
+        (e instanceof GRPCError ? ': ' + e.message : '')
+    );
+
+    return NextResponse.json(
+      {
+        message:
+          e instanceof GRPCError ? e.message : 'Error describing schedule',
+        cause: e,
+      },
+      {
+        status: getHTTPStatusCode(e),
+      }
+    );
+  }
+}

src/route-handlers/describe-schedule/describe-schedule.types.ts

@@ -0,0 +1,16 @@
+import { type DescribeScheduleResponse } from '@/__generated__/proto-ts/uber/cadence/api/v1/DescribeScheduleResponse';
+import { type DefaultMiddlewaresContext } from '@/utils/route-handlers-middleware';
+
+export type RouteParams = {
+  domain: string;
+  cluster: string;
+  scheduleId: string;
+};
+
+export type RequestParams = {
+  params: RouteParams;
+};
+
+export type DescribeScheduleDTO = DescribeScheduleResponse;
+
+export type Context = DefaultMiddlewaresContext;

src/utils/grpc/grpc-client.ts

@@ -5,6 +5,8 @@ import { type CountWorkflowExecutionsRequest__Input } from '@/__generated__/prot
 import { type CountWorkflowExecutionsResponse } from '@/__generated__/proto-ts/uber/cadence/api/v1/CountWorkflowExecutionsResponse';
 import { type CreateScheduleRequest__Input } from '@/__generated__/proto-ts/uber/cadence/api/v1/CreateScheduleRequest';
 import { type CreateScheduleResponse } from '@/__generated__/proto-ts/uber/cadence/api/v1/CreateScheduleResponse';
+import { type DescribeScheduleRequest__Input } from '@/__generated__/proto-ts/uber/cadence/api/v1/DescribeScheduleRequest';
+import { type DescribeScheduleResponse } from '@/__generated__/proto-ts/uber/cadence/api/v1/DescribeScheduleResponse';
 import { type DescribeDomainRequest__Input } from '@/__generated__/proto-ts/uber/cadence/api/v1/DescribeDomainRequest';
 import { type DescribeDomainResponse } from '@/__generated__/proto-ts/uber/cadence/api/v1/DescribeDomainResponse';
 import { type DescribeTaskListRequest__Input } from '@/__generated__/proto-ts/uber/cadence/api/v1/DescribeTaskListRequest';
@@ -80,6 +82,9 @@ export type GRPCClusterMethods = {
   createSchedule: (
     payload: CreateScheduleRequest__Input
   ) => Promise<CreateScheduleResponse>;
+  describeSchedule: (
+    payload: DescribeScheduleRequest__Input
+  ) => Promise<DescribeScheduleResponse>;
   describeCluster: (
     payload: DescribeClusterRequest__Input
   ) => Promise<DescribeClusterResponse>;
@@ -255,6 +260,13 @@ const getClusterServicesMethods = async (
       method: 'CreateSchedule',
       metadata: metadata,
     }),
+    describeSchedule: scheduleService.request<
+      DescribeScheduleRequest__Input,
+      DescribeScheduleResponse
+    >({
+      method: 'DescribeSchedule',
+      metadata: metadata,
+    }),
     describeCluster: adminService.request<
       DescribeClusterRequest__Input,
       DescribeClusterResponse

src/utils/route-handlers-middleware/middlewares/__mocks__/grpc-cluster-methods.ts

@@ -5,6 +5,7 @@ export const mockGrpcClusterMethods: GRPCClusterMethods = {
   closedWorkflows: jest.fn(),
   countWorkflows: jest.fn(),
   createSchedule: jest.fn(),
+  describeSchedule: jest.fn(),
   describeCluster: jest.fn(),
   describeDomain: jest.fn(),
   updateDomain: jest.fn(),