funcnode-utils

A Crystal library of small, focused utility classes.

Top-level documentation with examples: doc/index.html.

Everything lives under Funcnode::Utils. Features are grouped by area, each as a self-contained submodule:

• Exceptions::Persistent — durable, rate-limited exception persistence to disk.
• Crypto::Sha — pure, thread-safe SHA-256 / SHA-512 hashing of files, bytes, or streams.
• Notifications::Telegram — long-lived, best-effort, debounced admin alerts to a Telegram bot.

Installation

1. Add the dependency to your shard.yml:

   dependencies:
     funcnode-utils:
       gitlab: funcnode_crystal/funcnode-utils
   

2. Run shards install

Usage

require "funcnode-utils"

alias Persistent = Funcnode::Utils::Exceptions::Persistent

# Long-lived: create once at startup.
config = Persistent::Config.new
config.output_dir = "exceptions"
persister = Persistent::Persister.new(config)

begin
  do_risky_work
rescue ex
  # Saved to a per-exception folder under `output_dir`.
  # Identical exceptions are rate-limited and their count recorded.
  persister.save(ex, message: "while processing job 42")
end

persister.close # flush pending duplicate counters on shutdown

Persister is thread-safe (works under -Dpreview_mt) and works in both debug and --no-debug builds. Configuration can also be loaded from a YAML file, in which case #update rewrites it (as the commented template, so the comments survive). A missing file is created from that template and construction then fails, so nothing starts on a config the operator has not seen — see the config contract in doc/index.html, along with the full API, the on-disk layout, binary-body humanization, and rate-limiting details.

Development

crystal spec                     # run tests
crystal spec -Dpreview_mt        # run tests under the multi-threaded runtime
crystal tool format              # format sources

Contributing

1. Fork it (https://gitlab.com/funcnode_crystal/funcnode-utils/-/forks/new)
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Merge Request

Contributors

• Vasily Buter - creator and maintainer