ob64 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 110cd68288a2dd3ff785dca2a4dc2bdc0b3d47445fae88d0fef3a3a3db1b0d96
-  data.tar.gz: a0d837a2ba44079613b99fd862cdf156d3105b69359edbefeae32711a2be402e
+  metadata.gz: 93d2eaeaa970d18c2ab92ff9f5bb4621c22135c16faa0f1ef09ac71babe94b95
+  data.tar.gz: 7bad60e17ca1b3189634cb2043d58bf1ffa85c701deff0b99886dde4a34082e1
 SHA512:
-  metadata.gz: 6a4fa2cabc1fad23055020ed1c49906de65e494f82fbf19966cc0a511cc8e073026dc77c4e0cb9b57d77d67e21f068fdbf79c6dfa2de978381444e1793a4793a
-  data.tar.gz: 432523720a899411c6a3840fc410bd4e540b7f8211dda82dff2643046959ce52ceec8bc0a8f15a6518bddb913cce69129b52ade76d8dbd33f3a7e980a690c693
+  metadata.gz: fc8c44a79e33c420a13c1d4460a2773ed6d60ff0e4eab47ea5ad0a1db4365d85c4e642e442dfa4a2753ef0153f8bde876dca4867005f28c124f4b7251b06e55d
+  data.tar.gz: 61b2550bc2035667a86d6bfd87149fcba0bd3faa33d9e29c6f42f89cef8be2b5e5df6a36a35682e2cb9d193ea1252ee7d37bcb1d787d0c62cfa78d1618218144

data/.github/scripts/install-sde

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# Installs Intel SDE if this CPU can't run the avx512 codec, and exports SDE,
+# a command prefix that emulates a CPU that can.
+set -euo pipefail
+
+missing=
+for flag in avx512vl avx512vbmi avx512_vbmi2; do
+  grep -qw "$flag" /proc/cpuinfo || missing=1
+done
+[ -n "$missing" ] || exit 0
+
+url=https://downloadmirror.intel.com/924984/sde-external-10.13.1-2026-07-28-lin.tar.xz
+sha256=94e97d623fec54385686e1e7ba65ebc9941748c05ee451423948334892bf2b50
+dir="$RUNNER_TEMP/sde"
+
+curl -fsSL -o "$dir.tar.xz" "$url"
+echo "$sha256  $dir.tar.xz" | sha256sum -c --quiet
+mkdir -p "$dir"
+tar xJf "$dir.tar.xz" -C "$dir" --strip-components=1
+# Ice Lake: AVX512 with VBMI and VBMI2
+echo "SDE=$dir/sde64 -icl --" >>"$GITHUB_ENV"

data/.github/workflows/main.yml

@@ -36,8 +36,15 @@ jobs:
         ruby: ["3.3", "3.4", "4.0"]
         os: [ubuntu-24.04, ubuntu-24.04-arm]
         cc: [gcc, clang]
+        include:
+          # Ruby built with AddressSanitizer, x86-64 only: memory errors in the
+          # C code fail the specs. ubsan adds UndefinedBehaviorSanitizer.
+          - ruby: asan-release
+            os: ubuntu-24.04
+            cc: clang
+            ubsan: true
     runs-on: ${{ matrix.os }}
-    timeout-minutes: 15
+    timeout-minutes: 30
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
@@ -55,14 +62,57 @@ jobs:
       - name: Compile
         env:
           # Same warnings for both compilers; Ruby's defaults are GCC-only.
-          MAKEFLAGS: 'CC=${{ matrix.cc }} warnflags=-Wall\ -Wextra\ -Wno-unused-parameter\ -Werror'
+          MAKEFLAGS: >-
+            CC=${{ matrix.cc }}${{ matrix.ubsan && '\ -fsanitize=undefined\ -fno-sanitize-recover=all' || '' }}
+            warnflags=-Wall\ -Wextra\ -Wno-unused-parameter\ -Werror
         run: bundle exec rake compile
 
+      - name: Install Intel SDE if the CPU lacks AVX512
+        if: runner.arch == 'X64'
+        run: .github/scripts/install-sde
+
       - name: Show codecs
