Search Apps Documentation Source Content File Folder Download Copy Actions Download State String Boolean Number Struct Map Slice Pointer Function Closure Reference Nil Package Type Interface Unknown

types.gno

6.82 Kb · 182 lines
Download 
  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}