Scope Resource    = 획득 지점과 해제 지점을 같은 스코프에 둔다
Cleanup Guarantee = 성공 / 실패 / 조기 반환 모두에서 해제를 보장한다
Policy Boundary   = 해제는 로컬에서, 실패 해석은 상위 정책에서 처리한다

using System;
using System.IO;
using System.Text;
using System.Threading;
using System.Threading.Tasks;

public sealed class AuditLogWriter
{
    private readonly string filePath;

    public AuditLogWriter(string filePath)
    {
        this.filePath = filePath ?? throw new ArgumentNullException(nameof(filePath));
    }

    public string GetFilePath()
    {
        return this.filePath;
    }

    public async ValueTask WriteLineAsync(
        string message,
        CancellationToken cancellationToken)
    {
        if (string.IsNullOrWhiteSpace(message))
        {
            throw new ArgumentException("message는 비어 있을 수 없습니다.", nameof(message));
        }

        await using FileStream stream = new(
            this.filePath,
            FileMode.Append,
            FileAccess.Write,
            FileShare.Read,
            bufferSize: 16 * 1024,
            useAsync: true);
        await using StreamWriter writer = new(
            stream,
            Encoding.UTF8,
            bufferSize: 16 * 1024,
            leaveOpen: true);

        await writer.WriteLineAsync(message.AsMemory(), cancellationToken);
        await writer.FlushAsync(cancellationToken);
    }
}

import { mkdir, open } from "node:fs/promises";
import { dirname } from "node:path";

export class AuditLogWriter {
  readonly #filePath: string;

  public constructor(filePath: string) {
    if (filePath.trim().length === 0) {
      throw new RangeError("filePath는 비어 있을 수 없습니다.");
    }
    this.#filePath = filePath;
  }

  public getFilePath(): string {
    return this.#filePath;
  }

