지속성 실행 SDK

지속성 실행 SDK는 지속성 함수 빌드의 기반입니다. 진행 상태의 체크포인트를 지정하고, 재시도를 처리하고, 실행 흐름을 관리하는 데 필요한 기본 요소를 제공합니다. SDK는 체크포인트 관리 및 재생의 복잡성을 추상화하여 자동으로 내결함성이 되는 순차적 코드를 작성할 수 있습니다.

SDK는 JavaScript, TypeScript 및 Python에 사용할 수 있습니다. 전체 API 설명서 및 예제는 GitHub의 JavaScript/TypeScript SDK 및 Python SDK를 참조하세요.

DurableContext

SDK는 함수에 모든 지속성 작업을 노출하는 DurableContext 객체를 제공합니다. 이 컨텍스트는 표준 Lambda 컨텍스트를 대체하고 체크포인트 생성, 실행 흐름 관리 및 외부 시스템과의 조정을 위한 방법을 제공합니다.

SDK를 사용하려면 지속성 실행 래퍼로 Lambda 핸들러를 래핑합니다.

TypeScript

import { withDurableExecution, DurableContext } from '@aws/durable-execution-sdk-js';

export const handler = withDurableExecution(
  async (event: any, context: DurableContext) => {
    // Your function receives DurableContext instead of Lambda context
    // Use context.step(), context.wait(), etc.
    return result;
  }
);
          

Python

from aws_durable_execution_sdk_python import durable_execution, DurableContext

@durable_execution
def handler(event: dict, context: DurableContext):
    # Your function receives DurableContext
    # Use context.step(), context.wait(), etc.
    return result
          

래퍼는 함수 간접 호출을 가로채고, 기존 체크포인트 로그를 로드하고, 재생 및 체크포인트를 관리하는 DurableContext를 제공합니다.

SDK가 수행하는 작업

SDK는 지속성 실행이 가능하도록 3가지 중요한 책임을 처리합니다.

체크포인트 관리: SDK는 함수가 지속성 작업을 실행할 때 체크포인트를 자동으로 생성합니다. 각 체크포인트에는 작업 유형, 입력 및 결과가 기록됩니다. 함수가 단계를 완료하면 SDK는 계속하기 전에 체크포인트를 유지합니다. 이를 통해 중단되더라도 완료된 작업에서 함수를 재개할 수 있습니다.

재생 조정: 일시 중지 또는 중단 후 함수가 재개되면 SDK가 재생을 수행합니다. 처음부터 코드를 실행하지만, 저장된 체크포인트 결과를 사용하여 완료된 작업을 다시 실행하지 않고 건너뜁니다. SDK를 통해 재생이 결정론적이게 됩니다. 입력 및 체크포인트 로그가 동일하면 함수가 동일한 결과를 생성합니다.

상태 격리: SDK는 비즈니스 로직과 별도로 실행 상태를 유지합니다. 각 지속성 실행에는 다른 실행이 액세스할 수 없는 자체 체크포인트 로그가 있습니다. SDK는 저장된 체크포인트 데이터를 암호화하고 재생 전반에서 상태를 일관적으로 유지합니다.

체크포인트 작동 방식

지속성 작업을 직접 호출하면 SDK는 다음 순서를 따릅니다.

이 시퀀스를 통해 작업이 완료되면 결과가 안전하게 저장됩니다. 어느 시점에서든 함수가 중단되면 SDK는 마지막으로 완료된 체크포인트까지 재생할 수 있습니다.

재생 동작

일시 중지 또는 중단 후 함수가 재개되면 SDK가 재생을 수행합니다.

이 재생 메커니즘을 사용하려면 코드가 결정론적이어야 합니다. 입력 및 체크포인트 로그가 동일한 경우 함수는 동일한 시퀀스의 지속성 작업 직접 호출을 수행해야 합니다. SDK는 재생 중에 작업 이름과 유형이 체크포인트 로그와 일치하는지 확인하여 이를 적용합니다.

