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
npm install @subspace/reed-solomon-erasure.wasm
How to use
import {ReedSolomonErasure} from "@subspace/reed-solomon-erasure.wasm";
const reedSolomonErasure = await ReedSolomonErasure.fromCurrentDirectory();
const SHARD_SIZE = 4;
const DATA_SHARDS = 4;
const PARITY_SHARDS = 2;
const input = Uint8Array.of(
1, 2, 3, 4,
1, 2, 3, 4,
1, 2, 3, 4,
1, 2, 3, 4,
);
const shards = new Uint8Array(SHARD_SIZE * (DATA_SHARDS + PARITY_SHARDS));
shards.set(input.slice());
console.log(
'Encoding success: expect 0, result',
reedSolomonErasure.encode(shards, DATA_SHARDS, PARITY_SHARDS),
);
const corruptedShards = shards.slice();
corruptedShards.set([0, 0, 0, 0], 0);
corruptedShards.set([0, 0, 0, 0], SHARD_SIZE);
console.log('Corrupted shards 0 and 1');
const result = reedSolomonErasure.reconstruct(
corruptedShards,
DATA_SHARDS,
PARITY_SHARDS,
[false, false, true, true, true, true],
);
console.log(
'Reconstructing corrupted data shards: expect 0, result',
result,
);
console.log(
'Original data shards: ',
input.join(', '),
);
console.log(
'Reconstructed data shards:',
corruptedShards.slice(0, SHARD_SIZE * DATA_SHARDS).join(', '),
);
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:
fetch('https://domain.tld/path/to/reed_solomon_erasure_bg.wasm')
.then(ReedSolomonErasure.fromResponse)
.then((reedSolomonErasure) => {
// Use library here
})
ReedSolomonErasure.fromBytes(bytes: BufferSource): ReedSolomonErasure
Static method for synchronous instantiation, primarily in Node.js environment, usage example:
const reedSolomonErasure = ReedSolomonErasure.fromBytes(
require('fs').readFileSync(`/path/to/reed_solomon_erasure_bg.wasm`)
);
// 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