  public async writeLineAsync(
    message: string,
    signal?: AbortSignal,
  ): Promise<void> {
    if (message.trim().length === 0) {
      throw new RangeError("message는 비어 있을 수 없습니다.");
    }
    signal?.throwIfAborted();

    await mkdir(dirname(this.#filePath), { recursive: true });

    const handle = await open(this.#filePath, "a");
    try {
      signal?.throwIfAborted();
      // 시작 전 확인뿐 아니라 쓰기 중 취소까지 원하면 signal을 옵션으로 넘긴다.
      await handle.appendFile(`${message}\n`, { encoding: "utf8", signal });
    } finally {
      await handle.close();
    }
  }
}

import { mkdir, open } from "node:fs/promises";
import { dirname } from "node:path";

export class AuditLogWriterModern {
  readonly #filePath: string;

  public constructor(filePath: string) {
    if (filePath.trim().length === 0) {
      throw new RangeError("filePath는 비어 있을 수 없습니다.");
    }
    this.#filePath = filePath;
  }

  public async writeLineAsync(message: string): Promise<void> {
    if (message.trim().length === 0) {
      throw new RangeError("message는 비어 있을 수 없습니다.");
    }
    await mkdir(dirname(this.#filePath), { recursive: true });

    // Node의 FileHandle은 v20.4.0 / v18.18.0부터 [Symbol.asyncDispose]를 구현한다
    // (v24.2.0부터 non-experimental). 스코프를 벗어나면 handle이 자동 close된다.
    // (수명 관리 의도는 C#의 await using과 유사하다)
    await using handle = await open(this.#filePath, "a");
    await handle.appendFile(`${message}\n`, { encoding: "utf8" });
  }
}

from pathlib import Path

class AuditLogWriter:
    def __init__(self, file_path: str) -> None:
        if not file_path.strip():
            raise ValueError("file_path는 비어 있을 수 없습니다.")
        self._file_path = Path(file_path)

    def get_file_path(self) -> Path:
        return self._file_path

    def write_line(self, message: str) -> None:
        if not message.strip():
            raise ValueError("message는 비어 있을 수 없습니다.")
        self._file_path.parent.mkdir(parents=True, exist_ok=True)
        with self._file_path.open("a", encoding="utf-8") as file:
            file.write(f"{message}\n")

use std::fs::OpenOptions;
use std::io;
use std::io::Write;
use std::path::{Path, PathBuf};

pub struct AuditLogWriter {
    file_path: PathBuf,
}

impl AuditLogWriter {
    pub fn new(file_path: impl Into<PathBuf>) -> Self {
        Self {
            file_path: file_path.into(),
        }
    }

    pub fn get_file_path(&self) -> &Path {
        &self.file_path
    }

    pub fn write_line(&self, message: &str) -> io::Result<()> {
        if message.trim().is_empty() {
            return Err(io::Error::new(
                io::ErrorKind::InvalidInput,
                "message는 비어 있을 수 없습니다.",
            ));
        }
        if let Some(parent) = self.file_path.parent() {
            // 상대 경로 파일명만 주면 parent가 빈 경로("")일 수 있어 명시적으로 거른다.
            if !parent.as_os_str().is_empty() {
                std::fs::create_dir_all(parent)?;
            }
        }
        let mut file = OpenOptions::new()
            .create(true)
            .append(true)
            .open(&self.file_path)?;
        writeln!(file, "{message}")?;
        file.flush()?;
        Ok(())
    }
}

type AuditEvent = Readonly<{
  actorId: string;
  action: "login" | "logout" | "permissionChanged";
  targetId: string;
  occurredAt: Date;
}>;

type AuditIoPolicy = Readonly<{
  runAsync: (operation: () => Promise<void>) => Promise<void>;
}>;

function toAuditLine(event: AuditEvent): string {
  if (event.actorId.trim().length === 0) {
    throw new RangeError("actorId는 비어 있을 수 없습니다.");
  }
  if (event.targetId.trim().length === 0) {
    throw new RangeError("targetId는 비어 있을 수 없습니다.");
  }
  return [
    event.occurredAt.toISOString(),
    event.actorId,
    event.action,
    event.targetId,
  ].join("\t");
}

export async function appendAuditEventAsync(
  event: AuditEvent,
  writer: AuditLogWriter,
  ioPolicy: AuditIoPolicy,
  signal?: AbortSignal,
): Promise<void> {
  const line = toAuditLine(event);
  await ioPolicy.runAsync(async () => {
    await writer.writeLineAsync(line, signal);
  });
}

toAuditLine             = 도메인 이벤트 검증과 문자열 변환
AuditLogWriter          = 파일 열기 / 쓰기 / 닫기
AuditIoPolicy           = 재시도, 경보, 장애 처리 정책
appendAuditEventAsync   = 도메인 흐름 조립

입력이 비었는가
→ 파일 경로 디렉터리가 존재하는가
→ 리소스를 획득했는가
→ 획득 직후 해제 스코프가 보이는가
→ 쓰기 작업이 성공하든 실패하든 해제가 실행되는가
→ I/O 실패 해석은 상위 정책으로 올라가는가

type AuditLogger = Readonly<{ error: (msg: string, meta?: unknown) => void }>;

export async function writeLineSafely(
  filePath: string,
  message: string,
  logger: AuditLogger,
): Promise<void> {
  const handle = await open(filePath, "a");

  let bodyOk = false;
  try {
    await handle.appendFile(`${message}\n`, { encoding: "utf8" });
    bodyOk = true;
  } finally {
    try {
      await handle.close();
    } catch (closeError) {
      // close 실패는 항상 관측한다. (metric: audit_log.close.failure.count++)
      logger.error("audit close failed", { closeError });

      if (bodyOk) {
        // 본문은 성공했으니 close 실패를 드러낸다.
        throw closeError;
      }
      // 본문이 이미 실패했다면 원래 예외를 우선한다.
      // 여기서 throw하지 않아야 원래 예외가 덮이지 않는다(Double Fault 방지).
    }
  }
}

import { open } from "node:fs/promises";

async function appendAuditBadAsync(
  filePath: string,
  message: string,
): Promise<void> {
  const handle = await open(filePath, "a");
  if (message.trim().length === 0) {
    return;
  }
  await handle.appendFile(`${message}\n`, { encoding: "utf8" });
  await handle.close();
}

async function appendAuditBetterAsync(
  filePath: string,
  message: string,
): Promise<void> {
  if (message.trim().length === 0) {
    throw new RangeError("message는 비어 있을 수 없습니다.");
  }
  const handle = await open(filePath, "a");
  try {
    await handle.appendFile(`${message}\n`, { encoding: "utf8" });
  } finally {
    await handle.close();
  }
}

import assert from "node:assert/strict";
import test from "node:test";

type AsyncCloseable = Readonly<{
  closeAsync: () => Promise<void>;
}>;

class DisposableProbe implements AsyncCloseable {
  #closed = false;
  #closeCalls = 0;

  public getClosed(): boolean {
    return this.#closed;
  }

  public getCloseCalls(): number {
    return this.#closeCalls;
  }

  public async closeAsync(): Promise<void> {
    this.#closed = true;
    this.#closeCalls += 1;
  }
}

async function usingResourceAsync<TResource extends AsyncCloseable>(
  resource: TResource,
  bodyAsync: (resource: TResource) => Promise<void>,
): Promise<void> {
  try {
    await bodyAsync(resource);
  } finally {
    await resource.closeAsync();
  }
}

test("성공 경로에서도 리소스를 닫는다", async () => {
  const probe = new DisposableProbe();
  await usingResourceAsync(probe, async () => {
    return;
  });
  assert.equal(probe.getClosed(), true);
  assert.equal(probe.getCloseCalls(), 1);
});

test("실패 경로에서도 리소스를 닫는다", async () => {
  const probe = new DisposableProbe();
  await assert.rejects(async () => {
    await usingResourceAsync(probe, async () => {
      throw new Error("쓰기 실패");
    });
  });
  assert.equal(probe.getClosed(), true);
  assert.equal(probe.getCloseCalls(), 1);
});

audit_log.write.success.count
audit_log.write.failure.count
audit_log.close.failure.count
audit_log.write.duration.ms

이벤트 -> Channel<T> / 큐 (메모리 버퍼)
       -> 애플리케이션 수명과 결합된 백그라운드 워커(BackgroundService)
       -> 스트림을 열어둔 채 Batch Write + 주기적 Flush
       -> 종료 시 그레이스풀하게 남은 버퍼 flush 후 close

1. StopAsync(hostCancellationToken) 진입 (호스트가 종료 신호를 준다)
2. 새 이벤트 수용 중단: channel.Writer.Complete()로 더 이상 받지 않는다
3. 남은 큐 드레인: await foreach로 Reader의 잔여 항목을 끝까지 처리
   - 여기서 hostCancellationToken을 그대로 쓰면 즉시 취소되어 로그가 유실된다.
     드레인 전용 유예(grace) 시간을 주는 별도 토큰으로 완료를 기다린다.
4. 마지막 flush: 스트림 FlushAsync (+ 필요 시 flush-to-disk)
5. 스트림/핸들 close