-        run: bundle exec ruby -Ilib -rob64 -e 'p Ob64.codecs, Ob64.codec'
+        run: $SDE bundle exec ruby -Ilib -rob64 -e 'p Ob64.codecs, Ob64.codec'
+
+      - name: Test
+        env:
+          # Fails the codec spec if one is missing
+          OB64_CODECS: ${{ runner.arch == 'X64' && 'scalar,avx2,avx512' || 'scalar,neon64' }}
+        run: $SDE bundle exec rake spec
+
+  codecs:
+    # The C codecs alone under ASan and UBSan, on exact-size buffers.
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-24.04, ubuntu-24.04-arm]
+        cc: [gcc, clang]
+    runs-on: ${{ matrix.os }}
+    # Long under SDE, which emulates AVX512 slowly
+    timeout-minutes: 90
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: ruby/setup-ruby@7f797815d8adceb1c412e7abefdd1ab4abc47a5f # v1.335.0
+        with:
+          ruby-version: "3.4"
+          bundler-cache: true
+
+      - name: Install Clang
+        if: matrix.cc == 'clang'
+        run: command -v clang || { sudo apt-get update && sudo apt-get install -y clang; }
+
+      - name: Install Intel SDE if the CPU lacks AVX512
+        if: runner.arch == 'X64'
+        run: .github/scripts/install-sde
 
       - name: Test
-        run: bundle exec rake spec
+        env:
+          CC: ${{ matrix.cc }}
+          OB64_CODECS: ${{ runner.arch == 'X64' && 'scalar,avx2,avx512' || 'scalar,neon64' }}
+        run: bundle exec rake spec:c
 
   package:
     runs-on: ubuntu-24.04

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+## [0.8.0] - 2026-10-27
+
+- Fix undefined behavior in AVX512 detection.
+- `Ob64::Base64::RFC4648.encode` and `encode_urlsafe` return US-ASCII Strings, like `pack("m0")` (were BINARY).
+
 ## [0.7.0] - 2026-10-26
 
 - **Breaking:** Split `Ob64::Base64` into one module per RFC. `Ob64::Base64::RFC4648` has `encode`, `decode`, `encode_urlsafe`, `decode_urlsafe`, `encoded_length_of` and `decoded_length_of` (were `Ob64::Base64.encode`, `decode`, `urlsafe_encode`, `urlsafe_decode`, `encoded_length_of` and `decoded_length_of`).

data/README.md

