Guard & Filter

Guard와 ExceptionHandler는 IPC 핸들러 앞뒤로 동작하는 파이프라인이다. Guard가 요청을 검증하고, ExceptionHandler가 에러를 구조화된 응답으로 변환한다.

파이프라인 흐름

요청 → Guard(canActivate) → Handler → 응답
         ↓ (실패)              ↓ (에러)
    ExceptionHandler   ExceptionHandler
         ↓                    ↓
       응답                  응답

1. 모든 Guard의 canActivate()를 순서대로 실행한다
2. Guard가 false를 반환하면 첫 번째 ExceptionHandler의 catch()에 에러를 전달한다
3. Guard 통과 후 핸들러를 실행한다
4. 핸들러에서 에러가 발생하면 첫 번째 ExceptionHandler의 catch()에 전달한다

IpcContext

Guard와 ExceptionHandler에 전달되는 컨텍스트 객체:

interface IpcContext {
  event: IpcMainInvokeEvent;  // Electron IPC 이벤트
  channel: string;            // IPC 채널 이름
  window: BrowserWindow;      // 등록된 윈도우
  args: unknown[];            // 핸들러 인자
}

IpcGuard

요청의 유효성을 검증한다. canActivate()가 false를 반환하면 요청을 거부한다.

interface IpcGuard {
  canActivate(ctx: IpcContext): boolean | Promise<boolean>;
}

커스텀 Guard 작성

import type { IpcGuard, IpcContext } from '@repo/electron-ipc';

class AuthGuard implements IpcGuard {
  canActivate(ctx: IpcContext): boolean {
    // 인증된 요청만 허용
    const token = ctx.args[0];
    return typeof token === 'string' && isValidToken(token);
  }
}

SenderGuard

패키지에 내장된 Guard. IPC 메시지가 등록된 윈도우의 webContents에서 온 것인지 검증한다.

import { SenderGuard } from '@repo/electron-ipc';

createApp({
  guards: [new SenderGuard()],
  // ...
});

내부 구현:

class SenderGuard implements IpcGuard {
  canActivate(ctx: IpcContext): boolean {
    return ctx.event.sender === ctx.window.webContents;
  }
}

IpcExceptionHandler

핸들러 실행 중 발생한 에러를 잡아 구조화된 응답으로 변환한다.

interface IpcExceptionHandler {
  catch(error: unknown, ctx: IpcContext): unknown;
}

커스텀 ExceptionHandler 작성

import type { IpcExceptionHandler, IpcContext } from '@repo/electron-ipc';

class ErrorHandler implements IpcExceptionHandler {
  catch(error: unknown, ctx: IpcContext) {
    const message = error instanceof Error ? error.message : 'Unknown error';
    return {
      success: false,
      error: message,
      channel: ctx.channel,
    };
  }
}

적용

Guard와 ExceptionHandler는 createApp()의 설정에서 배열로 전달한다:

createApp({
  guards: [new SenderGuard(), new AuthGuard()],
  exceptionHandlers: [new ErrorHandler()],
  modules: [MyModule],
  createWindow: () => new BrowserWindow({ /* ... */ }),
});

• Guards: 배열 순서대로 실행. 하나라도 false면 즉시 중단.
• Exception Handlers: Guard 실패 또는 핸들러 에러 시 첫 번째 handler의 catch()가 호출된다.

다음 단계

• API Reference — IpcGuard, IpcExceptionHandler 전체 시그니처
• AppConfig — guards, exceptionHandlers 설정 상세