feat(api): add create schedule POST route and tests

Add Zod request schema, gRPC payload mapping (start-workflow parity for nested action), POST /schedules, and node tests.

Author: Assem-Uber

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

@@ -1,5 +1,6 @@
 import { type NextRequest } from 'next/server';
 
+import { createSchedule } from '@/route-handlers/create-schedule/create-schedule';
 import { listSchedules } from '@/route-handlers/list-schedules/list-schedules';
 import type { RouteParams } from '@/route-handlers/list-schedules/list-schedules.types';
 import { routeHandlerWithMiddlewares } from '@/utils/route-handlers-middleware';
@@ -16,3 +17,15 @@ export async function GET(
     routeHandlersDefaultMiddlewares
   );
 }
+
+export async function POST(
+  request: NextRequest,
+  options: { params: RouteParams }
+) {
+  return routeHandlerWithMiddlewares(
+    createSchedule,
+    request,
+    options,
+    routeHandlersDefaultMiddlewares
+  );
+}

src/route-handlers/create-schedule/__tests__/create-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 { createSchedule } from '../create-schedule';
+import { type Context, type RequestParams } from '../create-schedule.types';
+
+jest.mock('@/utils/logger');
+
+function getValidRequestBody() {
+  return {
+    scheduleId: 'my-schedule',
+    spec: {
+      cronExpression: '0 9 * * *',
+    },
+    action: {
+      startWorkflow: {
+        workflowType: { name: 'DemoWorkflow' },
+        taskList: { name: 'demo-task-list' },
+        workerSDKLanguage: 'GO' as const,
+        workflowIdPrefix: 'scheduled-demo-',
+        executionStartToCloseTimeoutSeconds: 3600,
+        taskStartToCloseTimeoutSeconds: 30,
+      },
+    },
+  };
+}
+
+describe(createSchedule.name, () => {
+  beforeEach(() => {
+    jest.resetAllMocks();
+  });
+
+  it('calls createSchedule and returns the gRPC response', async () => {
+    const { res, mockCreateSchedule } = await setup({});
+
+    expect(mockCreateSchedule).toHaveBeenCalledTimes(1);
+    expect(res.status).toEqual(200);
+    const json = await res.json();
+    expect(json).toEqual({ scheduleId: 'my-schedule' });
+  });
+
+  it('returns validation error when body is invalid', async () => {
+    const { res, mockCreateSchedule } = await setup({
+      body: { scheduleId: '' },
+    });
+
+    expect(mockCreateSchedule).not.toHaveBeenCalled();
+    expect(res.status).toEqual(400);
+    const json = await res.json();
+    expect(json.message).toEqual('Invalid values provided for schedule create');
+    expect(Array.isArray(json.validationErrors)).toBe(true);
+  });
+
+  it('returns error when createSchedule throws a GRPCError', async () => {
+    const { res, mockCreateSchedule } = await setup({
+      error: new GRPCError('Schedule already exists', {
+        grpcStatusCode: status.ALREADY_EXISTS,
+      }),
+    });
+
+    expect(mockCreateSchedule).toHaveBeenCalled();
+    expect(res.status).toEqual(409);
+    const json = await res.json();
+    expect(json).toEqual(
+      expect.objectContaining({
+        message: 'Schedule already exists',
+      })
+    );
+
+    expect(logger.error).toHaveBeenCalledWith(
+      expect.objectContaining({
+        requestParams: { domain: 'mock-domain', cluster: 'mock-cluster' },
+        error: expect.any(GRPCError),
+      }),
+      'Error creating schedule: Schedule already exists'
+    );
+  });
+
+  it('returns error when createSchedule throws a generic error', async () => {
+    const { res, mockCreateSchedule } = await setup({
+      error: new Error('Network error'),
+    });
+
+    expect(mockCreateSchedule).toHaveBeenCalled();
+    expect(res.status).toEqual(500);
+    const json = await res.json();
+    expect(json).toEqual(
+      expect.objectContaining({
+        message: 'Error creating schedule',
+      })
+    );
+
+    expect(logger.error).toHaveBeenCalledWith(
+      expect.objectContaining({
+        requestParams: { domain: 'mock-domain', cluster: 'mock-cluster' },
+        error: expect.any(Error),
+      }),
+      'Error creating schedule'
+    );
+  });
+});
+
+async function setup({ body, error }: { body?: unknown; error?: Error }) {
+  const mockCreateSchedule = jest
+    .spyOn(mockGrpcClusterMethods, 'createSchedule')
+    .mockImplementationOnce(async () => {
+      if (error) {
+        throw error;
+      }
+      return { scheduleId: 'my-schedule' };
+    });
+
+  const payload = body ?? getValidRequestBody();
+
+  const res = await createSchedule(
+    new NextRequest('http://localhost', {
+      method: 'POST',
+      body: JSON.stringify(payload),
+    }),
+    {
+      params: {
+        domain: 'mock-domain',
+        cluster: 'mock-cluster',
+      },
+    } as RequestParams,
+    {
+      grpcClusterMethods: mockGrpcClusterMethods,
+    } as Context
+  );
+
+  return { res, mockCreateSchedule };
+}