@@ -2,13 +2,56 @@
 
 [![Gem Version](https://badge.fury.io/rb/ob64.svg)](http://rubygems.org/gems/ob64)
 [![CI](https://github.com/jcmfernandes/ob64/actions/workflows/main.yml/badge.svg?branch=master)](https://github.com/jcmfernandes/ob64/actions/workflows/main.yml)
-[![Yard Docs](https://img.shields.io/badge/yard-docs-blue.svg)](http://www.rubydoc.info/gems/ob64/0.7.0)
+[![Yard Docs](https://img.shields.io/badge/yard-docs-blue.svg)](http://www.rubydoc.info/gems/ob64/0.8.0)
 
 A *fast* Base64 and uuencode encoder and decoder as a Ruby gem.
 
-How fast? Try it yourself, execute:
+How fast? Times faster than Ruby's own `pack` / `unpack1`, per call, measured with `benchmark.rb` on an AMD Ryzen 9 9900X (AVX512) with Ruby 3.4:
 
-    $ rake benchmark
+```mermaid
+%%{init: {"themeVariables": {"xyChart": {"plotColorPalette": "#2a78d6"}}}}%%
+xychart-beta
+    title "1 kB input: times faster than Ruby"
+    x-axis ["m0 enc", "m0 dec", "url enc", "url dec", "m enc", "m dec", "u enc", "u dec"]
+    y-axis "times faster" 0 --> 45
+    bar [3.1, 4.8, 11.1, 12.6, 5.2, 3.9, 5.9, 4.2]
+```
+
+```mermaid
+%%{init: {"themeVariables": {"xyChart": {"plotColorPalette": "#2a78d6"}}}}%%
+xychart-beta
+    title "4 kB input: times faster than Ruby"
+    x-axis ["m0 enc", "m0 dec", "url enc", "url dec", "m enc", "m dec", "u enc", "u dec"]
+    y-axis "times faster" 0 --> 45
+    bar [6.3, 8.4, 17.6, 22.9, 8.4, 6.1, 7.5, 5.2]
+```
+
+```mermaid
+%%{init: {"themeVariables": {"xyChart": {"plotColorPalette": "#2a78d6"}}}}%%
+xychart-beta
+    title "16 kB input: times faster than Ruby"
+    x-axis ["m0 enc", "m0 dec", "url enc", "url dec", "m enc", "m dec", "u enc", "u dec"]
+    y-axis "times faster" 0 --> 45
+    bar [11.1, 12.6, 24.3, 32.8, 6.0, 7.0, 7.2, 5.3]
+```
+
+```mermaid
+%%{init: {"themeVariables": {"xyChart": {"plotColorPalette": "#2a78d6"}}}}%%
+xychart-beta
+    title "512 kB input: times faster than Ruby"
+    x-axis ["m0 enc", "m0 dec", "url enc", "url dec", "m enc", "m dec", "u enc", "u dec"]
+    y-axis "times faster" 0 --> 45
+    bar [14.0, 13.8, 39.2, 42.0, 7.7, 7.6, 7.3, 5.3]
+```
+
+- `m0`: RFC 4648 (`Ob64::Base64::RFC4648.encode` / `decode`)
+- `url`: RFC 4648 URL-safe (`encode_urlsafe` / `decode_urlsafe`), against Ruby's `pack("m0")` plus `tr`
+- `m`: RFC 2045 (`Ob64::Base64::RFC2045.encode` / `decode`)
+- `u`: uuencode (`Ob64::UU.encode` / `decode`)
+
+Try it yourself:
+
+    $ bin/rake compile benchmark
 
 ## Acknowledgements
 
@@ -115,7 +158,7 @@ See [{file:CHANGELOG.md}](CHANGELOG.md).
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests, and `rake spec:c` to check the C codecs for memory errors. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 

data/Rakefile

@@ -14,6 +14,17 @@ Rake::ExtensionTask.new("ob64_ext") do |ext|
   ext.ext_dir = "ext/ob64"
 end
 
+desc "Check the SIMD codecs against scalar in C, under ASan and UBSan; SEED=n repeats a run"
+task "spec:c" do
+  mkdir_p "tmp"
+  sh "#{ENV.fetch("CC", "cc")} -std=gnu99 -O3 -g -fsanitize=address,undefined -fno-sanitize-recover=all " \
+    "-fno-omit-frame-pointer -Wall -Wextra -Wno-unused-parameter -Werror -Iext/ob64 -o tmp/codecs_test " \
+    "spec/c/codecs_test.c ext/ob64/pack_base64.c ext/ob64/pack_uuencode.c"
+  # SDE: an emulator prefix, see .github/scripts/install-sde. It must run the test
+  # itself: under SDE, ASan programs started by another one exit 0 unrun.
+  sh "#{ENV["SDE"]} tmp/codecs_test #{ENV["SEED"]}"
+end
+
 desc "Run benchmark"
 task :benchmark do
   load "#{__dir__}/benchmark.rb"

data/ext/ob64/ob64_ext.c

@@ -1,5 +1,6 @@
 #include <stdbool.h>
 #include "ob64.h"
+#include "ruby/encoding.h"
 
 VALUE mOb64 = Qnil;
 VALUE mOb64_Ext = Qnil;
@@ -51,6 +52,8 @@ VALUE Ob64_encode_string(VALUE self, VALUE bin, VALUE urlsafe, VALUE padding)
 
   pack_base64_encode(RSTRING_PTR(bin), bin_len, RSTRING_PTR(result), flags);
   rb_str_set_len(result, __encoded_length_of(bin_len, RTEST(padding)));
+  /* US-ASCII, as pack("m0") */
+  ENCODING_CODERANGE_SET(result, rb_usascii_encindex(), ENC_CODERANGE_7BIT);
   RB_GC_GUARD(bin);
 
   return result;

data/ext/ob64/pack_base64.c

@@ -4359,7 +4359,7 @@ pack_base64_xgetbv (uint32_t index)
 }
 
 #ifndef bit_AVX512vl
-#define bit_AVX512vl (1 << 31)
+#define bit_AVX512vl (1u << 31)
 #endif
 #ifndef bit_AVX512vbmi
 #define bit_AVX512vbmi (1 << 1)

data/lib/ob64/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Ob64
-  VERSION = "0.7.0"
+  VERSION = "0.8.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ob64
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - João Fernandes
@@ -19,6 +19,7 @@ extensions:
 extra_rdoc_files: []
 files:
 - ".github/dependabot.yml"
+- ".github/scripts/install-sde"
 - ".github/workflows/main.yml"
 - ".gitignore"
 - ".rspec"
@@ -59,8 +60,8 @@ licenses:
 metadata:
   homepage_uri: https://github.com/jcmfernandes/ob64
   changelog_uri: https://github.com/jcmfernandes/ob64/blob/master/CHANGELOG.md
-  documentation_uri: https://www.rubydoc.info/gems/ob64/0.7.0
-  source_code_uri: https://github.com/jcmfernandes/ob64/tree/v0.7.0
+  documentation_uri: https://www.rubydoc.info/gems/ob64/0.8.0
+  source_code_uri: https://github.com/jcmfernandes/ob64/tree/v0.8.0
 rdoc_options: []
 require_paths:
 - lib