Script

카테고리: 유틸리티 · 노드 타입 ID: utility-script

bytes/int/bool/string 포트에 대해 내장 스크립트(Python 부분집합)를 실행한다

개요

사용자 정의 입력·출력 포트(bytes, int, bool, string) 위에서 결정론적 샌드박스형 Python 문법 서브셋인 NodeCrypto 내장 스크립트를 실행한다.

임의 정밀도 정수 산술, 바이트 및 비트 슬라이싱(b[i:j], b.bits[i:j]), 루프와 조건문, 사용자 정의 함수, 24종의 내장 함수를 제공하여 표준 노드 조합만으로 표현하기 복잡한 커스텀 프로토콜 프레이밍이나 수학적 변환을 간결하게 작성할 수 있다. 전체 언어 명세는 내장 스크립트 레퍼런스를 참고한다.

사용 시점

TLV/ASN.1 헤더 조립, 커스텀 패킷 파싱, 유한체/모듈러 거듭제곱(`pow(a, e, m)`) 계산, 다단계 비트 조작을 하나의 노드 안에서 처리할 때 사용한다.
런타임 불변 조건을 검사하고 조건 위반 시 fail(code, message)로 명시적 오류를 발생시킬 때 사용한다.

파라미터 설정

Script 노드는 노드 카드와 속성창에서 다음 요소를 설정한다:

입력 및 출력 포트 테이블: 스크립트에서 읽을 입력 포트와 결과를 내보낼 출력 포트를 자유롭게 추가·삭제하고, 각 포트의 스크립트 식별자 이름과 데이터 타입(bytes, int, bool, string)을 지정한다.
스크립트 코드 에디터(code): 실행할 스크립트 본문을 작성한다. 선언된 모든 출력 포트 변수는 스크립트가 종료되기 전에 반드시 모든 실행 경로에서 값이 대입되어야 한다. 문법과 내장 함수는 문법 및 제어 흐름 및 내장 함수를 참고한다.
실행 한도 및 오류 통합: 최대 실행 스텝 수(maxSteps, 기본 100000), 최대 실행 시간(timeoutMs, 기본 1000ms), 그리고 선택적인 오류 통합(errorUnify)을 설정할 수 있다.

파라미터 (ID)	타입 및 기본값	노출 조건	설명 및 옵션
코드 `code`	`textarea` 기본값: `""` (비움)	항상 노출	실행할 내장 스크립트 소스 코드이다.
오류 단일화 `errorUnify`	`boolean` 기본값: `false` 변수 참조 지원 (`$var`: `bool`)	항상 노출	활성화하면 모든 스크립트 컴파일·런타임 오류를 지정한 단일 오류 코드와 메시지로 대체한다.
단일화 오류 코드 `errorUnifyCode`	`text` 기본값: `""` (비움) 변수 참조 지원 (`$var`: `string`)	`errorUnify`가 `true` 일 때	오류 통합 활성화 시 내보낼 오류 코드이다.
단일화 오류 메시지 `errorUnifyMessage`	`text` 기본값: `""` (비움) 변수 참조 지원 (`$var`: `string`)	`errorUnify`가 `true` 일 때	오류 통합 활성화 시 내보낼 오류 메시지이다.

포트 입출력 명세

포트 연결 규칙, 데이터 타입별 색상, 가변 포트 생성 방식은 포트 및 연결 문서를 참고한다.

입력 포트

항목	명세
포트 성격	가변 입력 포트(사용자 정의 스크립트 입력 변수)
캔버스 초기 기본값	0개(기본 템플릿은 입력 포트 없이 시작하며 필요에 따라 추가).
포트 개수 범위	입력 포트 0개 이상.
허용 데이터 타입	`Bytes`(`bytes`), `Int`(`int`), `Bool`(`bool`), `String`(`string`).
포트 추가 및 관리	속성창의 입력 포트 목록에서 포트를 추가·삭제하고 유효한 스크립트 식별자 이름과 타입을 지정한다.
평가 및 순서 규칙	각 입력 포트는 스크립트 전역 스코프에서 자신의 포트 이름과 동일한 읽기 가능한 변수로 바인딩된다.

출력 포트

항목	명세
포트 성격	가변 출력 포트(사용자 정의 스크립트 출력 변수)
캔버스 초기 기본값	출력 포트 1개(`out`, 타입 `Bytes`).
포트 개수 범위	출력 포트 1개 이상.
허용 데이터 타입	`Bytes`(`bytes`), `Int`(`int`), `Bool`(`bool`), `String`(`string`).
포트 추가 및 관리	속성창의 출력 포트 목록에서 포트를 추가·삭제하고 유효한 스크립트 식별자 이름과 타입을 지정한다.
평가 및 순서 규칙	스크립트가 정상 종료될 때 각 출력 포트 변수에 마지막으로 대입된 값이 해당 출력 포트로 내보내진다.

