Script

Script는 프런트엔드가 HTTP로 호출하는 선언형 백엔드 엔드포인트입니다. 서버 코드를 작성하지 않고 "무엇을 할지"를 JSON으로 선언하면 WEEGLOO 엔진이 대신 실행합니다. 인증, 조건 검사(guard), 연쇄 CRUD, 외부 API 호출, 값 가공처럼 프런트엔드를 받치는 전형적인 백엔드 배관(BFF, Backend-for-Frontend)을 Script 하나로 대체하는 것이 목표입니다.

이 문서 묶음은 Script 문법의 정본(reference)입니다. 개별 문법의 상세는 아래 이 그룹의 문서에서 나눠 다룹니다.

Script는 CMA에서 저작하고 실행합니다(Weegloo User 신원). 제품에 가입한 회원(ServiceUser) 신원으로는 ACMA에서도 같은 방식으로 쓸 수 있습니다. Script API는 이 두 관리 API(CMA, ACMA)에만 있고, 읽기 전용 전달 API(CDA, ACDA)에는 없습니다.

멘탈 모델

• 하나의 Script는 하나의 HTTP 엔드포인트입니다. 호출 메서드(method)로 어떤 Script를 실행할지 매칭합니다.
• 본문은 statements 배열입니다. 위에서 아래로 순차 실행됩니다. 일반 프로그래밍의 함수 본문과 같습니다.
• 코드가 아니라 선언입니다. 임의 코드(FaaS)를 넣는 것이 아니라, 정해진 statement 타입을 조합합니다. 사람이 손으로 짜기보다 AI 에이전트가 MCP로 생성하는 쪽에 맞춰 설계됐습니다.
• 값은 JSON Pointer 템플릿으로 흐릅니다. 앞 단계의 결과, 입력 payload, 변수를 { /pointer }로 참조해 다음 단계로 넘깁니다. 조건이나 계산이 필요하면 JsonLogic 연산자를 씁니다. 자세한 규칙은 값 표현식에서 다룹니다.

최상위 구조 (ScriptDefinition)

Script 하나는 다음 ScriptDefinition 구조로 정의합니다.

{
  "method": "Post",               // Get | Post | Put | Patch | Delete. 호출 시 매칭할 HTTP 메서드 (필수)
  "payloadSchema": { /* ... */ }, // (선택) JSON Schema. 있으면 실행 전에 요청 payload를 검증
  "executionMode": "Sync",        // "Sync" | "Async" (필수)
  "statements": [ /* Statement[]. 위에서 아래로 실행 (필수, 1개 이상) */ ]
}

payload는 JSON만 받습니다. 호출 body는 /payload 컨텍스트 루트로 접근합니다({ /payload/... }). 호출의 요청 HTTP 헤더는 /headers 루트로 참조합니다({ /headers/... }, 키는 소문자). 전체 컨텍스트 루트는 값 표현식에서 다룹니다.

요청과 응답

Script는 최종적으로 Return 문의 값을 호출자에게 돌려줍니다. 응답(또는 Async 폴링 결과)의 형태는 다음과 같습니다.

{
  "requestId": "…",     // 실행 식별자 (Async는 이 id로 결과를 폴링)
  "durationMs": 1234,   // 실행 소요(ms)
  "statusCode": 200,    // 도달한 Return의 statusCode (기본 200)
  "return": <value>     // Return.isError 가 false일 때만. 값이 null이면 ""
  // "error": <value>   // Return.isError 가 true일 때만(이때 "return"은 없음). 값이 null이면 ""
}

• return과 error는 동시에 나오지 않습니다. Return 문의 isError가 어느 쪽인지 결정합니다.
• Return 문에 도달하지 못한 채 Script가 끝나면 return과 error가 둘 다 없고 statusCode는 기본값(200)입니다.
• 값이 null이면 해당 필드는 빈 문자열 ""로 나옵니다.

Return의 value, isError, statusCode로 응답 본문과 상태 코드를 제어합니다. 자세한 내용은 Statement 카탈로그의 Return에서 다룹니다.

실행 모드: Sync와 Async

• 외부 I/O가 있으면 Async만 허용됩니다. 어떤 statement든 Http 외부 호출(ExternalIo)이나 Media 파일 인제스트(MediaIngest. url·base64)처럼 네트워크를 타는 작업이 하나라도 있으면 executionMode는 반드시 Async여야 하고, Sync로 저장하려 하면 저장 시점에 거부됩니다. 요청 스레드를 외부 지연으로 막지 않기 위해서입니다.
• 실행 위치의 차이일 뿐, 어느 쪽이든 결과는 Return 값입니다.

자세한 능력에서 모드로 이어지는 규칙과 한도는 실행 시맨틱, 제약, 보안에서 다룹니다.

최소 예시

요청 payload의 제목과 본문으로 게시글 Content를 만들고 바로 발행한 뒤, 만든 sys.id를 돌려줍니다.

{
  "method": "Post",
  "executionMode": "Sync",
  "statements": [
    { "type": "ResourceCreate", "resource": "Content",
      "contentType": { "sys": { "id": "ct_post" } },
      "fields": {
        "title": { "en-US": "{ /payload/fields/title }" },
        "body":  { "en-US": "{ /payload/fields/body }" }
      },
      "publish": true,
      "name": "post" },
 
    { "type": "Return", "value": { "id": "{ /post/sys/id }" }, "statusCode": 201 }
  ]
}

• ResourceCreate로 Content를 만들고 결과를 post라는 이름에 바인딩합니다.
• Return이 { "id": <새 Content id> }를 201로 돌려줍니다.
• Content의 fields 값이 로케일 맵({ "en-US": ... })인 이유는 값 표현식의 로케일 맵에서 다룹니다.

더 다양한 시나리오는 쿡북에 있습니다.

이 그룹의 문서

• 값 표현식: { /pointer } 참조, 리터럴, JsonLogic 연산과 조건, 컨텍스트 루트, 로케일 맵을 다룹니다. 문법의 핵심입니다.
• Statement 카탈로그: 17종 문(리소스 CRUD와 읽기, Http, SetVar, If, Loop, Parallel, Try, Return)의 필드와 결과를 다룹니다.
• 실행 시맨틱, 제약, 보안: 실행 순서, guard, 보상, 낙관적 잠금, 에러, 정적 제약과 플랜 한도, 보안 모델을 다룹니다.
• 쿡북: upsert, 크레딧 guard, LLM 프록시, 페이지네이션, 병렬, 결제 사가 등 완결된 예시를 다룹니다.
• Script 리소스와 엔드포인트: Script 리소스의 sys 구조와 저작, 실행(/execute) HTTP 엔드포인트 명세를 다룹니다.

처음이라면 이 페이지에서 값 표현식, Statement 카탈로그 순서로 읽는 것을 권합니다. 쿡북은 통째로 훑어도 좋습니다.