src/route-handlers/create-schedule/create-schedule.constants.ts

@@ -0,0 +1,20 @@
+import { ScheduleCatchUpPolicy } from '@/__generated__/proto-ts/uber/cadence/api/v1/ScheduleCatchUpPolicy';
+import { ScheduleOverlapPolicy } from '@/__generated__/proto-ts/uber/cadence/api/v1/ScheduleOverlapPolicy';
+
+import { WORKER_SDK_LANGUAGES } from '../start-workflow/start-workflow.constants';
+
+export { WORKER_SDK_LANGUAGES };
+
+export const SCHEDULE_OVERLAP_POLICIES = [
+  ScheduleOverlapPolicy.SCHEDULE_OVERLAP_POLICY_SKIP_NEW,
+  ScheduleOverlapPolicy.SCHEDULE_OVERLAP_POLICY_BUFFER,
+  ScheduleOverlapPolicy.SCHEDULE_OVERLAP_POLICY_CONCURRENT,
+  ScheduleOverlapPolicy.SCHEDULE_OVERLAP_POLICY_CANCEL_PREVIOUS,
+  ScheduleOverlapPolicy.SCHEDULE_OVERLAP_POLICY_TERMINATE_PREVIOUS,
+] as const;
+
+export const SCHEDULE_CATCH_UP_POLICIES = [
+  ScheduleCatchUpPolicy.SCHEDULE_CATCH_UP_POLICY_SKIP,
+  ScheduleCatchUpPolicy.SCHEDULE_CATCH_UP_POLICY_ONE,
+  ScheduleCatchUpPolicy.SCHEDULE_CATCH_UP_POLICY_ALL,
+] as const;

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

@@ -0,0 +1,53 @@
+import { NextResponse, type NextRequest } from 'next/server';
+
+import { getHTTPStatusCode, GRPCError } from '@/utils/grpc/grpc-error';
+import logger, { type RouteHandlerErrorPayload } from '@/utils/logger';
+
+import { type Context, type RequestParams } from './create-schedule.types';
+import transformCreateScheduleBodyToGrpcInput from './helpers/transform-create-schedule-body-to-grpc-input';
+import createScheduleRequestBodySchema from './schemas/create-schedule-request-body-schema';
+
+export async function createSchedule(
+  request: NextRequest,
+  options: RequestParams,
+  ctx: Context
+) {
+  const params = options.params;
+  const requestBody = await request.json();
+  const { data, error } =
+    createScheduleRequestBodySchema.safeParse(requestBody);
+
+  if (error) {
+    return NextResponse.json(
+      {
+        message: 'Invalid values provided for schedule create',
+        validationErrors: error.errors,
+      },
+      { status: 400 }
+    );
+  }
+
+  const grpcPayload = transformCreateScheduleBodyToGrpcInput({
+    domain: params.domain,
+    body: data,
+  });
+
+  try {
+    const response = await ctx.grpcClusterMethods.createSchedule(grpcPayload);
+    return NextResponse.json(response);
+  } catch (e) {
+    logger.error<RouteHandlerErrorPayload>(
+      { requestParams: params, error: e },
+      'Error creating schedule' +
+        (e instanceof GRPCError ? ': ' + e.message : '')
+    );
+
+    return NextResponse.json(
+      {
+        message: e instanceof GRPCError ? e.message : 'Error creating schedule',
+        cause: e,
+      },
+      { status: getHTTPStatusCode(e) }
+    );
+  }
+}

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

@@ -0,0 +1,23 @@
+import { type z } from 'zod';
+
+import { type CreateScheduleResponse } from '@/__generated__/proto-ts/uber/cadence/api/v1/CreateScheduleResponse';
+import { type DefaultMiddlewaresContext } from '@/utils/route-handlers-middleware';
+
+import type createScheduleRequestBodySchema from './schemas/create-schedule-request-body-schema';
+
+export type RouteParams = {
+  domain: string;
+  cluster: string;
+};
+
+export type RequestParams = {
+  params: RouteParams;
+};
+
+export type CreateScheduleRequestBody = z.infer<
+  typeof createScheduleRequestBodySchema
+>;
+
+export type CreateScheduleResponseBody = CreateScheduleResponse;
+
+export type Context = DefaultMiddlewaresContext;