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";

const ProcessEventsSchema = z.object({
  progress: z.object({ percent: z.number() }),
  complete: z.object({ result: z.string() }),
});

class MyModelClass extends BaseModelClass {
  @stream({
    type: "sse",
    events: ProcessEventsSchema,
  })
  async processData(ctx: Context) {
    const sse = ctx.createSSE(ProcessEventsSchema);

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

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

    return sse;
  }
}

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 데코레이터가 적용된 메서드에서, 기본값(consume: "buffer") 또는 @upload({ consume: "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 확장

관련 문서

​타입 정의

​Context 속성

​request

​reply

​headers

​createSSE

​naiteStore

​locale

​bufferedFiles

​uploadedFiles

​AuthContext 속성

​Context 확장

​관련 문서

타입 정의

Context 속성

request

reply

headers

createSSE

naiteStore

locale

bufferedFiles

uploadedFiles

AuthContext 속성

Context 확장

관련 문서