This is an automated email from the ASF dual-hosted git repository.
kocolosk pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/couchdb-b64url.git
commit 699f471ded9eaefaa06a20dfd56629d4e87f31b2
Author: Adam Kocoloski <adam.kocolo...@airbnb.com>
AuthorDate: Mon Nov 15 22:58:34 2021 -0500
Metadata / README updates, branch protection
---
.asf.yaml | 21 +++++++++++++++++++++
README.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++
README.rst | 16 ----------------
src/b64url.app.src | 2 +-
4 files changed, 68 insertions(+), 17 deletions(-)
diff --git a/.asf.yaml b/.asf.yaml
new file mode 100644
index 0000000..cc29d3d
--- /dev/null
+++ b/.asf.yaml
@@ -0,0 +1,21 @@
+github:
+ description: "URL-safe Base64 encoder"
+ labels:
+ - couchdb
+ - erlang
+ - nif
+ features:
+ issues: true
+ enabled_merge_buttons:
+ squash: true
+ rebase: true
+ merge: true
+ protected_branches:
+ main:
+ required_status_checks:
+ strict: true
+
+notifications:
+ commits: commits@couchdb.apache.org
+ issues: notificati...@couchdb.apache.org
+ pullrequests: notificati...@couchdb.apache.org
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..c3a3497
--- /dev/null
+++ b/README.md
@@ -0,0 +1,46 @@
+# Base64 encoder with URL-safe scheme
+
+[](https://github.com/apache/couchdb-b64url/actions/workflows/ci.yml)
+
+This is a simple NIF that is responsible for quickly encoding and
+decoding Base64 URL values:
+
+```erlang
+1> Thing = b64url:encode("Hello, CouchDB!").
+<<"SGVsbG8sIENvdWNoREIh">>
+2> b64url:decode(Thing).
+<<"Hello, CouchDB!">>
+```
+
+## Performance
+
+This implementation is significantly faster than the Erlang version it replaced
+in CouchDB. The `benchmark.escript` file contains the original implementation
+(using regular expressions to replace unsafe characters in the output of the
+`base64` module) and can be used to compare the two for strings of various
+lengths. For example:
+
+```
+ERL_LIBS=_build/default/lib/b64url/ ./test/benchmark.escript 4 10 100 30
+erl : 75491270 bytes / 30 seconds = 2516375.67 bps
+nif : 672299342 bytes / 30 seconds = 22409978.07 bps
+```
+
+This test invocation spawns four workers that generate random strings between
10
+and 100 bytes in length and then perform an encode/decode on them in a tight
+loop for 30 seconds, and then reports the aggregate encoded data volume. Note
+that the generator overhead (`crypto:strong_rand_bytes/1`) is included in these
+results, so the relative difference in encoder throughput is rather larger than
+what's reported here.
+
+## Timeslice Consumption
+
+NIF implementations must take care to avoid doing [lengthy
+work](https://www.erlang.org/doc/man/erl_nif.html#lengthy_work) in a single
+invocation. This library will yield back to the Erlang VM as needed when
+operating on a large string, maintaining a partial result until it can resume
+operation. The current implementation uses a conservative heuristic that
+estimates 64 bytes of encoding / decoding to consume 1% of a timeslice, so
input
+strings shorter than ~6k should be encoded / decoded within a single
invocation,
+and the library should not adversely affect the responsiveness of the VM in any
+way.
diff --git a/README.rst b/README.rst
deleted file mode 100644
index 38484ae..0000000
--- a/README.rst
+++ /dev/null
@@ -1,16 +0,0 @@
-==============
-couchdb-b64url
-==============
-
-This is a pretty simple NIF that is just responsible for encoding and decoding
-Base46 URL values::
-
- 1> Thing = b64url:encode("Hello, CouchDB!").
- <<"SGVsbG8sIENvdWNoREIh">>
- 2> b64url:decode(Thing).
- <<"Hello, CouchDB!">>
-
-License
-=======
-
-Apache 2.0
diff --git a/src/b64url.app.src b/src/b64url.app.src
index a2a8913..aaf8e9f 100644
--- a/src/b64url.app.src
+++ b/src/b64url.app.src
@@ -14,5 +14,5 @@
{description, "A small NIF for encoding Base64 URL encoding/decoding."},
{vsn, git},
{registered, []},
- {applications, [kernel]}
+ {applications, [kernel, stdlib]}
]}.
