philiprehberger-base64_url
v0.8.0392,443 downloadsMIT
URL-safe Base64 encoding with optional padding and JSON helpers
$
gem install philiprehberger-base64_urlREADME
philiprehberger-base64_url
URL-safe Base64 encoding with optional padding and JSON helpers
Requirements
- Ruby >= 3.1
Installation
Add to your Gemfile:
gem "philiprehberger-base64_url"
Or install directly:
gem install philiprehberger-base64_url
Usage
require "philiprehberger/base64_url"
encoded = Philiprehberger::Base64Url.encode('hello world')
# => "aGVsbG8gd29ybGQ"
decoded = Philiprehberger::Base64Url.decode(encoded)
# => "hello world"
Padding Control
require "philiprehberger/base64_url"
Philiprehberger::Base64Url.encode("Hello") # => "SGVsbG8" (no padding)
Philiprehberger::Base64Url.encode("Hello", padding: true) # => "SGVsbG8=" (with padding)
Validation
Philiprehberger::Base64Url.valid?("aGVsbG8") # => true
Philiprehberger::Base64Url.valid?("!!!") # => false
JSON Helpers
token = Philiprehberger::Base64Url.encode_json({ user_id: 42, role: 'admin' })
# => URL-safe Base64 string
payload = Philiprehberger::Base64Url.decode_json(token)
# => {"user_id"=>42, "role"=>"admin"}
Constant-Time Comparison
token_a = Philiprehberger::Base64Url.encode("secret")
token_b = params[:token]
Philiprehberger::Base64Url.secure_compare(token_a, token_b) # => true/false
Decoded Size
Philiprehberger::Base64Url.byte_length("aGVsbG8gd29ybGQ") # => 11
Encoded Size
Pre-compute the unpadded URL-safe Base64 length for n input bytes without
encoding — useful for token sizing and buffer allocation.
Philiprehberger::Base64Url.encoded_length(0) # => 0
Philiprehberger::Base64Url.encoded_length(16) # => 22 (UUID)
Philiprehberger::Base64Url.encoded_length(32) # => 43 (default token)
File Helpers
encoded = Philiprehberger::Base64Url.encode_file("image.png")
Philiprehberger::Base64Url.decode_to_file(encoded, "copy.png")
Convert between URL-safe and standard Base64
Philiprehberger::Base64Url.to_std("SGVsbG8") # => "SGVsbG8="
Philiprehberger::Base64Url.to_std("a-b_c") # => "a+b/c==="
Philiprehberger::Base64Url.from_std("SGVsbG8=") # => "SGVsbG8"
Philiprehberger::Base64Url.from_std("a+b/c==") # => "a-b_c"
Random token
Philiprehberger::Base64Url.random
# => "Xk8...k2Q" (43-char URL-safe Base64 of 32 random bytes, no padding)
Philiprehberger::Base64Url.random(bytes: 16)
# => 22-char URL-safe Base64 token
Compact UUIDs
Shorten a 36-character canonical UUID into a 22-character URL-safe Base64 string (no padding) and decode back to the original canonical form.
token = Philiprehberger::Base64Url.encode_uuid("f47ac10b-58cc-4372-a567-0e02b2c3d479")
# => "9HrBC1jMQ3KlZw4Cssx0eQ" (22 chars)
Philiprehberger::Base64Url.decode_uuid(token)
# => "f47ac10b-58cc-4372-a567-0e02b2c3d479"
API
| Method | Description |
|---|---|
.encode(data, padding: false) | Encode data to URL-safe Base64 (optional padding) |
Base64Url.random(bytes: 32) | Generate a URL-safe Base64 random token |
.decode(data) | Decode a URL-safe Base64 string |
.encode_json(hash) | Encode a hash as JSON then URL-safe Base64 |
.decode_json(str) | Decode a URL-safe Base64 string and parse as JSON |
.valid?(data) | Check if a string is valid URL-safe Base64 |
.secure_compare(a, b) | Constant-time comparison of two strings |
.byte_length(encoded) | Calculate decoded byte count without decoding |
.encoded_length(bytes) | Length of the unpadded URL-safe Base64 encoding for n bytes of input |
.encode_file(path, padding: false) | Encode a file's contents to URL-safe Base64 |
.decode_to_file(encoded, path) | Decode and write to a file |
.to_std(data) | Convert URL-safe Base64 to standard Base64 (adds = padding, swaps -_ for +/) |
.from_std(data) | Convert standard Base64 to URL-safe Base64 (strips = padding, swaps +/ for -_) |
.encode_uuid(uuid) | Encode a canonical UUID as a compact 22-character URL-safe Base64 string |
.decode_uuid(encoded) | Decode a 22-character URL-safe Base64 string back to a canonical lowercase UUID |
Development
bundle install
bundle exec rspec
bundle exec rubocop
Support
If you find this project useful: