create-entity-server 0.0.9 → 0.0.23

package/template/samples/python/entity_server.py

@@ -8,7 +8,6 @@ Entity Server 클라이언트 (Python)
     ENTITY_SERVER_URL          http://localhost:47200
     ENTITY_SERVER_API_KEY      your-api-key
     ENTITY_SERVER_HMAC_SECRET  your-hmac-secret
-    ENTITY_PACKET_MAGIC_LEN    4   (서버 packet_magic_len 과 동일)
 
 사용 예:
     es = EntityServerClient()
@@ -40,25 +39,36 @@ from typing import Any
 
 import requests
 from cryptography.hazmat.primitives.ciphers.aead import XChaCha20Poly1305
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+from cryptography.hazmat.primitives import hashes
+
+import secrets as _secrets
 
 
 class EntityServerClient:
     def __init__(
         self,
-        base_url:    str = "",
-        api_key:     str = "",
-        hmac_secret: str = "",
-        timeout:     int = 10,
-        magic_len:   int = 4,
+        base_url:        str  = "",
+        api_key:         str  = "",
+        hmac_secret:     str  = "",
+        token:           str  = "",
+        timeout:         int  = 10,
+        encrypt_requests: bool = False,
     ) -> None:
-        self.base_url    = (base_url    or os.getenv("ENTITY_SERVER_URL",          "http://localhost:47200")).rstrip("/")
-        self.api_key     = api_key     or os.getenv("ENTITY_SERVER_API_KEY",     "")
-        self.hmac_secret = hmac_secret or os.getenv("ENTITY_SERVER_HMAC_SECRET", "")
-        self.timeout     = timeout
-        self.magic_len   = int(os.getenv("ENTITY_PACKET_MAGIC_LEN", magic_len))
-        self._session    = requests.Session()
+        self.base_url        = (base_url    or os.getenv("ENTITY_SERVER_URL",          "http://localhost:47200")).rstrip("/")
+        self.api_key         = api_key     or os.getenv("ENTITY_SERVER_API_KEY",     "")
+        self.hmac_secret     = hmac_secret or os.getenv("ENTITY_SERVER_HMAC_SECRET", "")
+        self.token           = token       or os.getenv("ENTITY_SERVER_TOKEN",       "")
+        self.timeout         = timeout
+        self.encrypt_requests = encrypt_requests
+        self._packet_encryption: bool = False
+        self._session        = requests.Session()
         self._active_tx_id: str | None = None
 
+    def set_token(self, token: str) -> None:
+        """JWT Bearer 토큰을 설정합니다. HMAC 모드와 배타적으로 사용해야 합니다."""
+        self.token = token
+
     # ─── 트랜잭션 ──────────────────────────────────────────────────────────────
 
     def trans_start(self) -> str:
@@ -89,58 +99,108 @@ class EntityServerClient:
         return self._request("POST", f"/v1/transaction/commit/{tx_id}")
 
     # ─── CRUD ─────────────────────────────────────────────────────────────────
+    def check_health(self) -> dict:
+        """서버 헬스 체크를 수행하고 패킷 암호화 활성 여부를 자동으로 감지합니다.
+        서버가 packet_encryption: true 를 응답하면 이후 모든 요청에 암호화가 자동 적용됩니다."""
+        resp = self._session.get(self.base_url + "/v1/health", timeout=self.timeout)
+        data = resp.json()
+        if data.get("packet_encryption"):
+            self._packet_encryption = True
+        return data
+    def get(self, entity: str, seq: int, *, skip_hooks: bool = False) -> dict:
+        """단건 조회. skip_hooks=True 이면 after_get 훅 미실행."""
+        q = "?skipHooks=true" if skip_hooks else ""
+        return self._request("GET", f"/v1/entity/{entity}/{seq}{q}")
+
+    def find(self, entity: str, conditions: dict, *, skip_hooks: bool = False) -> dict:
+        """
+        조건으로 단건 조회 (POST + conditions body).
+
+        - conditions: index/hash/unique 필드에만 필터 조건 사용 가능
+        - skip_hooks=True 이면 after_find 훅 미실행
+        """
+        q = "?skipHooks=true" if skip_hooks else ""
+        return self._request("POST", f"/v1/entity/{entity}/find{q}", body=conditions)
 