사용 가능한 지속성 작업

DurableContext는 다양한 조정 패턴에 대한 작업을 제공합니다. 각각의 지속성 작업은 체크포인트를 자동으로 생성하므로 언제든지 함수를 재개할 수 있습니다.

단계

자동 체크포인트 지정 및 재시도를 사용하여 비즈니스 로직을 실행합니다. 외부 서비스를 직접 호출하거나, 계산을 수행하거나, 체크포인트를 지정해야 하는 로직을 실행하는 작업에는 단계를 사용합니다. SDK는 단계 전후에 체크포인트를 생성하여 재생할 결과를 저장합니다.

TypeScript

const result = await context.step('process-payment', async () => {
  return await paymentService.charge(amount);
});
            

Python

result = context.step(
    lambda _: payment_service.charge(amount),
    name='process-payment'
)
            

단계는 구성 가능한 재시도 전략, 실행 시맨틱(최대 1회 또는 최소 1회) 및 사용자 지정 직렬화를 지원합니다.

대기

컴퓨팅 리소스를 소비하지 않고 지정된 기간 동안 실행을 일시 중지합니다. SDK는 체크포인트를 생성하고, 함수 간접 호출을 종료하고, 재개를 예약합니다. 대기가 완료되면 Lambda는 함수를 다시 간접 호출하고 SDK는 계속하기 전에 대기 지점까지 재생합니다.

TypeScript

// Wait 1 hour without charges
await context.wait({ seconds: 3600 });
            

Python

# Wait 1 hour without charges
context.wait(3600)
            

콜백

콜백을 사용하면 함수가 일시 중지되고 외부 시스템에서 입력을 제공할 때까지 대기합니다. 콜백을 생성할 때 SDK는 고유한 콜백 ID를 생성하고 체크포인트를 생성합니다. 이후 함수는 컴퓨팅 요금을 발생시키지 않고 일시 중지(간접 호출 종료)합니다. 외부 시스템은 SendDurableExecutionCallbackSuccess 또는 SendDurableExecutionCallbackFailure Lambda API를 사용하여 콜백 결과를 제출합니다. 콜백이 제출되면 Lambda는 함수를 다시 간접 호출하고 SDK는 콜백 지점으로 재생하며 함수는 콜백 결과를 계속 진행합니다.

SDK는 콜백 작업과 관련하여 2가지 메서드를 제공합니다.

createCallback: 콜백을 생성하고 promise와 콜백 ID를 모두 반환합니다. Lambda API를 사용하여 결과를 제출하는 외부 시스템으로 콜백 ID를 보냅니다.

TypeScript

const [promise, callbackId] = await context.createCallback('approval', {
  timeout: { hours: 24 }
});

await sendApprovalRequest(callbackId, requestData);
const approval = await promise;
            

Python

callback = context.create_callback(
    name='approval',
    config=CallbackConfig(timeout_seconds=86400)
)

context.step(
    lambda _: send_approval_request(callback.callback_id),
    name='send_request'
)

approval = callback.result()
            

waitForCallback: 콜백 생성 및 제출을 하나의 작업으로 결합하여 콜백 처리를 간소화합니다. SDK는 콜백을 생성하고, 콜백 ID로 제출자 함수를 실행하고, 결과를 기다립니다.

TypeScript

const result = await context.waitForCallback(
  'external-api',
  async (callbackId, ctx) => {
    await submitToExternalAPI(callbackId, requestData);
  },
  { timeout: { minutes: 30 } }
);
            

Python

result = context.wait_for_callback(
    lambda callback_id: submit_to_external_api(callback_id, request_data),
    name='external-api',
    config=WaitForCallbackConfig(timeout_seconds=1800)
)
            

함수가 무기한 대기하지 않도록 제한 시간을 구성합니다. 콜백 제한 시간이 초과되면 SDK가 CallbackError를 발생시키고 함수가 제한 시간 사례를 처리할 수 있습니다. 장기 실행 콜백에 하트비트 제한 시간을 사용하여 외부 시스템의 응답 중지 시기를 감지합니다.

