📝 Add 1.0.1(0.6.1) change notes for wide file rotation

2026-07-29 14:06:34 +00:00 · 2026-07-05 21:32:11 +08:00
parent 6e3cc165b6
commit b90481186f
14 changed files with 234 additions and 10 deletions
@@ -0,0 +1,74 @@
+---
+name: file-rotation-i64
+group: api
+category: sink
+update-time: 20260705
+description: Create a native-focused large-file rotation policy using an Int64 byte threshold.
+key-word:
+    - file
+    - rotation
+    - i64
+    - native
+---
+
+## File-rotation-i64
+
+Create a size-based file rotation policy with an `Int64` byte threshold. This helper is the opt-in native-focused path for large-file rotation scenarios that exceed the default `Int`-based contract.
+
+### Interface
+
+```moonbit
+pub fn file_rotation_i64(max_bytes : Int64, max_backups~ : Int = 1) -> FileRotation {}
+```
+
+#### input
+
+- `max_bytes : Int64` - Maximum active file size threshold before rotation on the native-focused wide path.
+- `max_backups : Int` - Number of retained backup files.
+
+#### output
+
+- `FileRotation` - Rotation policy value that preserves a native wide threshold while staying compatible with the existing file sink API surface.
+
+### Explanation
+
+- `max_bytes <= 0L` is normalized to `1L`.
+- `max_backups <= 0` is normalized to `1`.
+- Rotation is size-based only.
+- This helper keeps the existing `FileRotation` type but stores an additional native wide threshold internally for runtime rotation checks.
+- The helper is intended for native file backends and advanced large-file scenarios.
+- JSON config export helpers preserve the exact threshold through `max_bytes_i64` while still exposing a compatibility `max_bytes` view.
+
+### How to Use
+
+#### When Need Native Large-file Rotation Thresholds
+
+```moonbit
+let sink = file_sink(
+  "app.log",
+  rotation=Some(file_rotation_i64(5368709120L, max_backups=4)),
+)
+```
+
+In this example, the active rotation threshold is expressed with `Int64` rather than the default `Int` path.
+
+#### When Need A Wide Policy Value First
+
+```moonbit
+let rotation = file_rotation_i64(3221225472L, max_backups=2)
+let sink = file_sink("app.log", rotation=Some(rotation))
+```
+
+In this example, the wide threshold policy is assembled separately and then reused.
+
+### Error Case
+
+- If `max_bytes` is non-positive, it is clamped to `1L`.
+- This API does not make non-native targets gain real file support; callers should still use `native_files_supported()` when portability matters.
+
+### Notes
+
+1. This API is additive and does not replace the default `file_rotation(...)` contract.
+2. Prefer the default `Int` path unless a native large-file threshold is actually required.
+3. String-based JSON roundtrip uses `max_bytes_i64` for the exact threshold and keeps `max_bytes` as the compatibility field.
+4. This helper is designed for advanced use and target-aware code.