BitLogger/docs/api/file-sink-policy.md

name, group, category, update-time, description, key-word

name	group	category	update-time	description	key-word
file-sink-policy	api	sink	20260707	Public file policy type re-exported from file_model for file and runtime control APIs.	file policy alias public

File-sink-policy

FileSinkPolicy is the public policy object used to describe file append mode, auto-flush behavior, and optional rotation settings together. On the root src facade, it is re-exported from src/file_model, which is the real owner of the concrete policy model.

Interface

pub using @file_model { type FileSinkPolicy }

output

• FileSinkPolicy - Public file policy object containing append, auto_flush, and optional rotation settings.

Explanation

Detailed rules explaining key parameters and behaviors

• This root surface is a re-export, not the concrete owner definition.
• The concrete type lives in @file_model.FileSinkPolicy, not in @utils.
• The current policy fields are append : Bool, auto_flush : Bool, and rotation : FileRotation?.
• The same policy object is returned by FileSink::policy(), RuntimeSink::file_policy(), and ConfiguredLogger::file_policy().
• It is also accepted by FileSink::set_policy(...), RuntimeSink::file_set_policy(...), and ConfiguredLogger::file_set_policy(...).

How to Use

Here are some specific examples provided.

When Need One Object For Runtime File Settings

When append, flush, and rotation behavior should be updated together:

let policy = FileSinkPolicy::new(
  append=false,
  auto_flush=true,
  rotation=Some(file_rotation(1024 * 1024, max_backups=3)),
)

In this example, the file policy can be passed around as one typed value instead of separate flags.

When Need Runtime Policy Roundtrip

When current file behavior should be read, adjusted, and written back:

let policy = runtime.file_policy()
let next = FileSinkPolicy::new(
  append=policy.append,
  auto_flush=false,
  rotation=policy.rotation,
)

In this example, the policy object is the handoff boundary for direct runtime file control.

Error Case

e.g.:

• FileSinkPolicy itself does not have a runtime failure mode.

• If a non-file runtime sink exposes a fallback policy through file helpers, the object is still valid but does not reflect a live file handle.

Notes

1. Use FileSinkPolicy::new(...) to construct this policy explicitly.

2. Use file_sink_policy_to_json(...) or stringify_file_sink_policy(...) when the policy should be exported.