휴먼 인 더 루프 워크플로, 외부 시스템 통합, 웹후크 응답 또는 외부 입력을 위해 실행을 일시 중지해야 하는 시나리오에는 콜백을 사용합니다.

병렬 실행

선택적 동시성 제어를 활용하여 여러 작업을 실행합니다. SDK는 병렬 실행을 관리하고, 각 작업에 대한 체크포인트를 생성하고, 완료 정책에 따라 실패를 처리합니다.

TypeScript

const results = await context.parallel([
  async (ctx) => ctx.step('task1', async () => processTask1()),
  async (ctx) => ctx.step('task2', async () => processTask2()),
  async (ctx) => ctx.step('task3', async () => processTask3())
]);
            

Python

results = context.parallel(
    lambda ctx: ctx.step(lambda _: process_task1(), name='task1'),
    lambda ctx: ctx.step(lambda _: process_task2(), name='task2'),
    lambda ctx: ctx.step(lambda _: process_task3(), name='task3')
)
            

parallel을 사용하여 독립적인 작업을 동시에 실행합니다.

맵

선택적 동시성 제어를 사용하여 배열의 각 항목에 대해 동시에 작업을 실행합니다. SDK는 동시 실행을 관리하고, 각 작업에 대한 체크포인트를 생성하고, 완료 정책에 따라 실패를 처리합니다.

TypeScript

const results = await context.map(itemArray, async (ctx, item, index) =>
  ctx.step('task', async () => processItem(item, index))
);
            

Python

results = context.map(
    item_array,
    lambda ctx, item, index: ctx.step(
        lambda _: process_item(item, index),
        name='task'
    )
)
            

map을 사용하여 동시성 제어로 배열을 처리합니다.

하위 컨텍스트

그룹화 작업에 필요한 격리된 실행 컨텍스트를 생성합니다. 하위 컨텍스트에는 자체 체크포인트 로그가 있으며 여러 개의 단계, 대기 및 기타 작업을 포함할 수 있습니다. SDK는 전체 하위 컨텍스트를 재시도 및 복구를 위한 단일 유닛으로 취급합니다.

하위 컨텍스트를 사용하여 복잡한 워크플로를 구성하거나, 하위 워크플로를 구현하거나, 함께 재시도해야 하는 작업을 격리할 수 있습니다.

TypeScript

const result = await context.runInChildContext(
  'batch-processing',
  async (childCtx) => {
    return await processBatch(childCtx, items);
  }
);
            

Python

result = context.run_in_child_context(
    lambda child_ctx: process_batch(child_ctx, items),
    name='batch-processing'
)
            

재생 메커니즘을 사용하려면 지속성 작업이 결정론적 순서에 따라 발생해야 합니다. 여러 하위 컨텍스트를 사용하면 여러 작업 스트림을 동시에 실행할 수 있으며, 결정론은 각 컨텍스트 내에 별도로 적용됩니다. 이를 통해 여러 개의 CPU 코어를 효율적으로 활용하는 고성능 함수를 구성할 수 있습니다.

예를 들어 2개의 하위 컨텍스트 A와 B를 시작한다고 가정합니다. 최초 간접 호출 시 컨텍스트 내의 단계는 A1, B1, B2, A2, A3 순서로 실행되고, 'A' 단계는 'B' 단계와 동시에 실행되었습니다. 재생 시 체크포인트 로그에서 결과가 검색되면 타이밍이 훨씬 빨라지고, B1, A1, A2, B2, A3 등의 다른 순서로 단계가 발생합니다. 'A' 단계가 올바른 순서(A1, A2, A3)로 발생했고 'B' 단계가 올바른 순서(B1, B2)로 발생했기 때문에 결정론의 필요성이 올바르게 충족되었습니다.

조건부 대기