오류 케이스

실행 중 아래 조건이 발생하면 이 노드는 ERROR 상태가 되며, 출력 포트에 연결된 하위 노드는 실행되지 않는다. 오류 통합(errorUnify)을 활성화하면 아래의 모든 오류 코드가 사용자가 지정한 단일 오류 코드와 메시지로 대체된다.

오류 코드	기본 엔진 메시지	발생 조건
`BYTES_OUT_OF_RANGE`	인덱스 또는 구간이 값의 범위를 벗어났다	바이트/비트 인덱스 또는 슬라이스 구간이 버퍼의 유효 범위를 벗어났을 때 발생한다.
`BYTES_LENGTH_MISMATCH`	길이가 같아야 하는 두 값의 길이가 다르다	연결된 바이트 배열 피연산자들의 바이트 길이가 서로 일치하지 않을 때 발생한다.
`BYTES_INT_OVERFLOW`	정수가 지정한 길이·부호로 표현되지 않는다	정수 값이 지정한 고정 또는 포트 바이트 길이 안에 표현될 수 없을 때 발생한다.
`BYTES_INVALID_HEX`	16진 문자열이 올바르지 않는다	16진수 입력 필드에 16진수가 아닌 문자가 있거나 글자 수가 홀수일 때 발생한다.
`BYTES_INVALID_UTF8`	UTF-8로 해석할 수 없는 바이트열이다	바이트 시퀀스를 유효한 UTF-8로 해석할 수 없을 때 발생한다.
`BYTES_INVALID_ARGUMENT`	인자 값이 올바르지 않는다	비트 시프트 수, 바이트 길이, 음수 정수 등 인자 값이 유효하지 않을 때 발생한다.
`BYTES_SIZE_LIMIT`	결과 길이가 한도를 넘는다	결과 바이트 버퍼 길이가 엔진 최대 할당 한도를 초과할 때 발생한다.
`SCRIPT_COMPILE_ERROR`	스크립트가 검사를 통과하지 못했다	구문 오류, 타입 불일치, 미선언 식별자, 출력 포트 미대입 등 정적 검사에 실패했을 때 발생한다. 자세한 내용은 스크립트 오류 코드를 참고한다.
`SCRIPT_DIVISION_BY_ZERO`	0으로 나눌 수 없다	`//` 또는 `%` 연산의 오른쪽 피연산자가 `0`일 때 발생한다.
`SCRIPT_INDEX_OUT_OF_RANGE`	목록 인덱스 또는 구간이 범위를 벗어났다	바이트·비트·리스트 인덱스가 유효 범위를 벗어났을 때 발생한다.
`SCRIPT_INVALID_ARGUMENT`	인자 값이 올바르지 않는다	내장 함수에 허용 도메인을 벗어난 인자가 전달되었을 때 발생한다.
`SCRIPT_INVALID_ERROR_CODE`	fail의 code가 예약된 접두사를 사용했다	`fail(code, msg)`의 첫 인자에 예약된 시스템 접두사(`SCRIPT_`)를 사용했을 때 발생한다.
`SCRIPT_SIZE_LIMIT`	int 비트 수 또는 목록 길이가 한도를 넘었다	정수 비트 폭이나 바이트/리스트 크기가 샌드박스 한도를 초과했을 때 발생한다.
`SCRIPT_STEP_LIMIT`	실행 단계 한도를 넘었다	실행 단계 수가 `maxSteps`를 초과했을 때 발생한다.
`SCRIPT_TIMEOUT`	실행 시간 상한을 넘었다	실행 시간이 `timeoutMs`를 초과했을 때 발생한다.
`SCRIPT_INTERNAL_ERROR`	스크립트 해석기 내부 오류이다	스크립트 인터프리터 내부 예외가 발생했을 때 발생한다.

활용 예시

길이 접두사(2바이트 빅엔디안)가 붙은 페이로드 프레이밍하기

입력 바이트 배열 앞에 2바이트 길이를 붙여 출력한다.

Script 노드에 입력 포트 payload(Bytes)와 출력 포트 out(Bytes)을 설정한다.
코드 에디터에 out = i2b(len(payload), 2, "big") + payload를 작성하고 실행한다.