types.gno
6.82 Kb · 182 lines
1package store
2
3import (
4 bptree "gno.land/p/nt/bptree/v0"
5)
6
7type Permission uint8
8
9const (
10 _ Permission = iota
11 Write
12)
13
14// KVStore interface for domain-specific storage
15// Each domain creates its own instance of KVStore
16type KVStore interface {
17 // GetDomainAddress returns the domain address.
18 //
19 // Returns:
20 // - address: Address of the domain realm that owns this store.
21 GetDomainAddress() address
22
23 // GetAllKeys returns all keys in this store.
24 //
25 // Returns:
26 // - []string: Keys currently stored by the implementation, including any namespace prefix it uses.
27 // - error: nil when keys are enumerated successfully; otherwise the implementation's retrieval error.
28 GetAllKeys() ([]string, error)
29
30 // Has checks if a key exists.
31 //
32 // Parameters:
33 // - key: Logical key to test for presence in the store.
34 //
35 // Returns:
36 // - bool: true when key has a stored entry; false when no entry exists.
37 Has(key string) bool
38
39 // Get retrieves a value by key.
40 //
41 // Parameters:
42 // - key: Logical key whose stored value should be returned.
43 //
44 // Returns:
45 // - any: Value stored under key, including an explicitly stored nil.
46 // - error: nil when key exists; otherwise the implementation's missing-key error.
47 Get(key string) (any, error)
48
49 // GetInt64 retrieves an int64 value by key.
50 //
51 // Parameters:
52 // - key: Logical key whose value must have dynamic type int64.
53 //
54 // Returns:
55 // - int64: Stored int64 value, or the implementation's zero value when retrieval or casting fails.
56 // - error: nil on success; otherwise a missing-key or failed-cast error.
57 GetInt64(key string) (int64, error)
58
59 // GetUint64 retrieves a uint64 value by key.
60 //
61 // Parameters:
62 // - key: Logical key whose value must have dynamic type uint64.
63 //
64 // Returns:
65 // - uint64: Stored uint64 value, or the implementation's zero value when retrieval or casting fails.
66 // - error: nil on success; otherwise a missing-key or failed-cast error.
67 GetUint64(key string) (uint64, error)
68
69 // GetBool retrieves a bool value by key.
70 //
71 // Parameters:
72 // - key: Logical key whose value must have dynamic type bool.
73 //
74 // Returns:
75 // - bool: Stored bool value, or false when retrieval or casting fails.
76 // - error: nil on success; otherwise a missing-key or failed-cast error.
77 GetBool(key string) (bool, error)
78
79 // GetString retrieves a string value by key.
80 //
81 // Parameters:
82 // - key: Logical key whose value must have dynamic type string.
83 //
84 // Returns:
85 // - string: Stored string value, or the empty string when retrieval or casting fails.
86 // - error: nil on success; otherwise a missing-key or failed-cast error.
87 GetString(key string) (string, error)
88
89 // GetAddress retrieves an address value by key.
90 //
91 // Parameters:
92 // - key: Logical key whose value must have dynamic type address.
93 //
94 // Returns:
95 // - address: Stored address value, or the empty address when retrieval or casting fails.
96 // - error: nil on success; otherwise a missing-key or failed-cast error.
97 GetAddress(key string) (address, error)
98
99 // GetBPTree retrieves a B+ tree value by key.
100 //
101 // Parameters:
102 // - key: Logical key whose value must have dynamic type *bptree.BPTree.
103 //
104 // Returns:
105 // - *bptree.BPTree: Stored B+ tree pointer, or nil when retrieval or casting fails.
106 // - error: nil on success; otherwise a missing-key or failed-cast error.
107 GetBPTree(key string) (*bptree.BPTree, error)
108
109 // Set stores a value with the given key.
110 //
111 // Parameters:
112 // - _: Interrealm-call discriminator; callers pass 0.
113 // - rlm: Propagated current realm context from the domain wrapper; implementations validate it and may use its address for write authorization.
114 // - key: Logical key under which value is stored.
115 // - value: Arbitrary value to associate with key.
116 //
117 // Returns:
118 // - error: nil when value is stored; otherwise the implementation's realm, authorization, or storage error.
119 Set(_ int, rlm realm, key string, value any) error
120
121 // Delete removes a key.
122 //
123 // Parameters:
124 // - _: Interrealm-call discriminator; callers pass 0.
125 // - rlm: Propagated current realm context from the domain wrapper; implementations validate it and may use its address for write authorization.
126 // - key: Logical key whose stored entry should be removed.
127 //
128 // Returns:
129 // - error: nil when key is removed; otherwise the implementation's realm, authorization, missing-key, or storage error.
130 Delete(_ int, rlm realm, key string) error
131
132 // IsWriteAuthorized checks if the caller has write permission.
133 //
134 // Parameters:
135 // - caller: Address whose write permission should be checked.
136 //
137 // Returns:
138 // - bool: true when caller is authorized to write; false otherwise.
139 IsWriteAuthorized(caller address) bool
140
141 // GetAuthorizedCallers returns all authorized callers and their permissions.
142 //
143 // Returns:
144 // - map[address]Permission: Caller-to-permission mapping exposed by the implementation.
145 // - error: nil when the ACL is available; otherwise the implementation's ACL retrieval error.
146 GetAuthorizedCallers() (map[address]Permission, error)
147
148 // AddAuthorizedCaller adds a new authorized caller.
149 //
150 // Parameters:
151 // - _: Interrealm-call discriminator; callers pass 0.
152 // - rlm: Propagated current realm context from the domain wrapper; implementations validate it before changing ACL state.
153 // - caller: Address to add to the authorization map.
154 // - permission: Permission to assign to caller; the concrete store accepts Write.
155 //
156 // Returns:
157 // - error: nil when caller is added; otherwise the implementation's realm, authorization, duplicate, permission, or storage error.
158 AddAuthorizedCaller(_ int, rlm realm, caller address, permission Permission) error
159
160 // UpdateAuthorizedCaller updates an existing caller's permission.
161 //
162 // Parameters:
163 // - _: Interrealm-call discriminator; callers pass 0.
164 // - rlm: Propagated current realm context from the domain wrapper; implementations validate it before changing ACL state.
165 // - caller: Address of the registered caller to update.
166 // - permission: Replacement permission for caller; the concrete store accepts Write.
167 //
168 // Returns:
169 // - error: nil when caller's permission is updated; otherwise the implementation's realm, authorization, missing-caller, permission, or storage error.
170 UpdateAuthorizedCaller(_ int, rlm realm, caller address, permission Permission) error
171
172 // RemoveAuthorizedCaller removes an authorized caller.
173 //
174 // Parameters:
175 // - _: Interrealm-call discriminator; callers pass 0.
176 // - rlm: Propagated current realm context from the domain wrapper; implementations validate it before changing ACL state.
177 // - caller: Address of the registered caller to remove.
178 //
179 // Returns:
180 // - error: nil when caller is removed; otherwise the implementation's realm, authorization, missing-caller, or storage error.
181 RemoveAuthorizedCaller(_ int, rlm realm, caller address) error
182}
