command

command는 XML 계약을 기준으로 서버 측 CLI 프로세스와 Web URL 호출을 실행하는 모듈입니다. transact 계약에서 CommandType을 C로 지정하면 RoutingCommandUri 규칙에 따라 /command/api/execution으로 라우팅됩니다.

책임 범위

계약에 등록된 실행 파일, 인자, 작업 디렉터리를 해석해 shell 없이 프로세스를 실행합니다.
HTTP 요청 계약을 읽어 URL, query string, header, authorization, body를 구성합니다.
{ @Parameter }, { #Parameter } 치환 규칙으로 요청 값을 실행 명령이나 Web 요청에 주입합니다.
실행 결과를 HandStack의 표준 응답 형식으로 반환하고, 필요 시 logger 모듈로 거래 로그를 전송합니다.

주요 API

메서드	경로	용도
`GET`	`/command/api/execution/has`	계약 캐시에 실행 ID가 있는지 확인합니다.
`GET`	`/command/api/execution/refresh`	계약 파일을 다시 읽어 캐시를 갱신합니다.
`GET`	`/command/api/execution/retrieve`	실행 계약 원문 또는 메타 정보를 조회합니다.
`GET`	`/command/api/execution/meta`	실행 계약의 입력/출력 메타 정보를 반환합니다.
`POST`	`/command/api/execution`	CLI 또는 Web 요청 계약을 실행합니다.

핵심 구현

Areas/command/Controllers/ExecutionController.cs: 외부 API 진입점입니다.
DataClient/CommandClient.cs: 계약 검색, 파라미터 바인딩, CLI/Web 실행을 담당합니다.
Extensions/CommandMapper.cs: XML 계약을 메모리 매핑으로 로드하고 refresh를 처리합니다.
Entity/ModuleConfigJson.cs: module.json의 설정 스키마입니다.

계약과 식별자

계약은 기본적으로 다음 위치에 둡니다.

contracts/command/{ApplicationID}/{ProjectID}/{TransactionID}.xml

실행 ID는 다음 형식으로 조회됩니다.

ApplicationID|ProjectID|TransactionID|CommandID

계약의 <commands>는 CLI 실행을, <requests>는 Web URL 호출을 정의합니다. CommandID는 계약의 id와 seq 조합으로 관리되므로, 같은 거래 파일 안에서 중복되지 않아야 합니다.

주요 설정

설정	설명
`ContractBasePath`	command XML 계약 루트 목록입니다.
`IsContractFileWatching`	계약 파일 변경 감시 여부입니다. 개발 환경에서는 편리하지만 운영에서는 변경 통제와 함께 사용합니다.
`DefaultCommandTimeout`	계약에 timeout이 없을 때 적용되는 기본 실행 제한 시간입니다.
`DefaultMaxOutputBytes`	CLI 실행 결과로 수집할 최대 출력 크기입니다.
`Security.AllowedExecutableBasePaths`	CLI 실행 파일을 허용할 기준 경로 목록입니다. 비어 있으면 운영 정책상 허용 범위를 별도로 검토해야 합니다.
`Security.BlockedForwardHeaders`	Web 요청으로 전달하지 않을 HTTP 헤더 목록입니다.
`LogServerUrl`	거래 로그를 전송할 `logger` API입니다.

transact 연동

transact 거래 계약에서는 CommandType을 C로 둡니다.

{
  "ServiceID": "CMD010",
  "CommandType": "C",
  "ReturnType": "Json"
}

transact/module.json의 라우팅은 환경별로 다음 형태를 사용합니다.

{
  "HDS|*|C|D": "http://localhost:8421/command/api/execution",
  "HDS|*|C|P": "http://localhost:8421/command/api/execution",
  "HDS|*|C|T": "http://localhost:8421/command/api/execution"
}

운영 주의사항

command는 서버 권한으로 외부 프로세스를 실행할 수 있으므로 계약 리뷰와 실행 파일 allowlist가 필수입니다.
shell 문자열을 조립하는 방식이 아니라 실행 파일과 인자를 분리해 선언해야 합니다.
Web 요청 계약에서 인증 헤더와 API Key를 사용할 때는 값 자체를 계약에 고정하지 말고 환경별 설정이나 요청 파라미터로 주입합니다.
운영 환경에서는 DefaultCommandTimeout, DefaultMaxOutputBytes, 로그 저장 정책을 서비스별로 검토합니다.

책임 범위​

주요 API​

핵심 구현​

계약과 식별자​

주요 설정​

transact 연동​

운영 주의사항​