Context

Context는 Sonamu API 메서드 실행 중에 HTTP 요청과 관련된 정보에 접근할 수 있게 해주는 객체입니다. API 메서드의 파라미터로 주입받아 사용할 수 있으며, AsyncLocalStorage를 통해 관리됩니다.

타입 정의

type Context = {
  request: FastifyRequest;
  reply: FastifyReply;
  headers: IncomingHttpHeaders;
  createSSE: <T extends ZodObject>(events: T) => ReturnType<typeof createSSEFactory<T>>;
  naiteStore: NaiteStore;
  locale: string;
  /** buffer 모드에서 업로드된 파일 */
  bufferedFiles?: BufferedFile[];
  /** stream 모드에서 업로드된 파일 */
  uploadedFiles?: UploadedFile[];
} & AuthContext &
  ContextExtend;

Context 타입은 **교차 타입(Intersection Type, &)**으로 구성됩니다:

기본 Context 객체 (request, reply 등)
AuthContext: 인증 관련 속성 (user, session)
ContextExtend: 프로젝트별 확장 속성

이러한 구조 덕분에 Context는 타입 안전성을 유지하면서 확장 가능합니다.

Context 속성

request

request: FastifyRequest;

현재 HTTP 요청을 나타내는 Fastify Request 객체입니다. 요청 URL, 메서드, 쿼리 파라미터 등에 접근할 수 있습니다.

reply

reply: FastifyReply;

현재 HTTP 응답을 나타내는 Fastify Reply 객체입니다. 응답 헤더 설정, 상태 코드 변경 등에 사용할 수 있습니다.

headers

headers: IncomingHttpHeaders;

HTTP 요청 헤더입니다. request.headers와 동일한 값으로, 편의를 위해 제공됩니다.

createSSE

createSSE: <T extends ZodObject>(events: T) => ReturnType<typeof createSSEFactory<T>>;

Server-Sent Events(SSE) 스트림을 생성하는 함수입니다. Zod 스키마를 사용하여 타입 안전한 이벤트 스트림을 만들 수 있습니다. 사용 예시:

import { z } from "zod";

class MyModelClass extends BaseModelClass {
  @api()
  @stream({
    type: "sse",
    events: z.object({
      progress: z.object({ percent: z.number() }),
      complete: z.object({ result: z.string() }),
    }),
  })
  async processData(ctx: Context) {
    const sse = ctx.createSSE({
      progress: z.object({ percent: z.number() }),
      complete: z.object({ result: z.string() }),
    });

    // 진행률 전송
    await sse.publish("progress", { percent: 50 });

    // 완료 이벤트 전송
    await sse.publish("complete", { result: "done" });

    return sse.getResponse();
  }
}

naiteStore

naiteStore: NaiteStore;

Naite 테스팅 프레임워크에서 사용하는 저장소입니다. 테스트 중 모킹된 데이터나 스냅샷 정보를 저장하는 용도로 사용됩니다.

locale

locale: string;

현재 요청의 locale(언어 설정)입니다. 항상 값이 존재합니다. Accept-Language 헤더를 파싱하여 지원하는 locale 중 하나를 자동으로 선택하며, 일치하는 locale이 없으면 defaultLocale이 사용됩니다. 설정 예시:

// sonamu.config.ts
export default {
  i18n: {
    defaultLocale: "ko",
    supportedLocales: ["ko", "en", "ja"],
  },
} satisfies SonamuConfig;

사용 예시:

class PostModelClass extends BaseModelClass {
  @api({ httpMethod: "GET" })
  async findMany(ctx: Context) {
    const locale = ctx.locale; // "ko", "en", "ja" 중 하나

    // locale에 따라 다른 응답
    const posts = await this.getPuri("r").table("posts").where("locale", locale).select("*");

    return posts;
  }
}

bufferedFiles

bufferedFiles?: BufferedFile[]

Buffer 모드로 업로드된 파일 목록입니다. @upload 데코레이터가 적용된 메서드에서, 기본 모드(buffer) 또는 mode: "buffer"로 설정된 경우에 존재합니다. 각 파일은 메모리에 로드된 상태로, MD5 계산이나 이미지 처리 등 유연한 작업이 가능합니다. BufferedFile 주요 속성 및 메서드:

interface BufferedFile {
  // 파일 정보
  filename: string; // 파일명
  mimetype: string; // MIME 타입 (예: "image/png", "application/pdf")
  size: number; // 파일 크기 (bytes)
  extname: string; // 확장자 (예: "png", "pdf")

  // 파일 처리 메서드
  buffer: Buffer; // 파일 Buffer (getter)
  md5(): Promise<string>; // MD5 해시 생성
  saveToDisk(diskName: string, key: string): Promise<string>; // 파일 저장 후 URL 반환
}

기본 사용 예시:

class FileModelClass extends BaseModelClass {
  @upload({ limits: { files: 10 } })
  async upload(): Promise<{ files: SonamuFile[] }> {
    const { bufferedFiles } = Sonamu.getContext();

    if (!bufferedFiles || bufferedFiles.length === 0) {
      throw new BadRequestException("파일이 업로드되지 않았습니다");
    }

    const processedFiles = await Promise.all(
      bufferedFiles.map(async (file) => {
        const md5 = await file.md5();
        const key = `${md5}.${file.extname}`;
        return {
          name: file.filename,
          url: await file.saveToDisk("fs", key),
          mime_type: file.mimetype,
          size: file.size,
        };
      }),
    );

    return { files: processedFiles };
  }
}