-    def get(self, entity: str, seq: int) -> dict:
-        """단건 조회"""
-        return self._request("GET", f"/v1/entity/{entity}/{seq}")
+    def list(
+        self,
+        entity: str,
+        page: int = 1,
+        limit: int = 20,
+        order_by: str | None = None,
+        order_dir: str | None = None,
+        fields: list[str] | None = None,
+        conditions: dict | None = None,
+    ) -> dict:
+        """
+        목록 조회 (POST + conditions body)
 
-    def list(self, entity: str, page: int = 1, limit: int = 20, order_by: str | None = None) -> dict:
-        """목록 조회"""
-        params: dict = {"page": page, "limit": limit}
+        - fields: 미지정 시 인덱스 필드만 반환 (기본, 가장 빠름). ['*'] 지정 시 전체 필드 반환
+        - conditions: index/hash/unique 필드에만 필터 조건 사용 가능
+        """
+        query_params: dict = {"page": page, "limit": limit}
         if order_by:
-            params["order_by"] = order_by
-        return self._request("GET", f"/v1/entity/{entity}/list", params=params)
+            query_params["order_by"] = f"-{order_by}" if order_dir == "DESC" else order_by
+        if fields:
+            query_params["fields"] = ",".join(fields)
+        return self._request("POST", f"/v1/entity/{entity}/list", body=conditions or {}, params=query_params)
 
-    def count(self, entity: str) -> dict:
-        """건수 조회"""
-        return self._request("GET", f"/v1/entity/{entity}/count")
+    def count(self, entity: str, conditions: dict | None = None) -> dict:
+        """건수 조회. conditions 는 list() 와 동일한 필터 규칙."""
+        return self._request("POST", f"/v1/entity/{entity}/count", body=conditions or {})
 
     def query(
         self,
-        entity:   str,
-        filter:   list[dict] | None = None,
-        page:     int = 1,
-        limit:    int = 20,
-        order_by: str | None = None,
+        entity: str,
+        sql: str,
+        params: list | None = None,
+        limit: int | None = None,
     ) -> dict:
         """
-        필터 검색
-        filter 예: [{"field": "status", "op": "eq", "value": "active"}]
+        커스텀 SQL 조회 (SELECT 전용, 인덱스 테이블만, JOIN 지원)
+
+        - SELECT 쿼리만 허용. SELECT * 불가. 최대 1000건.
+        - 사용자 입력은 반드시 params 로 바인딩 (SQL Injection 방지)
+
+        예::
+            es.query(
+                'order',
+                'SELECT o.seq, u.name FROM order o JOIN account u ON u.data_seq = o.account_seq WHERE o.status = ?',
+                params=['pending'],
+                limit=100,
+            )
         """
-        params: dict = {"page": page, "limit": limit}
-        if order_by:
-            params["order_by"] = order_by
-        return self._request("POST", f"/v1/entity/{entity}/query", body=filter or [], params=params)
+        body: dict[str, Any] = {"sql": sql, "params": params or []}
+        if limit is not None:
+            body["limit"] = limit
+        return self._request("POST", f"/v1/entity/{entity}/query", body=body)
 
-    def submit(self, entity: str, data: dict, *, transaction_id: str | None = None) -> dict:
+    def submit(self, entity: str, data: dict, *, transaction_id: str | None = None, skip_hooks: bool = False) -> dict:
         """
         생성 또는 수정
         data에 'seq' 포함 시 수정, 없으면 생성
         :param transaction_id: trans_start() 가 반환한 ID (생략 시 활성 트랜잭션 자동 사용)
+        :param skip_hooks: True 이면 before/after_insert, before/after_update 훅 미실행
         """
         tx_id = transaction_id or self._active_tx_id
         extra = {"X-Transaction-ID": tx_id} if tx_id else {}
-        return self._request("POST", f"/v1/entity/{entity}/submit", body=data, extra_headers=extra)
+        q = "?skipHooks=true" if skip_hooks else ""
+        return self._request("POST", f"/v1/entity/{entity}/submit{q}", body=data, extra_headers=extra)
 
