freelang-editor 11.7.4

package/src/EXPRESS-WEBSOCKET.md

@@ -0,0 +1,391 @@
+# Express.fl WebSocket 가이드
+
+FreeLang v11의 **네이티브 WebSocket** (RFC 6455) 구현을 Express.fl 래퍼로 간편하게 사용합니다.
+
+---
+
+## 📡 WebSocket 기본
+
+### 서버 시작
+
+```lisp
+(ws-start 3000)
+;; 🌐 WebSocket 서버 시작 → ws://localhost:3000
+```
+
+### 클라이언트 연결 감지
+
+```lisp
+;; 클라이언트 연결
+(ws_on_connect_fn "on-connect-handler")
+
+[FUNC on-connect-handler :params [$req]
+  :body (do
+    (log-info "✅ 클라이언트 연결")
+    nil)
+]
+```
+
+### 메시지 수신
+
+```lisp
+(ws_on_message_fn "on-message-handler")
+
+[FUNC on-message-handler :params [$req]
+  :body (let [
+    msg (server_req_body $req)
+    data (json_parse $msg)
+    text (get $data "text")
+  ]
+    (do
+      (println (str "💬 메시지: " text))
+      nil))
+]
+```
+
+### 연결 종료
+
+```lisp
+(ws_on_close_fn "on-close-handler")
+
+[FUNC on-close-handler :params [$req]
+  :body (do
+    (log-info "❌ 클라이언트 종료")
+    nil)
+]
+```
+
+---
+
+## 📤 메시지 전송
+
+### 모든 클라이언트에게 브로드캐스트
+
+```lisp
+;; 문자열
+(ws-send-all "Hello everyone!")
+
+;; JSON
+(ws-send-json-all {
+  :type "notification"
+  :message "누군가 입장했습니다"
+  :timestamp (now_iso)
+})
+```
+
+### 특정 클라이언트에게 전송
+
+```lisp
+;; 문자열
+(ws-send-to "client-id-123" "Hello specific client")
+
+;; JSON
+(ws-send-json-to "client-id-123" {
+  :type "private"
+  :text "개인 메시지입니다"
+})
+```
+
+### 연결 종료
+
+```lisp
+(ws-close-conn "client-id-123" 1000)
+;; 코드 1000: 정상 종료
+;; 코드 1001: Going Away
+;; 코드 1002: Protocol Error
+;; 코드 1003: Unsupported Data
+;; 코드 1008: Policy Violation
+```
+
+---
+
+## 📊 상태 조회
+
+### 온라인 클라이언트 수
+
+```lisp
+(let [count (ws-client-count)]
+  (println (str "온라인: " count "명")))
+```
+
+### 모든 클라이언트 ID
+
+```lisp
+(let [clients (ws-client-list)]
+  (println clients))
+;; → ["client-1", "client-2", "client-3"]
+```
+
+---
+
+## 💬 실전 예제: 채팅
+
+### 상태 관리
+
+```lisp
+(define *users* {})        ;; {"client-id": "username"}
+(define *messages* [])      ;; [{from, text, timestamp}]
+```
+
+### 핸들러 구현
+
+```lisp
+[FUNC on-connect :params [$req]
+  :body (let [id (server_req_id)]
+    (ws-send-json-to id {
+      :type "welcome"
+      :message "채팅방 입장"
+      :online (ws-client-count)
+    }))
+]
+
+[FUNC on-message :params [$req]
+  :body (let [
+    data (json_parse (server_req_body $req))
+    username (get $data "username")
+    text (get $data "text")
+  ]
+    (do
+      ;; 사용자 등록
+      (set! *users* (json_set *users* (server_req_id) username))
+
+      ;; 메시지 저장
+      (set! *messages* (append *messages* [{
+        :from username
+        :text text
+        :timestamp (now_iso)
+      }]))
+
+      ;; 브로드캐스트
+      (ws-send-json-all {
+        :type "message"
+        :from username
+        :text text
+        :timestamp (now_iso)
+      })))
+]
+
+[FUNC on-close :params [$req]
+  :body (do
+    (set! *users* (json_del *users* (server_req_id)))
+    (ws-send-json-all {
+      :type "user_left"
+      :online (ws-client-count)
+    }))
+]
+```
+
+---
+
+## 🔄 HTTP + WebSocket 혼합
+
+### HTTP API로 기존 메시지 조회
+
+```lisp
+[FUNC api-messages :params [$req]
+  :body (res-json {
+    :total (len *messages*)
+    :messages *messages*
+  })
+]
+
+(app-get "/api/messages" "api-messages")
+```
+
+### 클라이언트 예제
+
+```html
+<script>
+  const ws = new WebSocket("ws://localhost:3000");
+  
+  // 연결
+  ws.onopen = () => {
+    ws.send(JSON.stringify({
+      type: "join",
+      username: "홍길동",
+      text: "안녕하세요"
+    }));
+  };
+  
+  // 메시지 수신
+  ws.onmessage = (e) => {
+    const msg = JSON.parse(e.data);
+    console.log(`${msg.from}: ${msg.text}`);
+  };
+  
+  // 종료
+  ws.onclose = () => console.log("연결 끊김");
+</script>
+```
+
+---
+
+## ⚡ 성능 팁
+
+### 배치 브로드캐스트 피하기
+
+```lisp
+;; ❌ 느림: N개 메시지마다 브로드캐스트
+(map (fn [msg] (ws-send-all $msg)) messages)
+
+;; ✅ 빠름: 한 번에 전송
+(ws-send-json-all {
+  :type "batch"
+  :messages messages
+})
+```
+
+### 캐시와 함께 사용
+
+```lisp
+;; 최근 100개 메시지 캐시
+(cache_set "recent_messages" *messages* 3600000)
+
+;; 조회
+[FUNC api-recent :params [$req]
+  :body (let [cached (cache_get "recent_messages")]
+    (res-json { :messages $cached }))
+]
+```
+
+---
+
+## 🔐 인증 + WebSocket
+
+### JWT 토큰 검증
+
+```lisp
+[FUNC on-connect :params [$req]
+  :body (let [
+    token (server_req_header $req "Authorization")
+    payload (auth_jwt_verify (str_split token " " 2) "secret")
+  ]
+    (if payload
+      (do
+        (log-info (str "✅ 인증됨: " (get $payload "username")))
+        nil)
+      (do
+        (log-error "❌ 인증 실패")
+        (ws-close-conn (server_req_id) 1008)))
+  )
+]
+```
+
+---
+
+## 📈 확장 예제
+
+### 멀티 채팅방
+
+```lisp
+(define *rooms* {})  ;; {"room_id": [messages]}
+
+[FUNC on-message :params [$req]
+  :body (let [
+    room (get (json_parse (server_req_body $req)) "room")
+    msg (get (json_parse (server_req_body $req)) "text")
+  ]
+    (do
+      ;; 방별 저장
+      (set! *rooms* (json_set *rooms* room
+        (append (get *rooms* room []) [msg])))
+      
+      ;; 방의 클라이언트들에게만 전송 (tag를 사용한 필터링)
+      (ws-send-json-all {
+        :room room
+        :message msg
+      })))
+]
+```
+
+### 사용자 상태 동기화
+
+```lisp
+(define *presence* {})  ;; {"client_id": {name, status, location}}
+
+[FUNC update-presence :params [$req]
+  :body (let [
+    id (server_req_id)
+    data (json_parse (server_req_body $req))
+  ]
+    (do
+      (set! *presence* (json_set *presence* id $data))
+      ;; 모두에게 알림
+      (ws-send-json-all {
+        :type "presence_update"
+        :presence *presence*
+      })))
+]
+```
+
+---
+
+## 🧪 테스트
+
+### 서버 시작
+
+```bash
+node bootstrap.js run express-chat.fl
+```
+
+### 클라이언트 테스트 (wscat)
+
+```bash
+npm install -g wscat
+
+# 연결
+wscat -c ws://localhost:3000
+
+# 메시지 전송 (JSON)
+{"type":"join","username":"Alice","text":"안녕하세요"}
+
+# HTTP API 확인
+curl http://localhost:3000/api/messages
+curl http://localhost:3000/api/users
+curl http://localhost:3000/health
+```
+
+### 성능 테스트
+
+```bash
+# 1000개 메시지 전송
+for i in {1..1000}; do
+  echo "{\"text\":\"msg $i\"}" | wscat -c ws://localhost:3000
+done
+```
+
+---
+
+## 📋 체크리스트
+
+- [ ] WebSocket 핸들러 3개 (connect, message, close) 등록
+- [ ] 클라이언트별 ID 저장 (`server_req_id()`)
+- [ ] 상태 변수로 사용자/메시지 추적
+- [ ] JSON 직렬화/역직렬화 처리
+- [ ] HTTP API로 상태 조회 제공
+- [ ] 에러 처리 (catch, try)
+- [ ] 로깅 (log-info, log-error)
+- [ ] 캐싱 (선택: 성능 향상용)
+
+---
+
+## 🔗 관련 함수
+
+### 기본 WS 함수 (stdlib-ws.ts)
+- `ws_start(port)` — 서버 시작
+- `ws_send(client, msg)` — 전송
+- `ws_broadcast(msg)` — 브로드캐스트
+- `ws_close(client, code)` — 종료
+- `ws_count()` — 클라이언트 수
+- `ws_clients()` — 클라이언트 목록
+
+### Express.fl 래퍼
+- `ws-start` — 간편한 서버 시작
+- `ws-send-all` — 로깅과 함께 브로드캐스트
+- `ws-send-to` — 로깅과 함께 개별 전송
+- `ws-close-conn` — 안전한 종료
+
+### HTTP + WS 통합
+- `app-listen` — HTTP + WS 함께 시작
+- `server_req_id()` — WS 연결 ID
+- `server_req_body()` — WS 메시지 본문

