reed-solomon-erasure.wasm

reed-solomon-erasure Rust library compiled to WebAssembly and optimized for small size.

This library aims to provide relatively low-level, yet simple to use API to Reed-Solomon erasure coding. Library works both in modern browsers and Node.js environment with TypeScript support.

How to install

1npm install @subspace/reed-solomon-erasure.wasm

How to use

1import {ReedSolomonErasure} from "@subspace/reed-solomon-erasure.wasm";
2
3const reedSolomonErasure = await ReedSolomonErasure.fromCurrentDirectory();
4const SHARD_SIZE = 4;
5const DATA_SHARDS = 4;
6const PARITY_SHARDS = 2;
7
8const input = Uint8Array.of(
9    1, 2, 3, 4,
10    1, 2, 3, 4,
11    1, 2, 3, 4,
12    1, 2, 3, 4,
13);
14
15const shards = new Uint8Array(SHARD_SIZE * (DATA_SHARDS + PARITY_SHARDS));
16shards.set(input.slice());
17
18console.log(
19    'Encoding success: expect 0, result',
20    reedSolomonErasure.encode(shards, DATA_SHARDS, PARITY_SHARDS),
21);
22
23const corruptedShards = shards.slice();
24corruptedShards.set([0, 0, 0, 0], 0);
25corruptedShards.set([0, 0, 0, 0], SHARD_SIZE);
26
27console.log('Corrupted shards 0 and 1');
28
29const result = reedSolomonErasure.reconstruct(
30    corruptedShards,
31    DATA_SHARDS,
32    PARITY_SHARDS,
33    [false, false, true, true, true, true],
34);
35
36console.log(
37    'Reconstructing corrupted data shards: expect 0, result',
38    result,
39);
40console.log(
41    'Original data shards:     ',
42    input.join(', '),
43);
44console.log(
45    'Reconstructed data shards:',
46    corruptedShards.slice(0, SHARD_SIZE * DATA_SHARDS).join(', '),
47);

API

ReedSolomonErasure.fromCurrentDirectory(): Promise

Static automagical method that will try to detect environment (Node.js or browser) and load *.wasm file from current directory

ReedSolomonErasure.fromCurrentDirectory(source: Response): Promise

Static method for asynchronous instantiation, primarily in Browser environment, expects you to load WASM file with fetch(), usage example:

1fetch('https://domain.tld/path/to/reed_solomon_erasure_bg.wasm')
2    .then(ReedSolomonErasure.fromResponse)
3    .then((reedSolomonErasure) => {
4        // Use library here
5    })

ReedSolomonErasure.fromBytes(bytes: BufferSource): ReedSolomonErasure

Static method for synchronous instantiation, primarily in Node.js environment, usage example:

1const reedSolomonErasure = ReedSolomonErasure.fromBytes(
2    require('fs').readFileSync(`/path/to/reed_solomon_erasure_bg.wasm`)
3);
4// Use library here

ReedSolomonErasure.encode(shards: Uint8Array, dataShards: number, parityShards: number): number

Takes a contiguous array of bytes that contain space for data_shards + parity_shards shards with data_shards shards containing data and fills additional parity_shards with parity information that can be later used to reconstruct data in case of corruption.

Returns one of ReedSolomonErasure.RESULT_* constants; if ReedSolomonErasure.RESULT_OK then parity shards were updated in shards in-place.

ReedSolomonErasure.reconstruct(shards: Uint8Array, dataShards: number, parityShards: number, shardsAvailable: boolean[]): number

Takes a contiguous array of bytes that contain data_shards + parity_shards shards and tries to reconstruct data shards if they are broken and whenever possible using information from shards_available (contains data_shards + parity_shards boolean values, each of which is either true if shard is not corrupted or false if it is).

Returns one of ReedSolomonErasure.RESULT_* constants; if ReedSolomonErasure.RESULT_OK then data shards were reconstructed in shards in-place.

Constants

Below constants are used to check the result of encoding/reconstruction:

• ReedSolomonErasure.RESULT_OK
• ReedSolomonErasure.RESULT_ERROR_TOO_FEW_SHARDS
• ReedSolomonErasure.RESULT_ERROR_TOO_MANY_SHARDS
• ReedSolomonErasure.RESULT_ERROR_TOO_FEW_DATA_SHARDS
• ReedSolomonErasure.RESULT_ERROR_TOO_MANY_DATA_SHARDS
• ReedSolomonErasure.RESULT_ERROR_TOO_FEW_PARITY_SHARDS
• ReedSolomonErasure.RESULT_ERROR_TOO_MANY_PARITY_SHARDS
• ReedSolomonErasure.RESULT_ERROR_TOO_FEW_BUFFER_SHARDS
• ReedSolomonErasure.RESULT_ERROR_TOO_MANY_BUFFER_SHARDS
• ReedSolomonErasure.RESULT_ERROR_INCORRECT_SHARD_SIZE
• ReedSolomonErasure.RESULT_ERROR_TOO_FEW_SHARDS_PRESENT
• ReedSolomonErasure.RESULT_ERROR_EMPTY_SHARD
• ReedSolomonErasure.RESULT_ERROR_INVALID_SHARD_FLAGS
• ReedSolomonErasure.RESULT_ERROR_INVALID_INDEX

Tests

Project is covered with tests that ensure things work as expected and do not regress, run them with usual npm test.

License

MIT, see license.txt