-    def delete(self, entity: str, seq: int, *, transaction_id: str | None = None, hard: bool = False) -> dict:
-        """삭제
+    def delete(self, entity: str, seq: int, *, transaction_id: str | None = None, hard: bool = False, skip_hooks: bool = False) -> dict:
+        """
+        삭제
         :param transaction_id: trans_start() 가 반환한 ID (생략 시 활성 트랜잭션 자동 사용)
-        :param hard: True 시 하드 삭제
+        :param hard: True 시 하드(물리) 삭제. False(기본) 이면 소프트 삭제 (rollback 으로 복원 가능)
+        :param skip_hooks: True 이면 before/after_delete 훅 미실행
         """
-        params = {"hard": "true"} if hard else {}
+        query_parts: list[str] = []
+        if hard:       query_parts.append("hard=true")
+        if skip_hooks: query_parts.append("skipHooks=true")
+        q = "?" + "&".join(query_parts) if query_parts else ""
         tx_id = transaction_id or self._active_tx_id
         extra = {"X-Transaction-ID": tx_id} if tx_id else {}
-        return self._request("DELETE", f"/v1/entity/{entity}/delete/{seq}", params=params, extra_headers=extra)
+        return self._request("POST", f"/v1/entity/{entity}/delete/{seq}{q}", extra_headers=extra)
 
     def history(self, entity: str, seq: int, page: int = 1, limit: int = 50) -> dict:
         """변경 이력 조회"""
@@ -150,6 +210,112 @@ class EntityServerClient:
         """history seq 단위 롤백 (단건)"""
         return self._request("POST", f"/v1/entity/{entity}/rollback/{history_seq}")
 
+    def push(self, push_entity: str, payload: dict, *, transaction_id: str | None = None) -> dict:
+        """푸시 발송 트리거 엔티티에 submit합니다."""
+        return self.submit(push_entity, payload, transaction_id=transaction_id)
+
+    def push_log_list(self, page: int = 1, limit: int = 20, order_by: str | None = None) -> dict:
+        """push_log 목록 조회 헬퍼"""
+        return self.list("push_log", page=page, limit=limit, order_by=order_by)
+
+    def register_push_device(
+        self,
+        account_seq: int,
+        device_id: str,
+        push_token: str,
+        *,
+        platform: str | None = None,
+        device_type: str | None = None,
+        browser: str | None = None,
+        browser_version: str | None = None,
+        push_enabled: bool = True,
+        transaction_id: str | None = None,
+    ) -> dict:
+        """account_device 디바이스 등록/갱신 헬퍼 (push_token 단일 필드)"""
+        payload: dict[str, Any] = {
+            "id": device_id,
+            "account_seq": account_seq,
+            "push_token": push_token,
+            "push_enabled": push_enabled,
+        }
+        if platform:
+            payload["platform"] = platform
+        if device_type:
+            payload["device_type"] = device_type
+        if browser:
+            payload["browser"] = browser
+        if browser_version:
+            payload["browser_version"] = browser_version
+        return self.submit("account_device", payload, transaction_id=transaction_id)
+
+    def update_push_device_token(
+        self,
+        device_seq: int,
+        push_token: str,
+        *,
+        push_enabled: bool = True,
+        transaction_id: str | None = None,
+    ) -> dict:
+        """account_device.seq 기준 push_token 갱신 헬퍼"""
+        return self.submit(
+            "account_device",
+            {
+                "seq": device_seq,
+                "push_token": push_token,
+                "push_enabled": push_enabled,
+            },
+            transaction_id=transaction_id,
+        )
+
+    def disable_push_device(
+        self,
+        device_seq: int,
+        *,
+        transaction_id: str | None = None,
+    ) -> dict:
+        """account_device.seq 기준 푸시 수신 비활성화 헬퍼"""
+        return self.submit(
+            "account_device",
+            {
+                "seq": device_seq,
+                "push_enabled": False,
+            },
+            transaction_id=transaction_id,
+        )
+
+    def read_request_body(
+        self,
+        raw_body: bytes | str | None,
+        content_type: str = "application/json",
+        *,
+        require_encrypted: bool = False,
+    ) -> dict:
+        """요청 본문을 읽어 JSON으로 반환합니다.
+        - application/octet-stream: 암호 패킷 복호화
+        - 그 외: 평문 JSON 파싱
+        """
+        lowered = (content_type or "").lower()
+        is_encrypted = "application/octet-stream" in lowered
+
+        if require_encrypted and not is_encrypted:
+            raise RuntimeError(
+                "Encrypted request required: Content-Type must be application/octet-stream"
+            )
+
+        if is_encrypted:
+            if raw_body in (None, b"", ""):
+                raise RuntimeError("Encrypted request body is empty")
+
+            packet = raw_body if isinstance(raw_body, bytes) else raw_body.encode("utf-8")
+            return json.loads(self._decrypt_packet(packet))
+
+        if raw_body in (None, b"", ""):
+            return {}
+
+        if isinstance(raw_body, bytes):
+            return json.loads(raw_body.decode("utf-8"))
+        return json.loads(raw_body)
+
     # ─── 내부 ─────────────────────────────────────────────────────────────────
 
     def _request(
@@ -167,18 +333,35 @@ class EntityServerClient:
         else:
             signed_path = path
 
-        body_str  = json.dumps(body, ensure_ascii=False) if body is not None else ""
-        timestamp = str(int(time.time()))
-        nonce     = str(uuid.uuid4())
-        signature = self._sign(method, signed_path, timestamp, nonce, body_str)
-
-        headers: dict = {
-            "Content-Type": "application/json",
-            "X-API-Key":    self.api_key,
-            "X-Timestamp":  timestamp,
-            "X-Nonce":      nonce,
-            "X-Signature":  signature,
-        }
+        # 요청 바디 결정: encrypt_requests 시 POST 바디를 암호화
+        body_data: bytes | None = None  # 네트워크로 보낼 바이트
+        body_for_sign: bytes    = b""   # HMAC 서명 대상
+        content_type_header     = "application/json"
+
+        if body is not None:
+            json_bytes = json.dumps(body, ensure_ascii=False).encode("utf-8")
+            if self.encrypt_requests or self._packet_encryption:
+                encrypted = self._encrypt_packet(json_bytes)
+                body_data       = encrypted
+                body_for_sign   = encrypted
+                content_type_header = "application/octet-stream"
+            else:
+                body_data     = json_bytes
+                body_for_sign = json_bytes
+
+        is_hmac_mode = bool(self.api_key and self.hmac_secret)
+
+        headers: dict = {"Content-Type": content_type_header}
+        if is_hmac_mode:
+            timestamp = str(int(time.time()))
+            nonce     = str(uuid.uuid4())
+            signature = self._sign(method, signed_path, timestamp, nonce, body_for_sign)
+            headers["X-API-Key"]   = self.api_key
+            headers["X-Timestamp"] = timestamp
+            headers["X-Nonce"]     = nonce
+            headers["X-Signature"] = signature
+        elif self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
         if extra_headers:
             headers.update(extra_headers)
 
@@ -187,14 +370,14 @@ class EntityServerClient:
             method=method,
             url=url,
             headers=headers,
-            data=body_str.encode("utf-8") if body_str else None,
+            data=body_data,
             params=params,
             timeout=self.timeout,
         )
 
         # 패킷 암호화 응답: application/octet-stream → 복호화
-        content_type = resp.headers.get("Content-Type", "")
-        if "application/octet-stream" in content_type:
+        ct = resp.headers.get("Content-Type", "")
+        if "application/octet-stream" in ct:
             data = json.loads(self._decrypt_packet(resp.content))
         else:
             data = resp.json()
@@ -204,22 +387,58 @@ class EntityServerClient:
 
         return data
 
+    def _derive_packet_key(self) -> bytes:
+        """
+        패킷 암호화 키를 유도합니다.
+        - HMAC 모드: HKDF-SHA256(hmac_secret, "entity-server:packet-encryption")
+        - JWT  모드: SHA256(token)
+        """
+        if self.token and not self.hmac_secret:
+            return hashlib.sha256(self.token.encode("utf-8")).digest()
+        h = HKDF(
+            algorithm=hashes.SHA256(),
+            length=32,
+            salt=b"entity-server:hkdf:v1",
+            info=b"entity-server:packet-encryption",
+        )
+        return h.derive(self.hmac_secret.encode("utf-8"))
+
+    def _encrypt_packet(self, plaintext: bytes) -> bytes:
+        """
+        XChaCha20-Poly1305 패킷 암호화
+        포맷: [magic:magic_len][nonce:24][ciphertext+tag]
+        magic_len: 2 + key[31] % 14  (패킷 키에서 자동 파생)
+        """
+        key   = self._derive_packet_key()
+        magic_len = 2 + key[31] % 14
+        magic = _secrets.token_bytes(magic_len)
+        nonce = _secrets.token_bytes(24)
+        ct    = XChaCha20Poly1305(key).encrypt(nonce, plaintext, b"")
+        return magic + nonce + ct
+
     def _decrypt_packet(self, data: bytes) -> bytes:
         """
         XChaCha20-Poly1305 패킷 복호화
         포맷: [magic:magic_len][nonce:24][ciphertext+tag]
