Skip to content

feat(json): add optional durable JSON file writes #544

Description

@GaspardKirira

Summary

Add an opt-in durability mode for applications that require data to reach stable storage before dump_file() returns.

Current behavior

dump_file() writes, flushes the C++ stream, and renames the temporary file.

A stream flush does not necessarily guarantee that data or directory metadata has reached durable storage.

A system crash or power loss may still lose the latest write.

Expected behavior

The module should expose an optional durability policy.

Normal writes should remain lightweight by default.

Durable mode should use platform-specific synchronization where supported.

Scope

  • Define a durability option.
  • Synchronize temporary file data before replacement.
  • Synchronize directory metadata after replacement where required.
  • Add POSIX implementation.
  • Add Windows implementation or documented fallback.
  • Report unsupported behavior clearly.
  • Add integration tests where practical.
  • Preserve default performance.
  • Preserve existing APIs.

Suggested files

  • modules/json/include/vix/json/dumps.hpp
  • modules/json/tests/json_dumps_durability_test.cpp
  • platform-specific implementation headers where needed.

Acceptance criteria

  • Durability mode is disabled by default.
  • Enabling durability performs the documented synchronization.
  • Unsupported platforms follow a documented policy.
  • Normal writes retain current behavior.
  • Replacement safety remains intact.
  • Errors are reported clearly.

Non-goals

This issue does not include:

  • database transaction guarantees;
  • distributed replication;
  • filesystem-independent durability guarantees;
  • mandatory synchronization for every write.

Metadata

Metadata

Assignees

No one assigned

    Labels

    help wantedExtra attention is neededscope:jsonChanges related to the Vix JSON modulestatus:triageNeeds investigationtestsTests, CI coverage and validationtype:featureNew functionality

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions