github.com/go-kivik/kivik/v4@v4.3.2/x/fsdb/notes.txt (about)

     1  PUT strategy:
     2  
     3  new_edits=false?
     4  	Yes: Does the rev already exist?
     5  		Yes: return
     6  		No: Create it as .{docid}/.tmp.{rev}.{ext}
     7  			Write any attachments as .{docid}/.tmp.{rev}/{filename}
     8  			Move .{docid}/.tmp
     9  		Is this the new winning rev?
    10  			Yes: Swap with existing winner
    11  			No: return
    12  	No: Does the rev match a leaf?
    13  		Yes: Write the new document as .{docid}/.tmp.{rev}.{ext}
    14  			Write any attachments as .{docid}/.tmp.{rev}/{filename}
    15  		No: return conflict error
    16  
    17          {db}/.{docid} is authoritative, and contains two types of entries:
    18          	- {rev}.{ext} - JSON document
    19          	- {rev}/      - Directory containing attachments
    20  
    21          As a user convenience, the winning rev _may_ be moved to {db}/{docid}.{ext}, and the associated attachments to {db}/{docid}/{filename}.
    22  
    23          When reading, the absence of a doc or attachment in {db}/{docid}* should fall back to reading {db}/.{docid}/{rev}*, to allow for a write operation to be aborted mid-way.
    24  
    25          When writing, the winning rev should be stored in {db}/{docid} only as a final step.
    26  
    27          When reading, if a winning rev exists, it can be trusted. If not, and there are more than a single rev in {db}/.{docid}, the winning rev should be calculated (but this should be easy, as revs are in the filenames).
    28  
    29          File locking etc:
    30          When writing, write to a tmp file, write attachments to a tmp dir. Move the tmp dir in place first, then move the temp file.
    31  
    32          Abandoned temp dirs can be cleaned up by the compact method.
    33  
    34          When reading, open each attachment (but don't read it) before sending a success. Then even if the files are deleted under our shoes, we can send a valid response (at least on Linux--Windows will probably need to read the files in completely).
    35  
    36  
    37          File naming strategy:
    38          Current rev lives under:     {db}/{docid}.{ext}
    39          Conflicting revs live under: {db}/.{docid}/{rev}.{ext}
    40          Atts for conflicts:          {db}/.{docid}/{rev}/{filename}
    41          Attachments:                 {db}/{docid}/{filename}