package/src/LOGGING-GUIDE.md

@@ -0,0 +1,354 @@
+# Deterministic Logging — 결정론 로깅 가이드
+
+> SHA256 기반 재현 가능한 로깅으로 AI 에이전트 실행을 검증합니다.
+
+---
+
+## 핵심 아이디어
+
+### 문제: 불안정한 AI 실행
+
+```
+같은 입력 → 다른 결과?
+          → 다른 실행 시간?
+          → 디버깅 불가능?
+```
+
+### 해결책: 결정론 로깅
+
+```
+같은 입력 → 같은 SHA256 해시
+         → 같은 결과
+         → 재현 가능
+         → 안전한 AI 배포
+```
+
+---
+
+## 기본 사용법
+
+### 1단계: 로그 엔트리 생성
+
+```lisp
+(load "src/logging-deterministic.fl")
+
+(let [$entry (log-entry
+  1                           ; step
+  "fetch-users"               ; task name
+  { :url "api.example.com" }  ; input
+  [{ :id 1 } { :id 2 }]       ; output
+)]
+  (println $entry))
+```
+
+**생성된 엔트리**:
+```
+{
+  :step 1
+  :task-name "fetch-users"
+  :timestamp 1704067200000
+  :input { :url "api.example.com" }
+  :output [{ :id 1 } { :id 2 }]
+  :input-hash "abc123..."    ; SHA256(input)
+  :output-hash "def456..."   ; SHA256(output)
+}
+```
+
+### 2단계: 로그 검증
+
+```lisp
+(let [$verify (log-verify $entry)]
+  (println {
+    :valid (get $verify :valid)
+    :input-ok (get $verify :input-verified)
+    :output-ok (get $verify :output-verified)
+  }))
+```
+
+**출력**:
+```
+{
+  :valid true
+  :input-ok true
+  :output-ok true
+}
+```
+
+---
+
+## 고급: 배치 검증
+
+### 로그 수집
+
+```lisp
+(let [$log (execution-log)]
+  (let [$log (log-append $log $entry1)]
+    (let [$log (log-append $log $entry2)]
+      (let [$log (log-append $log $entry3)]
+        (println $log)))))
+```
+
+**로그 구조**:
+```
+{
+  :id "sess_1704067200000"
+  :created-at 1704067200000
+  :entries [
+    { :step 1 :task-name "fetch" ... }
+    { :step 2 :task-name "process" ... }
+    { :step 3 :task-name "save" ... }
+  ]
+}
+```
+
+### 전체 검증
+
+```lisp
+(let [$results (log-verify-all $log)]
+  (println {
+    :total (get $results :total-entries)
+    :all-valid (get $results :all-valid)
+    :individual (get $results :results)
+  }))
+```
+
+**출력**:
+```
+{
+  :total 3
+  :all-valid true
+  :individual [
+    { :valid true :input-verified true :output-verified true }
+    { :valid true :input-verified true :output-verified true }
+    { :valid true :input-verified true :output-verified true }
+  ]
+}
+```
+
+---
+
+## 재현 (Replay)
+
+### 로그 재현
+
+```lisp
+(let [$replay (log-replay $log)]
+  (println {
+    :total-steps (get $replay :total-steps)
+    :results (get $replay :replay-results)
+  }))
+```
+
+**출력**:
+```
+{
+  :total-steps 3
+  :replay-results [
+    {
+      :step 1
+      :task-name "fetch"
+      :input-hash "abc123..."
+      :output-hash "def456..."
+      :verified true
+    }
+    ...
+  ]
+}
+```
+
+---
+
+## 실제 예제
+
+### 예제 1: Task 실행 로깅
+
+```lisp
+(load "src/agent-dsl.fl")
+(load "src/logging-deterministic.fl")
+
+(let [$state (agent-state)]
+  (let [$log (execution-log)]
+
+    ; Task 정의
+    (let [$task (make-task "multiply" (fn [$ctx]
+      (let [$input { :a 10 :b 20 }]
+        (let [$output { :result (* 10 20) }]
+          (do
+            ; 로그 추가
+            (let [$entry (log-entry 1 "multiply" $input $output)]
+              (set! $log (log-append $log $entry))
+            )
+            $output
+          )
+        )
+      )
+    ))]
+
+      ; 실행
+      (let [$result (agent-run [$task])]
+        (do
+          (println (str "실행 완료: " (get $result :status)))
+          (println (str "로그 엔트리: " (length (get $log :entries))))
+          
+          ; 검증
+          (let [$verification (log-verify-all $log)]
+            (println (str "모두 검증됨: " (get $verification :all-valid)))
+          )
+        )
+      )
+    )
+  )
+)
+```
+
+### 예제 2: HTTP 요청 로깅
+
+```lisp
+(let [$entry (log-entry
+  1
+  "fetch-api"
+  { :method "GET" :url "https://api.example.com/users" }
+  (json-parse (http-get "https://api.example.com/users"))
+)]
+  (let [$verify (log-verify $entry)]
+    (println (str "HTTP 요청 검증: " (get $verify :valid)))
+  )
+)
+```
+
+### 예제 3: 에러 추적
+
+```lisp
+(let [$error-entry (log-entry
+  1
+  "failed-task"
+  { :input "..." }
+  { :error "Connection timeout" }
+)]
+  (let [$verify (log-verify $error-entry)]
+    (if (get $verify :valid)
+      (println "에러도 재현 가능하게 기록됨")
+      (println "검증 실패")
+    )
+  )
+)
+```
+
+---
+
+## 검증 알고리즘
+
+### SHA256 결정론성
+
+```
+입력 (JSON 정규화)
+  ↓
+JSON String 변환
+  ↓
+SHA256 해시 계산
+  ↓
+저장된 해시와 비교
+  ↓
+✓ 일치 → 검증 성공
+✗ 불일치 → 검증 실패
+```
+
+### 예시
+
+```lisp
+; 입력
+(let [$data { :name "Alice" :age 30 }]
+  (let [$hash1 (sha256-deterministic $data)]
+    (let [$hash2 (sha256-deterministic { :name "Alice" :age 30 })]
+      (println (= $hash1 $hash2))  ; true
+    )
+  )
+)
+
+; 다른 입력
+(let [$data1 { :name "Alice" }]
+  (let [$data2 { :name "Bob" }]
+    (let [$hash1 (sha256-deterministic $data1)]
+      (let [$hash2 (sha256-deterministic $data2)]
+        (println (= $hash1 $hash2))  ; false
+      )
+    )
+  )
+)
+```
+
+---
+
+## 베스트 프랙티스
+
+### ✅ 추천
+
+```lisp
+; 1. 모든 Task 실행을 로깅
+(let [$entry (log-entry $step $name $input $output)]
+  (set! $log (log-append $log $entry))
+)
+
+; 2. 주기적으로 검증
+(log-verify-all $log)
+
+; 3. 로그를 저장소에 저장
+(storage-save $storage "logs" $session-id $log)
+```
+
+### ❌ 피해야 할 것
+
+```lisp
+; X 로깅하지 않음
+(agent-run [$task])  ; 로그 기록 없음
+
+; X 부분 검증
+(log-verify $entry)  ; 전체 배치 검증 필요
+
+; X 로그 저장 안 함
+; → 나중에 재현 불가능
+```
+
+---
+
+## API 레퍼런스
+
+| 함수 | 입력 | 출력 |
+|------|------|------|
+| `(log-entry step name input output)` | 4개 | Entry |
+| `(sha256-deterministic data)` | JSON | Hash |
+| `(log-verify entry)` | Entry | {valid, ...} |
+| `(execution-log)` | 없음 | Log |
+| `(log-append log entry)` | Log, Entry | Log |
+| `(log-verify-all log)` | Log | {total, valid, results} |
+| `(log-replay log)` | Log | {steps, results} |
+
+---
+
+## FAQ
+
+### Q: 왜 SHA256인가?
+**A**: 빠르고, 결정론적이고, 널리 지원됩니다. AI 배포에 충분합니다.
+
+### Q: 민감한 데이터는?
+**A**: 로그에 민감 정보를 포함하지 마세요. 대신 해시만 저장하세요.
+
+```lisp
+; 나쁜 예
+(log-entry 1 "login" { :password "secret" } {...})
+
+; 좋은 예
+(log-entry 1 "login" { :user-id "abc" } {...})
+```
+
+### Q: 로그 크기가 크면?
+**A**: 저장소에 분산 저장하고, 필요시만 로드하세요.
+
+```lisp
+(storage-save $storage "logs" (str "batch-" $batch-id) $log)
+(storage-load $storage "logs" (str "batch-" $batch-id))
+```
+
+---
+
+**🔒 AI 에이전트를 SHA256으로 안전하게 검증하세요!**