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_of_raw_bytes : string -> hash
69 (** [hash_of_raw_bytes s] creates a hash from raw digest bytes. Raises
70 [Invalid_argument] if [s] has the wrong length. *)
71
72 val hash_equal : hash -> hash -> bool
73 (** [hash_equal h1 h2] tests hash equality. *)
74
75 val hash_compare : hash -> hash -> int
76 (** [hash_compare h1 h2] compares hashes. *)
77
78 (** {2 Commit Operations} *)
79
80 type commit
81 (** The commit representation. *)
82
83 val commit_make :
84 tree:hash ->
85 parents:hash list ->
86 author:string ->
87 committer:string ->
88 message:string ->
89 timestamp:int64 ->
90 commit
91 (** Create a commit. *)
92
93 val commit_tree : commit -> hash
94 (** Tree hash of the commit. *)
95
96 val commit_parents : commit -> hash list
97 (** Parent commit hashes. *)
98
99 val commit_author : commit -> string
100 (** Author name. *)
101
102 val commit_committer : commit -> string
103 (** Committer name. *)
104
105 val commit_message : commit -> string
106 (** Commit message. *)
107
108 val commit_timestamp : commit -> int64
109 (** Commit timestamp. *)
110
111 val commit_of_bytes : string -> (commit, [> `Msg of string ]) result
112 (** Parse a commit from bytes. *)
113
114 val commit_to_bytes : commit -> string
115 (** Serialize a commit to bytes. *)
116
117 val commit_hash : commit -> hash
118 (** Compute the hash of a commit. *)
119end
120
121(** {1 Hash-Specific Signatures} *)
122
123module type SHA1 = S with type hash = Hash.sha1
124(** Tree format using SHA-1 (Git compatible). *)
125
126module type SHA256 = S with type hash = Hash.sha256
127(** Tree format using SHA-256 (ATProto compatible). *)
128
129(** {1 Built-in Formats} *)
130
131module Git : SHA1
132(** Git tree object format. Bidirectional compatibility with Git. *)
133
134module Mst : SHA256
135(** ATProto Merkle Search Tree format. *)