vblt.org
forked from
gazagnaire.org/irmin
Persistent store with Git semantics: lazy reads, delayed writes, content-addressing
1(** Tree format abstraction - the ONE functor in Irmin.
2
3 This module type defines how tree nodes are encoded and decoded. Different
4 formats (Git trees, ATProto MST) implement this interface. This is the only
5 functor-based abstraction point in the library. *)
6
7(** {1 Module Type} *)
8
9module type S = sig
10 (** The tree format signature. *)
11
12 type node
13 (** The internal node representation. *)
14
15 type hash
16 (** The hash type used by this format. *)
17
18 type entry =
19 [ `Node of hash | `Contents of hash | `Contents_inlined of string ]
20 (** A node entry: subtree hash, content hash, or inlined content. *)
21
22 val inline_threshold : int
23 (** Maximum serialized size (in bytes) for inlined contents. Contents at or
24 below this size are stored directly in the node rather than as a separate
25 blob. Set to 0 to disable inlining. *)
26
27 val hash_node : node -> hash
28 (** [hash_node n] computes the hash of [n]. *)
29
30 val hash_contents : string -> hash
31 (** [hash_contents data] computes the hash of content [data]. *)
32
33 val node_of_bytes : string -> (node, [> `Msg of string ]) result
34 (** [node_of_bytes data] deserializes a node from bytes. *)
35
36 val bytes_of_node : node -> string
37 (** [bytes_of_node n] serializes a node to bytes. *)
38
39 val empty_node : node
40 (** The empty node with no entries. *)
41
42 val find : node -> string -> entry option
43 (** [find node name] looks up an entry by name. *)
44
45 val add : node -> string -> entry -> node
46 (** [add node name entry] adds or replaces an entry. *)
47
48 val remove : node -> string -> node
49 (** [remove node name] removes an entry. *)
50
51 val list : node -> (string * entry) list
52 (** [list node] returns all entries sorted by name. *)
53
54 val is_empty : node -> bool
55 (** [is_empty node] returns true if the node has no entries. *)
56
57 (** {2 Hash Operations} *)
58
59 val hash_to_bytes : hash -> string
60 (** [hash_to_bytes h] returns the raw bytes of [h]. *)
61
62 val hash_to_hex : hash -> string
63 (** [hash_to_hex h] returns the hexadecimal representation of [h]. *)
64
65 val hash_of_hex : string -> (hash, [> `Msg of string ]) result
66 (** [hash_of_hex s] parses a hexadecimal hash string. *)
67
68 val hash_equal : hash -> hash -> bool
69 (** [hash_equal h1 h2] tests hash equality. *)
70
71 val hash_compare : hash -> hash -> int
72 (** [hash_compare h1 h2] compares hashes. *)
73
74 (** {2 Commit Operations} *)
75
76 type commit
77 (** The commit representation. *)
78
79 val commit_make :
80 tree:hash ->
81 parents:hash list ->
82 author:string ->
83 committer:string ->
84 message:string ->
85 timestamp:int64 ->
86 commit
87 (** Create a commit. *)
88
89 val commit_tree : commit -> hash
90 val commit_parents : commit -> hash list
91 val commit_author : commit -> string
92 val commit_committer : commit -> string
93 val commit_message : commit -> string
94 val commit_timestamp : commit -> int64
95
96 val commit_of_bytes : string -> (commit, [> `Msg of string ]) result
97 (** Parse a commit from bytes. *)
98
99 val commit_to_bytes : commit -> string
100 (** Serialize a commit to bytes. *)
101
102 val commit_hash : commit -> hash
103 (** Compute the hash of a commit. *)
104end
105
106(** {1 Hash-Specific Signatures} *)
107
108module type SHA1 = S with type hash = Hash.sha1
109(** Tree format using SHA-1 (Git compatible). *)
110
111module type SHA256 = S with type hash = Hash.sha256
112(** Tree format using SHA-256 (ATProto compatible). *)
113
114(** {1 Built-in Formats} *)
115
116module Git : SHA1
117(** Git tree object format. Bidirectional compatibility with Git. *)
118
119module Mst : SHA256
120(** ATProto Merkle Search Tree format. *)