entity-server-client 0.2.0 → 0.2.2

package/src/hooks/useEntityServer.ts

@@ -1,50 +1,155 @@
-import { useMemo } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import {
     EntityServerClient,
     entityServer,
+    type EntityListParams,
+    type EntityQueryRequest,
     type EntityServerClientOptions,
 } from "../index";
 
 export interface UseEntityServerOptions extends EntityServerClientOptions {
     singleton?: boolean;
     tokenResolver?: () => string | undefined | null;
+    /**
+     * 페이지 새로고침 후 로그인 상태를 복원할 때 사용합니다.
+     * 이 값이 있으면 마운트 시 `client.refreshToken()`을 호출해 새 access_token을 발급받습니다.
+     * `keepSession: true`와 함께 사용하면 세션 유지 타이머도 재시작됩니다.
+     * 갱신 성공 시 `onTokenRefreshed` 콜백이 호출됩니다.
+     */
+    resumeSession?: string;
+}
+
+export interface UseEntityServerResult {
+    /** EntityServerClient 인스턴스 (read 전용 메서드 직접 호출 시 사용) */
+    client: EntityServerClient;
+    /** submit 또는 delete 진행 중 여부 */
+    isPending: boolean;
+    /** 마지막 mutation 에러 (없으면 null) */
+    error: Error | null;
+    /** 에러·결과 상태 초기화 */
+    reset: () => void;
+    /** entity 데이터 생성/수정 (seq 없으면 INSERT, 있으면 UPDATE) */
+    submit: (
+        entity: string,
+        data: Record<string, unknown>,
+        opts?: { transactionId?: string; skipHooks?: boolean },
+    ) => Promise<{ ok: boolean; seq: number }>;
+    /** entity 데이터 삭제 */
+    del: (
+        entity: string,
+        seq: number,
+        opts?: { transactionId?: string; hard?: boolean; skipHooks?: boolean },
+    ) => Promise<{ ok: boolean; deleted: number }>;
+    /** 커스텀 SQL 조회 */
+    query: <T = unknown>(
+        entity: string,
+        req: EntityQueryRequest,
+    ) => Promise<{ ok: boolean; data: { items: T[]; count: number } }>;
 }
 
 /**
- * React 환경에서 EntityServerClient 인스턴스를 반환합니다.
+ * React 환경에서 EntityServerClient 인스턴스와 mutation 상태를 반환합니다.
  *
- * - `singleton=true`(기본): 패키지 전역 `entityServer` 인스턴스를 반환합니다.
+ * - `singleton=true`(기본): 패키지 전역 `entityServer` 인스턴스를 사용합니다.
  * - `singleton=false`: 컴포넌트 스코프의 새 인스턴스를 생성합니다.
+ *
+ * @example
+ * ```tsx
+ * const { submit, del, isPending, error, reset } = useEntityServer();
+ *
+ * const handleSave = async () => {
+ *     await submit("account", { name: "홍길동" });
+ * };
+ * ```
  */
 export function useEntityServer(
     options: UseEntityServerOptions = {},
-): EntityServerClient {
+): UseEntityServerResult {
     const {
         singleton = true,
         tokenResolver,
         baseUrl,
         packetMagicLen,
         token,
+        resumeSession,
     } = options;
 
-    return useMemo(() => {
-        const client = singleton
+    const [isPending, setIsPending] = useState(false);
+    const [error, setError] = useState<Error | null>(null);
+
+    // 언마운트 후 setState 방지
+    const mountedRef = useRef(true);
+    useEffect(() => {
+        mountedRef.current = true;
+        return () => {
+            mountedRef.current = false;
+        };
+    }, []);
+
+    // 새로고침 후 로그인 상태 복원: resumeSession이 있으면 마운트 시 refreshToken() 호출
+    const resumeTokenRef = useRef(resumeSession);
+    useEffect(() => {
+        const storedRefreshToken = resumeTokenRef.current;
+        if (!storedRefreshToken) return;
+        client.refreshToken(storedRefreshToken).catch(() => {
+            // refresh_token 만료 등 — onSessionExpired 콜백이 이미 처리
+        });
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+
+    const client = useMemo(() => {
+        const c = singleton
             ? entityServer
-            : new EntityServerClient({
-                  baseUrl,
-                  packetMagicLen,
-                  token,
-              });
+            : new EntityServerClient({ baseUrl, packetMagicLen, token });
 
         if (singleton) {
-            client.configure({ baseUrl, packetMagicLen, token });
+            c.configure({ baseUrl, packetMagicLen, token });
         }
 
         const resolvedToken = tokenResolver?.();
         if (typeof resolvedToken === "string") {
-            client.setToken(resolvedToken);
+            c.setToken(resolvedToken);
         }
 
-        return client;
+        return c;
     }, [singleton, tokenResolver, baseUrl, packetMagicLen, token]);
+
+    const run = useCallback(async <T>(fn: () => Promise<T>): Promise<T> => {
+        if (mountedRef.current) {
+            setIsPending(true);
+            setError(null);
+        }
+        try {
+            const result = await fn();
+            return result;
+        } catch (err) {
+            const e = err instanceof Error ? err : new Error(String(err));
+            if (mountedRef.current) setError(e);
+            throw e;
+        } finally {
+            if (mountedRef.current) setIsPending(false);
+        }
+    }, []);
+
+    const submit = useCallback<UseEntityServerResult["submit"]>(
+        (entity, data, opts) => run(() => client.submit(entity, data, opts)),
+        [client, run],
+    );
+
+    const del = useCallback<UseEntityServerResult["del"]>(
+        (entity, seq, opts) => run(() => client.delete(entity, seq, opts)),
+        [client, run],
+    );
+
+    const query = useCallback<UseEntityServerResult["query"]>(
+        (entity, req) => run(() => client.query(entity, req)),
+        [client, run],
+    );
+
+    const reset = useCallback(() => {
+        setIsPending(false);
+        setError(null);
+    }, []);
+
+    return { client, isPending, error, reset, submit, del, query };
 }

package/src/index.ts

@@ -96,6 +96,35 @@ export interface EntityServerClientOptions {
      * 기본값: `false`
      */
     encryptRequests?: boolean;
+    /**
+     * `true`이면 `login()` 성공 후 Access Token 만료 전에 자동으로 갱신(silent refresh)합니다.
+     * 갱신 시점은 `expires_in - refreshBuffer` 초입니다.
+     *
+     * 갱신 성공 시 `onTokenRefreshed`, 실패 시 `onSessionExpired` 콜백이 호출됩니다.
+     *
+     * 기본값: `false`
+     */
+    keepSession?: boolean;
+    /**
+     * 만료 몇 초 전에 자동 갱신을 시도할지 설정합니다.
+     *
+     * 예: `expires_in = 3600`, `refreshBuffer = 60` → 3540초 후 갱신
+     *
+     * 기본값: `60`
+     */
+    refreshBuffer?: number;
+    /**
+     * 자동 갱신 성공 시 호출되는 콜백입니다.
+     * 새 `access_token`과 `expires_in`이 전달됩니다.
+     * 앱은 이 콜백에서 localStorage 등에 토큰을 저장해야 합니다.
+     */
+    onTokenRefreshed?: (accessToken: string, expiresIn: number) => void;
+    /**
+     * 세션 유지 갱신 실패 시 호출되는 콜백입니다.
+     * refresh_token 만료 등으로 재발급이 불가능한 경우입니다.
+     * 앱은 이 콜백에서 로그인 페이지로 이동하는 등의 처리를 해야 합니다.
+     */
+    onSessionExpired?: (error: Error) => void;
 }
 
 /**
@@ -151,16 +180,24 @@ export class EntityServerClient {
     private encryptRequests: boolean;
     private activeTxId: string | null = null;
 
+    // 세션 유지 관련
+    private keepSession: boolean;
+    private refreshBuffer: number;
+    private onTokenRefreshed?: (accessToken: string, expiresIn: number) => void;
+    private onSessionExpired?: (error: Error) => void;
+    private _sessionRefreshToken: string | null = null;
+    private _refreshTimer: ReturnType<typeof setTimeout> | null = null;
+
     /**
      * EntityServerClient 인스턴스를 생성합니다.
      *
      * 기본값:
      * - `baseUrl`: `VITE_ENTITY_SERVER_URL` 또는 `http://localhost:47200`
-     * - `packetMagicLen`: `VITE_PACKET_MAGIC_LEN` 또는 `4`
+     * - `packetMagicLen`: `VITE_ENTITY_SERVER_PACKET_MAGIC_LEN` 또는 `4`
      */
     constructor(options: EntityServerClientOptions = {}) {
         const envBaseUrl = readEnv("VITE_ENTITY_SERVER_URL");
-        const envMagicLen = readEnv("VITE_PACKET_MAGIC_LEN");
+        const envMagicLen = readEnv("VITE_ENTITY_SERVER_PACKET_MAGIC_LEN");
 
         this.baseUrl = (
             options.baseUrl ??
@@ -172,6 +209,10 @@ export class EntityServerClient {
         this.packetMagicLen =
             options.packetMagicLen ?? (envMagicLen ? Number(envMagicLen) : 4);
         this.encryptRequests = options.encryptRequests ?? false;
+        this.keepSession = options.keepSession ?? false;
+        this.refreshBuffer = options.refreshBuffer ?? 60;
+        this.onTokenRefreshed = options.onTokenRefreshed;
+        this.onSessionExpired = options.onSessionExpired;
     }
 
     /** baseUrl, token, packetMagicLen, encryptRequests 값을 런타임에 갱신합니다. */
@@ -188,6 +229,18 @@ export class EntityServerClient {
         if (typeof options.encryptRequests === "boolean") {
             this.encryptRequests = options.encryptRequests;
         }
+        if (typeof options.keepSession === "boolean") {
+            this.keepSession = options.keepSession;
+        }
+        if (typeof options.refreshBuffer === "number") {
+            this.refreshBuffer = options.refreshBuffer;
+        }
+        if (options.onTokenRefreshed) {
+            this.onTokenRefreshed = options.onTokenRefreshed;
+        }
+        if (options.onSessionExpired) {
+            this.onSessionExpired = options.onSessionExpired;
+        }
     }
 
     /** 인증 요청에 사용할 JWT Access Token을 설정합니다. */
@@ -205,6 +258,82 @@ export class EntityServerClient {
         return this.packetMagicLen;
     }
 
+    /**
+     * 자동 토큰 갱신 타이머를 시작합니다.
+     * @param refreshToken 갱신에 사용할 Refresh Token
+     * @param expiresIn Access Token의 유효 기간 (초)
+     */
+    private _scheduleKeepSession(
+        refreshToken: string,
+        expiresIn: number,
+    ): void {
+        this._clearRefreshTimer();
+        this._sessionRefreshToken = refreshToken;
+
+        const delayMs = Math.max((expiresIn - this.refreshBuffer) * 1000, 0);
+        this._refreshTimer = setTimeout(async () => {
+            if (!this._sessionRefreshToken) return;
+            try {
+                const result = await this.refreshToken(this._sessionRefreshToken);
+                this.onTokenRefreshed?.(result.access_token, result.expires_in);
+                // 갱신 성공 시 다음 만료 전 타이머 재예약
+                this._scheduleKeepSession(
+                    this._sessionRefreshToken,
+                    result.expires_in,
+                );
+            } catch (err) {
+                this._clearRefreshTimer();
+                this.onSessionExpired?.(
+                    err instanceof Error ? err : new Error(String(err)),
+                );
+            }
+        }, delayMs);
+    }
+
+    /** 자동 갱신 타이머를 정리합니다. */
+    private _clearRefreshTimer(): void {
+        if (this._refreshTimer !== null) {
+            clearTimeout(this._refreshTimer);
+            this._refreshTimer = null;
+        }
+    }
+
+    /**
+     * 세션 유지 타이머를 중지합니다.
+     * `logout()` 호출 시 자동으로 중지되므로 직접 호출이 필요한 경우는 드뭅니다.
+     */
+    stopKeepSession(): void {
+        this._clearRefreshTimer();
+        this._sessionRefreshToken = null;
+    }
+
+    /**
+     * 서버 헬스 체크를 수행하고 패킷 암호화 활성 여부를 자동으로 감지합니다.
+     *
+     * 서버가 `packet_encryption: true`를 응답하면 이후 모든 요청에 암호화가 자동 적용됩니다.
+     * 초기화 직후 또는 로그인 전에 호출하면 암호화 설정을 자동으로 구성할 수 있습니다.
+     *
+     * ```ts
+     * await client.checkHealth();
+     * await client.login(email, password); // 이후 요청은 암호화 자동 적용
+     * ```
+     *
+     * @returns `{ ok: true }` 또는 `{ ok: true, packet_encryption: true }`
+     */
+    async checkHealth(): Promise<{ ok: boolean; packet_encryption?: boolean }> {
+        const res = await fetch(`${this.baseUrl}/v1/health`, {
+            signal: AbortSignal.timeout(3000),
+        });
+        const data = (await res.json()) as {
+            ok: boolean;
+            packet_encryption?: boolean;
+        };
+        if (data.packet_encryption) {
+            this.encryptRequests = true;
+        }
+        return data;
+    }
+
     /** 로그인 후 `access_token`을 내부 상태에 저장합니다. */
     async login(
         email: string,
@@ -222,6 +351,12 @@ export class EntityServerClient {
             };
         }>("POST", "/v1/auth/login", { email, passwd: password }, false);
         this.token = data.data.access_token;
+        if (this.keepSession) {
+            this._scheduleKeepSession(
+                data.data.refresh_token,
+                data.data.expires_in,
+            );
+        }
         return data.data;
     }
 
@@ -233,9 +368,28 @@ export class EntityServerClient {
             data: { access_token: string; expires_in: number };
         }>("POST", "/v1/auth/refresh", { refresh_token: refreshToken }, false);
         this.token = data.data.access_token;
+        if (this.keepSession) {
+            this._scheduleKeepSession(refreshToken, data.data.expires_in);
+        }
         return data.data;
     }
 
+    /**
+     * 서버에 로그아웃을 요청하고 내부 토큰을 초기화합니다.
+     * refresh_token을 서버에 전달해 무효화합니다.
+     */
+    async logout(refreshToken: string): Promise<{ ok: boolean }> {
+        this.stopKeepSession();
+        const data = await this.request<{ ok: boolean }>(
+            "POST",
+            "/v1/auth/logout",
+            { refresh_token: refreshToken },
+            false,
+        );
+        this.token = "";
+        return data;
+    }
+
     /** 트랜잭션을 시작하고 활성 트랜잭션 ID를 저장합니다. */
     async transStart(): Promise<string> {
         const res = await this.request<{ ok: boolean; transaction_id: string }>(
@@ -570,7 +724,9 @@ export class EntityServerClient {
                 method !== "HEAD";
 
             if (shouldEncrypt) {
-                const plaintext = new TextEncoder().encode(JSON.stringify(body));
+                const plaintext = new TextEncoder().encode(
+                    JSON.stringify(body),
+                );
                 const encrypted = this.encryptPacket(plaintext);
                 headers["Content-Type"] = "application/octet-stream";
                 fetchBody = encrypted;