alap (Ruby)

Server-side Ruby port of Alap — the expression parser that turns curated link queries (.coffee + :time:7d:) into resolved link results.

This gem ships the parser only — for the full client experience (menus, adapters, the lightbox/lens renderers), see the main TypeScript package on npm.

Install

gem install alap

Or in a Gemfile:

gem "alap"

Requires Ruby 3.0 or later.

Quick usage

require "alap"

config = {
  "settings" => { "listType" => "ul" },
  "allLinks" => {
    "brooklyn"  => { "label" => "Brooklyn Bridge",  "url" => "https://en.wikipedia.org/wiki/Brooklyn_Bridge",  "tags" => ["nyc", "bridge"] },
    "manhattan" => { "label" => "Manhattan Bridge", "url" => "https://en.wikipedia.org/wiki/Manhattan_Bridge", "tags" => ["nyc", "bridge"] },
    "highline"  => { "label" => "The High Line",   "url" => "https://en.wikipedia.org/wiki/High_Line",         "tags" => ["nyc", "park"] }
  }
}

links = Alap.resolve_expression(config, ".nyc + .bridge")
links.each { |link| puts "#{link['label']} -> #{link['url']}" }
# Brooklyn Bridge -> https://en.wikipedia.org/wiki/Brooklyn_Bridge
# Manhattan Bridge -> https://en.wikipedia.org/wiki/Manhattan_Bridge

The expression grammar (tags, operators, macros, regex search, refiners) is documented at https://docs.alap.info/core-concepts/expressions. This port covers the parser, security helpers, and config validation — the same surface as the Go, Python, PHP, Java, and Rust ports.

Security helpers

# URL sanitization (blocks javascript:, data:, etc.)
Alap::SanitizeUrl.sanitize("https://example.com")    # => "https://example.com"
Alap::SanitizeUrl.sanitize("javascript:alert(1)")   # => "about:blank"

# SSRF guard for outbound fetches
Alap::SsrfGuard.private_host?("http://10.0.0.1")   # => true
Alap::SsrfGuard.private_host?("https://example.com") # => false

# ReDoS protection for user-supplied regex
Alap::ValidateRegex.dangerous?("^(a+)+$")   # => true

Server integration

A complete Sinatra + SQLite reference server using this gem lives in the main repo at examples/servers/sinatra-sqlite/.

License

Apache-2.0. See LICENSE.