}
56 | */
57 | transact (fn) {
58 | return transact({
59 | queue: this.#queue,
60 | root: this.#root,
61 | blocks: this.#blocks,
62 | codec: this.#codec
63 | }, fn)
64 | }
65 |
66 | /**
67 | * Partitions a transactional store using the provided keyspace prefix.
68 | *
69 | * @template P
70 | * @param {string} prefix
71 | * @param {{ codec?: import('multiformats').BlockCodec }} [options]
72 | * @returns {ITransactionalStore}
73 | */
74 | partition (prefix, options) {
75 | const config = {
76 | queue: this.#queue,
77 | root: this.#root,
78 | blocks: this.#blocks,
79 | codec: this.#codec,
80 | ...options
81 | }
82 | return {
83 | /**
84 | * @template R
85 | * @param {(store: IStore
) => Promise} fn
86 | * @returns {Promise}
87 | */
88 | transact (fn) {
89 | return transact(config, store => fn(new SubTxnStore(prefix, store)))
90 | }
91 | }
92 | }
93 | }
94 |
95 | /**
96 | * @template T
97 | * @template R
98 | * @param {object} config
99 | * @param {Queue} config.queue Transaction queue.
100 | * @param {LinkStore} config.root Storage for the DAG root.
101 | * @param {BlockStore} config.blocks
102 | * @param {import('multiformats').BlockCodec} config.codec
103 | * @param {(store: IStore) => Promise} fn
104 | * @returns {Promise}
105 | */
106 | const transact = async ({ queue, root, blocks, codec }, fn) => {
107 | /** @type {import('p-defer').DeferredPromise} */
108 | const { promise, resolve, reject } = defer()
109 | await queue.add(async () => {
110 | try {
111 | let rootLink = await root.get()
112 | if (!rootLink) {
113 | const block = await ShardBlock.create()
114 | await blocks.put(block.cid, block.bytes)
115 | await root.set(block.cid)
116 | rootLink = block.cid
117 | }
118 | const txn = new TxnStore({ root: rootLink, blocks, codec })
119 | const result = await fn(txn)
120 | for (const a of txn.additions) {
121 | await blocks.put(a.cid, a.bytes)
122 | }
123 | await root.set(txn.root)
124 | for (const r of txn.removals) {
125 | await blocks.del(r.cid)
126 | }
127 | resolve(result)
128 | if (rootLink.toString() !== txn.root.toString()) {
129 | console.log(`Transaction commit: ${txn.root}`)
130 | }
131 | } catch (err) {
132 | reject(err)
133 | }
134 | })
135 | return promise
136 | }
137 |
138 | /**
139 | * @template T
140 | * @implements {IStore}
141 | */
142 | class TxnStore {
143 | #root
144 | #blocks
145 | /** @type {Map} */
146 | #additions
147 | /** @type {Map} */
148 | #removals
149 | #codec
150 |
151 | /**
152 | * @param {object} params
153 | * @param {import('@web3-storage/pail/api').ShardLink} params.root
154 | * @param {import('@web3-storage/pail/api').BlockFetcher} params.blocks
155 | * @param {import('multiformats').BlockCodec} params.codec
156 | */
157 | constructor ({ root, blocks, codec }) {
158 | this.#blocks = new MultiBlockFetcher({
159 | // @ts-expect-error
160 | get: async cid => this.#additions.get(cid)
161 | }, blocks)
162 | this.#root = root
163 | this.#additions = new LinkMap()
164 | this.#removals = new LinkMap()
165 | this.#codec = codec
166 | }
167 |
168 | get root () {
169 | return this.#root
170 | }
171 |
172 | get additions () {
173 | return [...this.#additions.values()]
174 | }
175 |
176 | get removals () {
177 | return [...this.#removals.values()]
178 | }
179 |
180 | /**
181 | * @param {string} key
182 | * @param {T} value
183 | */
184 | async put (key, value) {
185 | const valueBlock = await Block.encode({ value, codec: this.#codec, hasher })
186 | this.#additions.set(valueBlock.cid, valueBlock)
187 | if (this.#removals.has(valueBlock.cid)) {
188 | this.#removals.delete(valueBlock.cid)
189 | }
190 |
191 | // TODO: remove the value when putting to an existing key?
192 |
193 | const res = await Pail.put(this.#blocks, this.#root, key, valueBlock.cid)
194 | this.#applyDiff(res)
195 | }
196 |
197 | /** @param {string} key */
198 | async del (key) {
199 | const valueLink = await Pail.get(this.#blocks, this.#root, key)
200 | if (!valueLink) return
201 |
202 | const valueBlock = await this.#blocks.get(valueLink)
203 | if (!valueBlock) throw new Error(`missing value for key: ${key}: ${valueLink}`)
204 |
205 | // @ts-expect-error
206 | this.#additions.delete(valueBlock.cid)
207 | // TODO: this could be referenced somewhere else in the pail
208 | // this.#removals.set(valueBlock.cid, valueBlock)
209 |
210 | const res = await Pail.del(this.#blocks, this.#root, key)
211 | this.#applyDiff(res)
212 | }
213 |
214 | /**
215 | * @param {{ root: import('@web3-storage/pail/api').ShardLink } & import('@web3-storage/pail/api').ShardDiff} diff
216 | */
217 | #applyDiff (diff) {
218 | for (const a of diff.additions) {
219 | if (this.#removals.has(a.cid)) {
220 | this.#removals.delete(a.cid)
221 | }
222 | this.#additions.set(a.cid, a)
223 | }
224 | for (const r of diff.removals) {
225 | if (this.#additions.has(r.cid)) {
226 | this.#additions.delete(r.cid)
227 | }
228 | this.#removals.set(r.cid, r)
229 | }
230 | this.#root = diff.root
231 | }
232 |
233 | /** @param {string} key */
234 | async get (key) {
235 | const valueLink = await Pail.get(this.#blocks, this.#root, key)
236 | if (!valueLink) return
237 | const valueBlock = await this.#blocks.get(valueLink)
238 | if (!valueBlock) throw new Error(`missing value for key: ${key}: ${valueLink}`)
239 | return this.#codec.decode(valueBlock.bytes)
240 | }
241 |
242 | /** @param {string} key */
243 | async has (key) {
244 | const exists = await Pail.get(this.#blocks, this.#root, key)
245 | return Boolean(exists)
246 | }
247 |
248 | /**
249 | * @param {API.EntriesOptions} [options]
250 | * @returns {AsyncIterable<[string, T]>}
251 | */
252 | async * entries (options) {
253 | for await (const [k, v] of Pail.entries(this.#blocks, this.#root, options)) {
254 | const valueBlock = await this.#blocks.get(v)
255 | if (!valueBlock) throw new Error('missing value for key')
256 | yield [k, this.#codec.decode(valueBlock.bytes)]
257 | }
258 | }
259 | }
260 |
261 | /**
262 | * @template T
263 | * @implements {IStore}
264 | */
265 | class SubTxnStore {
266 | #prefix
267 | #store
268 |
269 | /**
270 | * @param {string} prefix
271 | * @param {IStore} store
272 | */
273 | constructor (prefix, store) {
274 | this.#prefix = prefix
275 | this.#store = store
276 | }
277 |
278 | /**
279 | * @param {string} key
280 | * @param {T} value
281 | */
282 | put (key, value) {
283 | return this.#store.put(`${this.#prefix}${key}`, value)
284 | }
285 |
286 | /** @param {string} key */
287 | del (key) {
288 | return this.#store.del(`${this.#prefix}${key}`)
289 | }
290 |
291 | /** @param {string} key */
292 | get (key) {
293 | return this.#store.get(`${this.#prefix}${key}`)
294 | }
295 |
296 | /** @param {string} key */
297 | has (key) {
298 | return this.#store.has(`${this.#prefix}${key}`)
299 | }
300 |
301 | /**
302 | * @param {API.EntriesOptions} [options]
303 | * @returns {AsyncIterable<[string, T]>}
304 | */
305 | async * entries (options) {
306 | if (options) {
307 | if ('prefix' in options && options.prefix) {
308 | options = { prefix: `${this.#prefix}${options.prefix}` }
309 | } else {
310 | if ('gt' in options && options.gt) {
311 | options = { ...options, gt: `${this.#prefix}${options.gt}` }
312 | }
313 | if ('gte' in options && options.gte) {
314 | options = { ...options, gte: `${this.#prefix}${options.gte}` }
315 | }
316 | if ('lt' in options && options.lt) {
317 | options = { ...options, lt: `${this.#prefix}${options.lt}` }
318 | }
319 | if ('lte' in options && options.lte) {
320 | options = { ...options, lte: `${this.#prefix}${options.lte}` }
321 | }
322 | }
323 | }
324 | for await (const [k, v] of this.#store.entries(options)) {
325 | yield [k.slice(this.#prefix.length), v]
326 | }
327 | }
328 | }
329 |
330 | /**
331 | * A store for a single CID.
332 | *
333 | * @template {import('multiformats').Link} T
334 | */
335 | class LinkStore {
336 | #link
337 | #filepath
338 |
339 | /** @param {string} filepath */
340 | constructor (filepath) {
341 | this.#filepath = filepath
342 | try {
343 | this.#link = /** @type {T} */ (Link.decode(fs.readFileSync(filepath)))
344 | } catch (err) {
345 | if (err.code !== 'ENOENT') throw err
346 | }
347 | }
348 |
349 | async get () {
350 | return this.#link
351 | }
352 |
353 | /** @param {T} link */
354 | async set (link) {
355 | await fs.promises.writeFile(this.#filepath, link.bytes)
356 | this.#link = link
357 | }
358 | }
359 |
360 | export class BlockStore {
361 | #bs
362 |
363 | /** @param {string} dir */
364 | constructor (dir) {
365 | fs.mkdirSync(dir, { recursive: true })
366 | this.#bs = new FsBlockstore(dir)
367 | }
368 |
369 | /**
370 | * @param {import('multiformats').UnknownLink} cid
371 | * @param {Uint8Array} bytes
372 | */
373 | put (cid, bytes) {
374 | // @ts-expect-error
375 | return this.#bs.put(cid, bytes)
376 | }
377 |
378 | /**
379 | * @template {unknown} T
380 | * @template {number} C
381 | * @template {number} A
382 | * @template {import('multiformats').Version} V
383 | * @param {import('multiformats').Link} cid
384 | * @returns {Promise | undefined>}
385 | */
386 | async get (cid) {
387 | try {
388 | // @ts-expect-error
389 | const bytes = await this.#bs.get(cid)
390 | return { cid, bytes }
391 | } catch {}
392 | }
393 |
394 | /** @param {import('multiformats').UnknownLink} cid */
395 | del (cid) {
396 | // @ts-expect-error
397 | return this.#bs.delete(cid)
398 | }
399 | }
400 |
--------------------------------------------------------------------------------
/LICENSE.md:
--------------------------------------------------------------------------------
1 | The contents of this repository are Copyright (c) corresponding authors and
2 | contributors, licensed under the `Permissive License Stack` meaning either of:
3 |
4 | - Apache-2.0 Software License: https://www.apache.org/licenses/LICENSE-2.0
5 | ([...4tr2kfsq](https://dweb.link/ipfs/bafkreiankqxazcae4onkp436wag2lj3ccso4nawxqkkfckd6cg4tr2kfsq))
6 |
7 | - MIT Software License: https://opensource.org/licenses/MIT
8 | ([...vljevcba](https://dweb.link/ipfs/bafkreiepofszg4gfe2gzuhojmksgemsub2h4uy2gewdnr35kswvljevcba))
9 |
10 | You may not use the contents of this repository except in compliance
11 | with one of the listed Licenses. For an extended clarification of the
12 | intent behind the choice of Licensing please refer to
13 | https://protocol.ai/blog/announcing-the-permissive-license-stack/
14 |
15 | Unless required by applicable law or agreed to in writing, software
16 | distributed under the terms listed in this notice is distributed on
17 | an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
18 | either express or implied. See each License for the specific language
19 | governing permissions and limitations under that License.
20 |
21 |
22 |
23 | `SPDX-License-Identifier: Apache-2.0 OR MIT`
24 |
25 | Verbatim copies of both licenses are included below:
26 |
27 | Apache-2.0 Software License
28 |
29 | ```
30 | Apache License
31 | Version 2.0, January 2004
32 | http://www.apache.org/licenses/
33 |
34 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
35 |
36 | 1. Definitions.
37 |
38 | "License" shall mean the terms and conditions for use, reproduction,
39 | and distribution as defined by Sections 1 through 9 of this document.
40 |
41 | "Licensor" shall mean the copyright owner or entity authorized by
42 | the copyright owner that is granting the License.
43 |
44 | "Legal Entity" shall mean the union of the acting entity and all
45 | other entities that control, are controlled by, or are under common
46 | control with that entity. For the purposes of this definition,
47 | "control" means (i) the power, direct or indirect, to cause the
48 | direction or management of such entity, whether by contract or
49 | otherwise, or (ii) ownership of fifty percent (50%) or more of the
50 | outstanding shares, or (iii) beneficial ownership of such entity.
51 |
52 | "You" (or "Your") shall mean an individual or Legal Entity
53 | exercising permissions granted by this License.
54 |
55 | "Source" form shall mean the preferred form for making modifications,
56 | including but not limited to software source code, documentation
57 | source, and configuration files.
58 |
59 | "Object" form shall mean any form resulting from mechanical
60 | transformation or translation of a Source form, including but
61 | not limited to compiled object code, generated documentation,
62 | and conversions to other media types.
63 |
64 | "Work" shall mean the work of authorship, whether in Source or
65 | Object form, made available under the License, as indicated by a
66 | copyright notice that is included in or attached to the work
67 | (an example is provided in the Appendix below).
68 |
69 | "Derivative Works" shall mean any work, whether in Source or Object
70 | form, that is based on (or derived from) the Work and for which the
71 | editorial revisions, annotations, elaborations, or other modifications
72 | represent, as a whole, an original work of authorship. For the purposes
73 | of this License, Derivative Works shall not include works that remain
74 | separable from, or merely link (or bind by name) to the interfaces of,
75 | the Work and Derivative Works thereof.
76 |
77 | "Contribution" shall mean any work of authorship, including
78 | the original version of the Work and any modifications or additions
79 | to that Work or Derivative Works thereof, that is intentionally
80 | submitted to Licensor for inclusion in the Work by the copyright owner
81 | or by an individual or Legal Entity authorized to submit on behalf of
82 | the copyright owner. For the purposes of this definition, "submitted"
83 | means any form of electronic, verbal, or written communication sent
84 | to the Licensor or its representatives, including but not limited to
85 | communication on electronic mailing lists, source code control systems,
86 | and issue tracking systems that are managed by, or on behalf of, the
87 | Licensor for the purpose of discussing and improving the Work, but
88 | excluding communication that is conspicuously marked or otherwise
89 | designated in writing by the copyright owner as "Not a Contribution."
90 |
91 | "Contributor" shall mean Licensor and any individual or Legal Entity
92 | on behalf of whom a Contribution has been received by Licensor and
93 | subsequently incorporated within the Work.
94 |
95 | 2. Grant of Copyright License. Subject to the terms and conditions of
96 | this License, each Contributor hereby grants to You a perpetual,
97 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable
98 | copyright license to reproduce, prepare Derivative Works of,
99 | publicly display, publicly perform, sublicense, and distribute the
100 | Work and such Derivative Works in Source or Object form.
101 |
102 | 3. Grant of Patent License. Subject to the terms and conditions of
103 | this License, each Contributor hereby grants to You a perpetual,
104 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable
105 | (except as stated in this section) patent license to make, have made,
106 | use, offer to sell, sell, import, and otherwise transfer the Work,
107 | where such license applies only to those patent claims licensable
108 | by such Contributor that are necessarily infringed by their
109 | Contribution(s) alone or by combination of their Contribution(s)
110 | with the Work to which such Contribution(s) was submitted. If You
111 | institute patent litigation against any entity (including a
112 | cross-claim or counterclaim in a lawsuit) alleging that the Work
113 | or a Contribution incorporated within the Work constitutes direct
114 | or contributory patent infringement, then any patent licenses
115 | granted to You under this License for that Work shall terminate
116 | as of the date such litigation is filed.
117 |
118 | 4. Redistribution. You may reproduce and distribute copies of the
119 | Work or Derivative Works thereof in any medium, with or without
120 | modifications, and in Source or Object form, provided that You
121 | meet the following conditions:
122 |
123 | (a) You must give any other recipients of the Work or
124 | Derivative Works a copy of this License; and
125 |
126 | (b) You must cause any modified files to carry prominent notices
127 | stating that You changed the files; and
128 |
129 | (c) You must retain, in the Source form of any Derivative Works
130 | that You distribute, all copyright, patent, trademark, and
131 | attribution notices from the Source form of the Work,
132 | excluding those notices that do not pertain to any part of
133 | the Derivative Works; and
134 |
135 | (d) If the Work includes a "NOTICE" text file as part of its
136 | distribution, then any Derivative Works that You distribute must
137 | include a readable copy of the attribution notices contained
138 | within such NOTICE file, excluding those notices that do not
139 | pertain to any part of the Derivative Works, in at least one
140 | of the following places: within a NOTICE text file distributed
141 | as part of the Derivative Works; within the Source form or
142 | documentation, if provided along with the Derivative Works; or,
143 | within a display generated by the Derivative Works, if and
144 | wherever such third-party notices normally appear. The contents
145 | of the NOTICE file are for informational purposes only and
146 | do not modify the License. You may add Your own attribution
147 | notices within Derivative Works that You distribute, alongside
148 | or as an addendum to the NOTICE text from the Work, provided
149 | that such additional attribution notices cannot be construed
150 | as modifying the License.
151 |
152 | You may add Your own copyright statement to Your modifications and
153 | may provide additional or different license terms and conditions
154 | for use, reproduction, or distribution of Your modifications, or
155 | for any such Derivative Works as a whole, provided Your use,
156 | reproduction, and distribution of the Work otherwise complies with
157 | the conditions stated in this License.
158 |
159 | 5. Submission of Contributions. Unless You explicitly state otherwise,
160 | any Contribution intentionally submitted for inclusion in the Work
161 | by You to the Licensor shall be under the terms and conditions of
162 | this License, without any additional terms or conditions.
163 | Notwithstanding the above, nothing herein shall supersede or modify
164 | the terms of any separate license agreement you may have executed
165 | with Licensor regarding such Contributions.
166 |
167 | 6. Trademarks. This License does not grant permission to use the trade
168 | names, trademarks, service marks, or product names of the Licensor,
169 | except as required for reasonable and customary use in describing the
170 | origin of the Work and reproducing the content of the NOTICE file.
171 |
172 | 7. Disclaimer of Warranty. Unless required by applicable law or
173 | agreed to in writing, Licensor provides the Work (and each
174 | Contributor provides its Contributions) on an "AS IS" BASIS,
175 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
176 | implied, including, without limitation, any warranties or conditions
177 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
178 | PARTICULAR PURPOSE. You are solely responsible for determining the
179 | appropriateness of using or redistributing the Work and assume any
180 | risks associated with Your exercise of permissions under this License.
181 |
182 | 8. Limitation of Liability. In no event and under no legal theory,
183 | whether in tort (including negligence), contract, or otherwise,
184 | unless required by applicable law (such as deliberate and grossly
185 | negligent acts) or agreed to in writing, shall any Contributor be
186 | liable to You for damages, including any direct, indirect, special,
187 | incidental, or consequential damages of any character arising as a
188 | result of this License or out of the use or inability to use the
189 | Work (including but not limited to damages for loss of goodwill,
190 | work stoppage, computer failure or malfunction, or any and all
191 | other commercial damages or losses), even if such Contributor
192 | has been advised of the possibility of such damages.
193 |
194 | 9. Accepting Warranty or Additional Liability. While redistributing
195 | the Work or Derivative Works thereof, You may choose to offer,
196 | and charge a fee for, acceptance of support, warranty, indemnity,
197 | or other liability obligations and/or rights consistent with this
198 | License. However, in accepting such obligations, You may act only
199 | on Your own behalf and on Your sole responsibility, not on behalf
200 | of any other Contributor, and only if You agree to indemnify,
201 | defend, and hold each Contributor harmless for any liability
202 | incurred by, or claims asserted against, such Contributor by reason
203 | of your accepting any such warranty or additional liability.
204 |
205 | END OF TERMS AND CONDITIONS
206 | ```
207 |
208 | MIT Software License
211 |
212 | ```
213 | Permission is hereby granted, free of charge, to any person obtaining a copy
214 | of this software and associated documentation files (the "Software"), to deal
215 | in the Software without restriction, including without limitation the rights
216 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
217 | copies of the Software, and to permit persons to whom the Software is
218 | furnished to do so, subject to the following conditions:
219 |
220 | The above copyright notice and this permission notice shall be included in
221 | all copies or substantial portions of the Software.
222 |
223 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
224 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
225 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
226 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
227 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
228 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
229 | THE SOFTWARE.
230 | ```
231 |
232 |