시도 사이에 자동 체크포인트 지정을 포함하는 조건에 대해 폴링합니다. SDK는 검사 함수를 실행하고, 결과가 포함된 체크포인트를 생성하고, 전략에 따라 대기하고, 조건이 충족될 때까지 반복합니다.

TypeScript

const result = await context.waitForCondition(
  async (state, ctx) => {
    const status = await checkJobStatus(state.jobId);
    return { ...state, status };
  },
  {
    initialState: { jobId: 'job-123', status: 'pending' },
    waitStrategy: (state) => 
      state.status === 'completed' 
        ? { shouldContinue: false }
        : { shouldContinue: true, delay: { seconds: 30 } }
  }
);
            

Python

result = context.wait_for_condition(
    lambda state, ctx: check_job_status(state['jobId']),
    config=WaitForConditionConfig(
        initial_state={'jobId': 'job-123', 'status': 'pending'},
        wait_strategy=lambda state, attempt: 
            {'should_continue': False} if state['status'] == 'completed'
            else {'should_continue': True, 'delay': 30}
    )
)
            

외부 시스템을 폴링하거나, 리소스가 준비될 때까지 대기하거나, 백오프를 사용하여 재시도를 구현하는 경우 waitForCondition을 사용합니다.

함수 간접 호출

다른 Lambda 함수를 간접 호출하고 결과를 기다립니다. SDK는 체크포인트를 생성하고, 대상 함수를 간접 호출하고, 호출이 완료되면 함수를 재개합니다. 이를 통해 함수 구성 및 워크플로 분해가 활성화됩니다.

TypeScript

const result = await context.invoke(
  'invoke-processor',
  'arn:aws:lambda:us-east-1:123456789012:function:processor',
  { data: inputData }
);
            

Python

result = context.invoke(
    'arn:aws:lambda:us-east-1:123456789012:function:processor',
    {'data': input_data},
    name='invoke-processor'
)
            

지속성 작업 측정 방법

DurableContext를 통해 직접 호출하는 각각의 지속성 작업은 실행 진행 상황을 추적하고 상태 데이터를 저장하기 위해 체크포인트를 생성합니다. 이러한 작업에는 사용량에 따라 요금이 부과되고, 체크포인트에는 데이터 쓰기 및 보존 비용에 영향을 미치는 데이터가 포함될 수 있습니다. 저장된 데이터에는 간접 호출 이벤트 데이터, 단계에서 반환된 페이로드, 콜백 완료 시 전달된 데이터가 포함됩니다. 지속성 작업의 측정 방식을 이해하면 실행 비용을 추정하고 워크플로를 최적화하는 데 도움이 됩니다. 요금에 대한 자세한 내용은 Lambda 요금 페이지를 참조하세요.

페이로드 크기는 지속성 작업에서 유지되는 직렬화된 데이터의 크기를 나타냅니다. 데이터는 바이트 단위로 측정되고 크기는 작업에서 사용하는 직렬 변환기에 따라 달라질 수 있습니다. 작업의 페이로드는 성공적인 완료의 결과 자체이거나 작업이 실패한 경우 직렬화된 오류 객체일 수 있습니다.

기본 작업

기본 작업은 지속성 함수의 기본 구성 요소입니다.

콜백 작업

콜백 작업을 사용하면 함수가 일시 중지되고 외부 시스템에서 입력을 제공할 때까지 대기합니다. 이러한 작업은 콜백이 생성 및 완료될 때 체크포인트를 생성합니다.

복합 작업

복합 작업은 여러 지속성 작업을 결합하여 병렬 실행, 배열 처리 및 중첩된 컨텍스트와 같은 복잡한 조정 패턴을 처리합니다.

runInChildContext의 컨텍스트나 복합 작업 내부에서 사용하는 컨텍스트의 경우 256KB 미만의 결과는 직접 체크포인트가 지정됩니다. 이보다 더 큰 결과는 저장되지 않고 컨텍스트의 작업을 다시 처리하여 재생 중에 재구성됩니다.