이미지 처리 예시:

import sharp from "sharp";

class ImageModelClass extends BaseModelClass {
  @upload({ limits: { files: 1 } })
  async uploadThumbnail(): Promise<{ url: string }> {
    const { bufferedFiles } = Sonamu.getContext();

    if (!bufferedFiles || bufferedFiles.length === 0) {
      throw new BadRequestException("이미지가 업로드되지 않았습니다");
    }

    const file = bufferedFiles[0];

    // Buffer로 이미지 처리 (getter 사용)
    const thumbnail = await sharp(file.buffer).resize(200, 200).jpeg({ quality: 80 }).toBuffer();

    // 처리된 이미지 저장
    const disk = Sonamu.storage.use("fs");
    const key = `thumbnails/${await file.md5()}.jpg`;
    await disk.put(key, thumbnail);

    return { url: await disk.getUrl(key) };
  }
}

uploadedFiles

uploadedFiles?: UploadedFile[]

Stream 모드로 업로드된 파일 목록입니다. @upload({ consume: "stream", destination: "..." }) 설정 시 존재합니다. 파일이 이미 저장소에 스트리밍 완료된 상태로, URL/key 등 메타데이터만 접근 가능합니다. 대용량 파일 업로드에 적합합니다. UploadedFile 주요 속성 및 메서드:

interface UploadedFile {
  // 파일 정보
  filename: string; // 파일명
  mimetype: string; // MIME 타입 (예: "image/png", "application/pdf")
  size: number; // 파일 크기 (bytes)
  extname: string; // 확장자 (예: "png", "pdf")
  url: string; // 저장된 파일의 URL
  signedUrl: string; // Signed URL (만료 시간 있음)
  key: string; // 저장소 내 키
  diskName: string; // 저장된 디스크 이름

  // 파일 처리 메서드
  download(): Promise<Buffer>; // 저장소에서 파일 다운로드
}

Stream 모드 사용 예시:

class FileModelClass extends BaseModelClass {
  @upload({ consume: "stream", destination: "s3", limits: { files: 5 } })
  async uploadLargeFiles(): Promise<{ files: SonamuFile[] }> {
    const { uploadedFiles } = Sonamu.getContext();

    if (!uploadedFiles || uploadedFiles.length === 0) {
      throw new BadRequestException("파일이 업로드되지 않았습니다");
    }

    // 이미 저장소에 업로드 완료된 상태
    return {
      files: uploadedFiles.map((file) => ({
        name: file.filename,
        url: file.url,
        mime_type: file.mimetype,
        size: file.size,
      })),
    };
  }
}

파일 업로드 처리: - @upload 데코레이터와 함께 사용해야 합니다 - Buffer 모드(기본): bufferedFiles 사용 - 메모리에 로드, MD5 계산/이미지 처리에 적합 - Stream 모드: uploadedFiles 사용 - 저장소로 직접 스트리밍, 대용량 파일에 적합 - 자세한 내용은 @upload 데코레이터 문서를 참고하세요

AuthContext 속성

Context는 AuthContext의 속성들도 포함합니다:

user: 현재 인증된 사용자 정보 (User | null)
session: 현재 세션 정보 (Session | null)

Context 확장

프로젝트에서 Context에 커스텀 속성을 추가하려면 ContextExtend 인터페이스를 확장할 수 있습니다:

// src/types.ts
declare module "sonamu" {
  interface ContextExtend {
    customProperty: string;
    helperMethod: () => void;
  }
}

이렇게 확장된 속성은 contextProvider를 통해 주입할 수 있습니다:

// sonamu.config.ts
export default {
  server: {
    apiConfig: {
      contextProvider: async (baseContext) => {
        return {
          ...baseContext,
          customProperty: "custom value",
          helperMethod: () => console.log("helper"),
        };
      },
    },
  },
} satisfies SonamuConfig;

시작하기

핵심 개념

데이터베이스

API 개발

프론트엔드 통합

테스팅

고급 기능

도구 & CLI

설정

API 레퍼런스

문제 해결

자주 묻는 질문

타입 정의

Context 속성

request

reply

headers

createSSE

naiteStore

locale

bufferedFiles

uploadedFiles

AuthContext 속성

Context 확장

관련 문서

시작하기

핵심 개념

데이터베이스

API 개발

프론트엔드 통합

테스팅

고급 기능

도구 & CLI

설정

API 레퍼런스

문제 해결

자주 묻는 질문

​타입 정의

​Context 속성

​request

​reply

​headers

​createSSE

​naiteStore

​locale

​bufferedFiles

​uploadedFiles

​AuthContext 속성

​Context 확장

​관련 문서

타입 정의

Context 속성

request

reply

headers

createSSE

naiteStore

locale

bufferedFiles

uploadedFiles

AuthContext 속성

Context 확장

관련 문서