-        키: sha256(hmac_secret)
+        키: HKDF-SHA256(hmac_secret, "entity-server:packet-encryption")
         """
-        key        = hashlib.sha256(self.hmac_secret.encode("utf-8")).digest()
-        nonce      = data[self.magic_len : self.magic_len + 24]
-        ciphertext = data[self.magic_len + 24 :]
+        key        = self._derive_packet_key()
+        magic_len  = 2 + key[31] % 14
+        nonce      = data[magic_len : magic_len + 24]
+        ciphertext = data[magic_len + 24 :]
         return XChaCha20Poly1305(key).decrypt(nonce, ciphertext, b"")
 
-    def _sign(self, method: str, path: str, timestamp: str, nonce: str, body: str) -> str:
-        """HMAC-SHA256 서명"""
-        payload = "|".join([method, path, timestamp, nonce, body])
-        return hmac.new(
-            key=self.hmac_secret.encode("utf-8"),
-            msg=payload.encode("utf-8"),
-            digestmod=hashlib.sha256,
-        ).hexdigest()
+    def _sign(self, method: str, path: str, timestamp: str, nonce: str, body: bytes | str) -> str:
+        """
+        HMAC-SHA256 서명.
+        body 는 bytes(암호화된 바디 포함) 또는 str 모두 지원합니다.
+        """
+        prefix = f"{method}|{path}|{timestamp}|{nonce}|".encode("utf-8")
+        h = hmac.new(key=self.hmac_secret.encode("utf-8"), digestmod=hashlib.sha256)
+        h.update(prefix)
+        if isinstance(body, bytes):
+            if body:
+                h.update(body)
+        elif body:
+            h.update(body.encode("utf-8"))
+        return h.hexdigest()

package/template/samples/python/example.py

@@ -15,7 +15,7 @@ es = EntityServerClient()
 
 # 목록 조회
 result = es.list("product", page=1, limit=10)
-print(f"List: {len(result.get('data', []))} items")
+print(f"List: {result.get('data', {}).get('total', 0)} items")
 
 # 생성
 created = es.submit("product", {
@@ -34,16 +34,17 @@ print(f"Get: {item['data']['name']}")
 es.submit("product", {"seq": seq, "price": 39000})
 print("Updated")
 
-# 필터 검색
+# 커스텀 SQL 검색
 results = es.query("product",
-    filter=[{"field": "category", "op": "eq", "value": "peripherals"}],
-    page=1, limit=5,
+    sql="SELECT seq, name, category FROM product WHERE category = ?",
+    params=["peripherals"],
+    limit=5,
 )
-print(f"Query: {len(results.get('data', []))} results")
+print(f"Query: {len(results.get('data', {}).get('items', []))} results")
 
 # 이력 조회
 hist = es.history("product", seq)
-print(f"History: {len(hist.get('data', []))} entries")
+print(f"History: {hist.get('data', {}).get('total', 0)} entries")
 
 # 삭제
 es.delete("product", seq)

package/template/samples/react/src/example.tsx

@@ -4,16 +4,15 @@
  * 설정:
  *   1. .env 에 VITE_ENTITY_SERVER_URL=http://localhost:47200 추가
  *   2. 로그인 시 entityServer.login(email, password) 호출
- *   3. 이후 훅으로 데이터 조회/수정
+ *   3. 이후 client 메서드로 데이터 조회/수정
  */
 
-import { useState } from "react";
-import {
-    useEntityDelete,
-    useEntityGet,
-    useEntityList,
-    useEntitySubmit,
-} from "./hooks/useEntity";
+// @ts-ignore
+import { useEffect, useState } from "react";
+// @ts-ignore
+import { useEntityServer } from "entity-server-client/react";
+// @ts-ignore
+import type { EntityListResult } from "entity-server-client";
 
 interface Product {
     seq: number;
@@ -25,27 +24,35 @@ interface Product {
 // ─── 목록 컴포넌트 ─────────────────────────────────────────────────────────
 
 export function ProductList() {
+    const { client, isPending, error, del } = useEntityServer();
     const [page, setPage] = useState(1);
-    const { data, isLoading, error } = useEntityList<Product>("product", {
-        page,
-        limit: 20,
-    });
-    const deleteMut = useEntityDelete("product");
+    const [result, setResult] = useState<EntityListResult<Product> | null>(
+        null,
+    );
+    const [loading, setLoading] = useState(false);
+
+    useEffect(() => {
+        setLoading(true);
+        client
+            .list<Product>("product", { page, limit: 20 })
+            .then((r) => setResult(r.data))
+            .finally(() => setLoading(false));
+    }, [client, page]);
 
-    if (isLoading) return <p>로딩 중...</p>;
-    if (error) return <p>에러: {(error as Error).message}</p>;
+    if (loading) return <p>로딩 중...</p>;
+    if (error) return <p>에러: {error.message}</p>;
 
     return (
         <div>
-            <h2>상품 목록 ({data?.total ?? 0}건)</h2>
+            <h2>상품 목록 ({result?.total ?? 0}건)</h2>
             <ul>
-                {data?.data.map((item) => (
+                {result?.items.map((item) => (
                     <li key={item.seq}>
                         [{item.seq}] {item.name} — {item.price.toLocaleString()}
                         원
                         <button
-                            onClick={() => deleteMut.mutate(item.seq)}
-                            disabled={deleteMut.isPending}
+                            onClick={() => del("product", item.seq)}
+                            disabled={isPending}
                         >
                             삭제
                         </button>
@@ -67,10 +74,19 @@ export function ProductList() {
 // ─── 단건 조회 컴포넌트 ─────────────────────────────────────────────────────
 
 export function ProductDetail({ seq }: { seq: number }) {
-    const { data, isLoading } = useEntityGet<Product>("product", seq);
+    const { client } = useEntityServer();
+    const [item, setItem] = useState<Product | null>(null);
+    const [loading, setLoading] = useState(true);
+
+    useEffect(() => {
+        client
+            .get<Product>("product", seq)
+            .then((r) => setItem(r.data))
+            .catch(() => setItem(null))
+            .finally(() => setLoading(false));
+    }, [client, seq]);
 
-    if (isLoading) return <p>로딩 중...</p>;
-    const item = data?.data;
+    if (loading) return <p>로딩 중...</p>;
     if (!item) return <p>상품을 찾을 수 없습니다.</p>;
 
     return (
@@ -85,13 +101,13 @@ export function ProductDetail({ seq }: { seq: number }) {
 // ─── 생성/수정 폼 컴포넌트 ──────────────────────────────────────────────────
 
 export function ProductForm({ seq }: { seq?: number }) {
-    const submitMut = useEntitySubmit("product");
+    const { submit, isPending } = useEntityServer();
     const [form, setForm] = useState({ name: "", price: 0, category: "" });
 
     const handleSubmit = async (e: React.FormEvent) => {
         e.preventDefault();
         // seq 있으면 수정, 없으면 생성
-        await submitMut.mutateAsync(seq ? { ...form, seq } : form);
+        await submit("product", seq ? { ...form, seq } : form);
         alert(seq ? "수정 완료" : "등록 완료");
     };
 
@@ -119,7 +135,7 @@ export function ProductForm({ seq }: { seq?: number }) {
                     setForm((f) => ({ ...f, category: e.target.value }))
                 }
             />
-            <button type="submit" disabled={submitMut.isPending}>
+            <button type="submit" disabled={isPending}>
                 {seq ? "수정" : "등록"}
             </button>
         </form>