@keetanetwork/asn1-napi-rs

About

This project utilizes napi-rs to build native Rust functionality that can be consumed in NodeJS. This library specifically addresses ASN.1 encoding and decoding for the @keetanetwork/node project. It contains all critical functionality for encoding/decoding ASN.1 BER for all KeetaNet node functionality.

Install this package

npm install @keetanetwork/asn1-napi-rs

Note: You will need a GitHub personal access token added to your ~/.npmrc file like so:

//npm.pkg.github.com/:_authToken=YOUR_TOKEN

Supported Environments

	node14	node16	node18
Windows x64	✓	✓	✓
Windows x32	✓	✓	✓
Windows arm64	✓	✓	✓
macOS x64	✓	✓	✓
macOS arm64	✓	✓	✓
Linux x64 gnu	✓	✓	✓
Linux x64 musl	✓	✓	✓
Linux arm gnu	✓	✓	✓
Linux arm64 gnu	✓	✓	✓
Linux arm64 musl	✓	✓	✓
Android arm64	✓	✓	✓
Android armv7	✓	✓	✓
FreeBSD x64	✓	✓	✓

Requirements

• Install the latest Rust (Minimum supported v1.60.0)
• Install Node.js@14+ which fully supported Node-API

Setup

Once prerequisites are installed, you can setup the initial project easily using:

make node_modules

Building

You can build the entire project or just the rust using the following:

make

Testing

All JavaScript/TypeScript tests are located in the tests directory within the project root. All Rust tests are located in a test module in the file containing the code to be tested. With ava, run make test to testing native addon.

make test

And you will see:

$ make test
running [number] tests
test asn1::test::test_asn1_into_bytes ... ok
test asn1::test::test_asn1_into_date ... ok
...

  ✔ integer › JS number to ASN1 conversion
  ✔ integer › ASN1 to Js number conversion from byte code
  ✔ integer › ASN1 to Js number conversion from base64
  ✔ integer › ASN1 to Js number conversion round trip
  ...

  [number] tests passed

Benchmarking

There are a few benchmarks of critical functionality available which tests the Rust implementations of functions against their TypeScript counterparts. You can run these tests using:

make do-bench

And you will see:

Running "Encode/Decode Block from Buffer" suite...
Progress: 100%

  Rust ASN1toJS - JStoASN1 Test Block:
    25 048 ops/s, ±3.18%   | fastest

  JavaScript ASN1toJS - JStoASN1 Test Block:
    1 817 ops/s, ±4.89%    | slowest, 92.75% slower

Finished 2 cases!
  Fastest: Rust ASN1toJS - JStoASN1 Test Block
  Slowest: JavaScript ASN1toJS - JStoASN1 Test Block
...

Functionality

Key function exports:

• JStoASN1
• ASN1toJS
• ASN1BigIntToBuffer
• ASN1IntegerToBigInt

CI/CD

With GitHub Actions, each commit and pull request will be built and tested automatically in [node@14, node@16, @node18] x [macOS, Linux, Windows] matrix.

Release

Releases are managed through GitHub actions. Once ready, tag a release like so using the semantic versioning style prefixed with a "v":

# Creates an annotated tag
git tag -s -a "v1.x.x" -m ":bookmark: v1.x.x"
# Pushes tags to remote
git push --tags

Then, create a release in GitHub which will trigger the GitHub action and deploy new GitHub NPM package for the release. The rest will be done for you and you can then require the new version as usual in the project this library is used in.