TL;DR

  • stellarium-ts는 RequestScript 리소스를 등록하고 로컬 또는 피어 노드에서 실행하는 Stellarium TypeScript 노드 구현체임.
  • Fastify 5 서버에 노드를 연결하고 리소스를 등록한 뒤 시작하면 SQLite 데이터베이스 생성, HTTP API 마운트, 요청 수신이 이뤄짐.
  • startingPeer를 설정하면 시작 피어에서 피어 목록과 리소스 목록을 가져오며, 기존 피어 목록은 유지됨.
  • 로컬 리소스 호출은 해당 노드에서 실행되고, 피어에서 학습한 리소스 호출은 해당 피어의 /run으로 전달됨.
  • /v1/peers, /v1/resources, /v1/run 등의 API로 피어와 리소스를 확인하고 RequestScript 요청을 실행할 수 있음.

stellarium-ts

  • stellarium-ts는 Stellarium 노드의 TypeScript 구현체임.

Stellarium이란?

  • Stellarium은 RequestScript 프로그래밍 언어를 기반으로 한 탈중앙화 API 플랫폼임.
  • 사용자는 자체 노드를 실행하고 피어와 리소스 및 계약을 공유함.
  • 이 패키지는 노드 구현체이며, Fastify 서버에 포함해 현재 프로세스에서 사용하는 RequestScript 리소스를 등록하고, 실행 중인 다른 노드에서 피어 및 리소스 목록을 선택적으로 가져올 수 있음.
  • 토론은 Discussions 탭이나 Discord(https://discord.gg/WWTWKmYWv6)에서 진행할 수 있음.

노드 실행

사전 요구 사항

  • Node.js 20 이상.
  • Fastify 5: 애플리케이션에서 생성해 노드에 전달함.
  • RequestScript: 노드에 등록하는 Resource 타입을 제공함.

설치

  • 노드 패키지와 애플리케이션이 직접 가져오는 패키지를 설치함.
  • 설치 대상은 stellarium-ts, fastify, requestscript임.

리소스 등록 및 시작

  • 리소스는 스크립트가 호출할 수 있는 호스트 객체임.
  • path와 name이 정규화된 이름을 구성하며, 예를 들어 com.example.Weather가 해당함.
  • 각 함수는 RequestScript 매개변수 및 반환 타입을 선언하고, exec는 현재 프로세스에서 실행됨.
  • 노드를 시작하기 전에 리소스를 등록해야 함. start는 SQLite 데이터베이스를 생성하고 HTTP API를 마운트한 뒤 수신을 시작함.
  • StellariumNodeOptions의 설정은 다음과 같음.
  • port: Fastify가 수신하는 포트이며 기본값은 3000임.
  • startingPeer: 부트스트랩할 피어의 출처이며 기본값은 없음. /v1 접미사를 포함하지 않음.
  • startingPeer를 생략하면 독립 실행으로 동작하며, 설정하면 이미 실행 중인 노드에서 피어와 리소스 정보를 복사함.
  • StellariumNode를 가져오면 dotenv가 로드되므로 작업 디렉터리의 .env 파일이 자동 적용됨.
  • BASE_URL은 이 노드가 호스팅하는 리소스에 저장되는 공개 URL 접두사임. 피어는 {BASE_URL}/run을 호출하며, 예시는 http://127.0.0.1:3000/v1임.
  • 다른 노드에서 학습한 피어와 리소스는 현재 작업 디렉터리의 requestscript.db에 저장되며, 파일은 시작 시 생성됨.

네트워크 참여

  • startingPeer가 설정되면 노드가 수신을 시작한 뒤 다음 요청을 수행함.
  • GET {startingPeer}/v1/peers: 현재 노드에 피어가 없을 때만 응답 목록을 저장하며, 기존 목록은 그대로 유지함.
  • GET {startingPeer}/v1/resources: 각 리소스를 해당 피어가 알린 baseUrl과 함께 저장함.
  • 현재 프로세스에 등록된 리소스를 지정하는 스크립트는 exec를 로컬에서 실행함.
  • 피어에서 학습한 리소스를 지정하는 스크립트는 해당 피어의 {baseUrl}/run에 RequestScript 요청을 POST하고, 피어의 returnValue를 반환함.

HTTP API

  • 경로는 /v1 아래에 마운트됨.
  • GET /v1/은 생존 확인 경로이며 { "hello": "world" }를 응답함.
  • GET /v1/peers는 노드에 저장된 피어를 { "peers": [{ "baseUrl", "name" }] } 형식으로 반환함.
  • GET /v1/resources는 이 노드에 등록된 리소스와 피어에서 학습한 리소스를 반환함.
  • POST /v1/run은 RequestScript 하나를 실행하며, 본문은 JSON 문자열임.
  • GET /v1/resources 응답에는 각 리소스의 path, name, baseUrl과 함수의 name, returnType, parameters가 포함됨. 함수 구현은 이를 호스팅하는 노드에 남아 있음.
  • POST /v1/run은 Content-Type: application/json으로 스크립트 소스를 JSON 문자열로 받으며, 선언은 request여야 함.
  • 실행 성공 시 200과 { "returnValue": ... }를 응답함. 요청이 아닌 스크립트에는 400과 { "error": "Invalid script" }를, 그 밖의 실패에는 500과 { "error": "Internal server error" }를 응답함.
  • 리소스는 const <name>: <path>.<ResourceName> 형식으로 바인딩하고 이름이 지정된 인수로 호출함. 언어 세부 사항은 RequestScript README에서 확인할 수 있음.
  • 예시 요청은 com.example.Weather 리소스의 temperature 함수를 city: "Oslo" 인수로 호출하며, 결과는 { "returnValue": 12 }임.

개발

  • 저장소는 pnpm을 사용함.
  • pnpm install로 의존성을 설치하고, pnpm build로 tsc를 실행해 dist/를 생성함. 빌드는 패키징 전에 실행되며, 패키지가 내보내는 대상은 dist/임.
  • pnpm dev는 src/server.ts 변경 시 다시 로드함.
  • 자체 프로세스에서 노드를 시작할 때는 앞서 설명한 것처럼 StellariumNode를 사용함.

기여

  • Stellarium의 백로그는 원문에서 ‘here’로 연결되어 있음.