Fingerly for Ruby
Read device intelligence events, verify webhooks and serve the browser SDK from your own domain.
The fingerly gem is the server-side SDK for Ruby. It reads Fingerly events
with a secret key, verifies webhook signatures and relays the browser SDK's
traffic through your own domain with a same-origin Rack proxy. It has no
runtime dependencies and is for backends that protect signups, logins and
payments from fraud and abuse. Fingerly identifies the
device behind each session and scores how suspicious it is.
-
Prerequisites. A Fingerly account and a secret key (
fly_sk_...). See API keys and environments. Ruby 3.2+. -
Install. Add it to your
Gemfile:gem "fingerly", "~> 0.4.1"
-
Read an event.
require "fingerly" fingerly = Fingerly::Client.new(secret_key: ENV.fetch("FINGERLY_SECRET_KEY")) request_id = ARGV.fetch(0) # the requestId the browser SDK's identify() returned event = fingerly.events.get(request_id) page = fingerly.events.list(level: Fingerly::SuspectLevel::HIGH, limit: 50) page.each { |row| puts "#{row.request_id} #{row.suspect_level}" }
-
Verify a webhook.
class FingerlyWebhooksController < ActionController::API def create payload = request.raw_post valid = Fingerly::Webhooks.verify( secret: ENV.fetch("FINGERLY_WEBHOOK_SECRET"), payload: payload, timestamp: request.headers["x-fingerly-timestamp"], signature: request.headers["x-fingerly-signature"] ) return head :bad_request unless valid event = Fingerly::Webhooks.parse(payload) # Hand the work to your own job queue here, deduplicating on event.id. Rails.logger.info("Fingerly webhook #{event.id} (#{event.type})") head :no_content end end
# config/routes.rb post "/webhooks/fingerly", to: "fingerly_webhooks#create"
Full guide: docs.fingerly.io/docs/sdks/ruby.
| I want to | Use | Read |
|---|---|---|
| Read an event after the browser identified a visitor | Fingerly::Client and events.get / events.list |
Read events |
| Let one event back one backend action | events.verify and events.consume |
Verify a backend action |
| Read or write an iOS device's DeviceCheck bits | device_check.query / device_check.write |
DeviceCheck bits |
| Check a webhook delivery is genuine | Fingerly::Webhooks.verify and .parse |
Verify webhooks |
| Keep the browser SDK first-party, away from content blockers | Fingerly::Proxy, a Rack middleware |
First-party proxy |
On this page: Read events · DeviceCheck bits · Verify webhooks · First-party proxy · Threads, fibers and deadlines · Requirements · Development · Documentation · Help · Licence
Event reads require fly_sk_{production|staging|development}_ keys. Requests
go to https://api.fingerly.io; endpoint: overrides that with a bare
https origin, scheme, host and an optional port. A path, query, fragment,
credentials, whitespace, a control character or plain http is a
ConfigurationError, and the message never repeats the value. For a local
test API, allow_insecure_loopback: true accepts http://127.0.0.1,
http://localhost and http://[::1] (with any port); leave it off in
production. Public, proxy, management, malformed and unsupported keys are rejected
before network access, by the constructor rather than by the first call.
Requests do not follow redirects. get and list each perform one request
and never retry.
event.suspect_score is nil when the request was not scored. Never read nil
as zero: a visitor about whom nothing fired scores 0, while a submission that
was never enriched has no score at all. scored? states the distinction at
the call site.
unless event.scored?
# Decide on something else; do not treat it as clean.
endevent.raw keeps the response body exactly as it arrived, so a field the API
adds later is reachable without a gem upgrade.
event.project_id is the UUID string of the Fingerly project the event
belongs to, on both events.get and events.list rows; it is nil when an
older server does not send it.
An event is usually readable as soon as identification answers. If it is
still being recorded, the read raises a Fingerly::APIError whose pending?
is true and whose retry_after says when to read again:
# Returns the event, or nil while it is still being recorded.
def read_event(fingerly, request_id)
fingerly.events.get(request_id)
rescue Fingerly::APIError => e
raise unless e.pending?
# Not recorded yet, so nothing is decided: read again after e.retry_after
# seconds (2 when nil), or verify asynchronously.
nil
endRetry a pending read a bounded number of times, for example from a background
job. event_not_found? means a request id that was never issued, or one past
retention, and is never pending.
The archived document arrives moments after the event itself, so check
has_document? rather than assuming it is there, and read event.document
(Hash or nil, holding allow-listed risk, attestation, ip_network and
velocity fields without raw signals, user agent or address). When a submission
is unidentifiable (identifiable == false, such as insufficient entropy, a
genuine embedded WebView, or an unmatched high-risk Web payload),
event.visitor_id is ""; there are no deferred_token, deferred_signals or
supplements fields in v: 3.
Compare fields against the named constants rather than raw strings. Each is
the frozen wire string itself, so event.suspect_level == Fingerly::SuspectLevel::HIGH is an ordinary string comparison, and every field
stays a String: a value the server adds later arrives unchanged, and is only
missing from the module's frozen ALL array.
| Module | Field | Values |
|---|---|---|
Fingerly::Signal |
EventTrigger#signal, #group |
every signal group and detector, such as VPN, VPN_PUBLIC and FINGERPRINT_SUPPRESSED |
Fingerly::SuspectLevel |
Event#suspect_level, webhook data["level"] |
LOW, MEDIUM, HIGH |
Fingerly::Confidence |
EventTrigger#confidence |
LOW, MEDIUM, HIGH |
Fingerly::EventState |
Event#state |
ENRICHED, UNAVAILABLE, and PENDING, which a read raises as pending? |
Fingerly::Environment |
Event#environment |
PRODUCTION, STAGING, DEVELOPMENT |
Fingerly::Platform |
Event#platform |
WEB, ANDROID, IOS |
Fingerly::AnonymityNetwork |
Event#anonymity_network |
TOR, RELAY, VPN, PROXY, HOSTING |
Fingerly::DeviceKind |
Event#device_kind |
DESKTOP, MOBILE, TABLET, SERVER |
Fingerly::VisitorKind |
Event#visitor_kind |
HUMAN, AI_BOT, AUTOMATION, SEARCH_CRAWLER |
Fingerly::AttestationState |
event.document["attestation"]["state"] |
ATTESTED, NOT_ATTESTED, FAILED |
Fingerly::AttestationStatus |
event.document["attestation"]["status"] |
VERIFIED, INDETERMINATE, INVALID, ABSENT, UNCONFIGURED |
Fingerly::AttestSkippedReason |
event.document["attestation"]["attest_skipped"] |
NOT_OFFERED, UNSUPPORTED, CHALLENGE_UNAVAILABLE, KEY_ERROR, TIMEOUT, BACKOFF, INSTALL_UNAVAILABLE |
Fingerly::VerifyReason |
EventVerification#reason |
OK ("") and the failures in Verify a backend action |
Fingerly::WebhookEventType |
WebhookEvent#type |
see Verify webhooks |
Fingerly::WebhookEnvironment |
WebhookEvent#environment |
LIVE, TEST |
A constant's name is its value upper-cased, with . as _ (VerifyReason::OK is ""). Event reads report
each trigger under its signal group (Fingerly::Signal::VPN), while
visitor.suspect webhooks and the archived document's risk.triggers carry
the detector (Fingerly::Signal::VPN_PUBLIC) with its group beside it. Inside
module Fingerly, Signal names Fingerly::Signal; write ::Signal for
Ruby's own. The SIGNAL_* constants on Fingerly::EventTrigger and its
V3_SIGNALS list are the same strings.
fingerly.events.verify reads the event with the server-only key, checks
that it can back the action, and consumes it, so one event backs one
decision:
def authorize_checkout(fingerly, request_id)
result = fingerly.events.verify(request_id, tag: "checkout") # max_age_seconds: 300, consume: true
return "refuse" unless result.ok? # result.reason names the failed check
# The score policy is yours: verify never judges the score.
result.event.suspect_level == Fingerly::SuspectLevel::LOW ? "allow" : "review"
rescue Fingerly::APIError => e
return "retry later" if e.pending? # not decided yet: read again after e.retry_after
raise
endThe checks run in this order and stop at the first failure, whose wire string
is result.reason ("" when result.ok?), with a constant on
Fingerly::VerifyReason (also on Fingerly::EventVerification):
not_found(NOT_FOUND): the request id was never issued, or the event is past retention.result.eventisnilfor this reason only.too_old(TOO_OLD): the event occurred more thanmax_age_secondsago (300 by default), or carries no readableoccurred_at.tag_mismatch(TAG_MISMATCH):tag:was given and the event's tag is not exactly it. Withouttag:nothing is compared; an empty tag raisesFingerly::ConfigurationError.unidentifiable(UNIDENTIFIABLE):event.visitor_idis empty.unscored(UNSCORED): the event has no suspect score.already_consumed(ALREADY_CONSUMED): another call consumed the event first.
The consume runs last, only when every other check passed, so a failed check
leaves the event unused. Pass consume: false to check without consuming. An
invalid option raises Fingerly::ConfigurationError before anything is sent.
Any other failure raises as it does for events.get. A pending event
(pending?) is not a verdict: retry after retry_after seconds or verify
asynchronously, rather than refusing the action.
fingerly.events.consume(request_id) is the consume on its own. It returns a
Fingerly::EventConsumption (request_id, consumed_at, first?) the first
time, is never retried, and raises Fingerly::EventAlreadyConsumedError, a
Fingerly::APIError with event_already_consumed? true and the first
consumed_at, every time after.
Do not authorize an action using scores or visitor identifiers supplied by the browser. Tags correlate events; they do not replace your application's authentication. A tag must never hold a personal identifier, such as a user ID, email, install ID or advertising ID, because the server keeps tags in long-lived rollups.
Every runtime failure derives from Fingerly::Error. A bad option raises
Fingerly::ConfigurationError, which is an ArgumentError: a key that was
never valid is a programming mistake rather than something a rescue around the
call site can help with.
def decide(fingerly, request_id)
event = fingerly.events.get(request_id)
return "review" if event.visitor_id.empty? || !event.scored?
return "refuse" if event.triggers.any? { |t| t.signal == Fingerly::Signal::ATTESTATION_FAILED }
event.suspect_level == Fingerly::SuspectLevel::LOW ? "allow" : "review"
rescue Fingerly::APIError => e
return "retry later" if e.pending? # not decided yet: read again after e.retry_after
return "refuse" if e.event_not_found?
return "retry later" if e.status == 429
raise
end| Error | Raised when |
|---|---|
Fingerly::ConfigurationError (an ArgumentError) |
A bad option, such as a key that was never valid. |
Fingerly::APIError |
Every response outside 2xx, a redirect included. Carries status, and optional code, details, request_id and retry_after. |
Fingerly::TimeoutError |
The deadline (timeout:) passed. |
Fingerly::ConnectionError |
The API is unreachable. |
On APIError, the secret key is stripped from the first three of those
fields, and the response body is never echoed. request_id falls back to the
x-request-id header when the body is not an error envelope. retry_after is
the Retry-After header in whole seconds, from either of its forms, or nil
when there was none: on a 429 or a pending event, wait that long before
reading again.
A read answers 404 with one of two codes, each with its own predicate:
| Predicate | Code | Meaning |
|---|---|---|
pending? |
event_pending |
The request id was accepted and the event is still being recorded. Nothing is decided yet: read again after retry_after seconds (the API sends Retry-After: 2), or verify asynchronously. Do not treat it as fraud. |
event_not_found? |
event_not_found |
The request id was never issued, or the event is past retention. |
The client never retries an event read by itself; only a DeviceCheck call retries, and only the same request.
No object in the SDK shows a credential. A client or proxy printed with
inspect, to_s, pp, to_json or YAML shows [redacted] in place of its
key, and Marshal.dump refuses it. The request handed to client_ip hides the
visitor's cookies and authorization header the same way.
On iOS, Apple keeps two DeviceCheck bits per device for your developer team, and they survive a reinstall. When DeviceCheck is on for the project's Apple key, Fingerly holds the DeviceCheck token that came with an identification for one hour, and your backend spends it once:
bits = fingerly.device_check.query(request_id) # Fingerly::DeviceCheckBits
bits.found # false when Apple holds no bits for the device yet
bits.bit0 # true or false
bits.last_update # "YYYY-MM", or nil when Apple holds no bits
written = fingerly.device_check.write(request_id, bit0: true) # Fingerly::DeviceCheckWrite
written.bit0 # true; a bit left out is nil, and keeps its value at AppleApple treats each DeviceCheck token as single-use, so one event pays for one call: a read or a write, never both. A flow that checks and then marks a device, such as a once-per-device free trial, takes two identifications:
- Query on the identification that asks for the trial. If the bits say the device already had one, refuse it.
- Otherwise grant the trial and record the grant in your own data.
- Write the bit on the next identification from that install, such as one the app makes right after the grant. Until the write lands, your own record of the grant is what stops a second trial.
# bit0 means "this device has had a free trial". The meaning is yours.
def start_trial(fingerly, account, request_id)
bits = begin
fingerly.device_check.query(request_id)
rescue Fingerly::DeviceCheckError => e
raise unless e.not_held? || e.spent? || e.apple_rejected?
nil # no answer, not a verdict: decide without the bits
end
return "offer-paid-plan" if bits&.bit0
Trial.grant(account, device_marked: false)
"granted"
end
def mark_trial(fingerly, account, request_id)
fingerly.device_check.write(request_id, bit0: true)
Trial.update(account, device_marked: true)
rescue Fingerly::DeviceCheckError => e
raise unless e.not_held? || e.spent?
# Keep device_marked false and write at the install's next identification.
endA failure raises Fingerly::DeviceCheckError, a Fingerly::APIError with a
predicate per code:
| Status | Code | Predicate |
|---|---|---|
| 404 | device_check_not_held |
not_held? |
| 409 | device_check_spent |
spent? |
| 409 | device_check_busy |
busy? |
| 409 | credential_unavailable |
credential_unavailable? |
| 422 | bits_required |
bits_required? |
| 422 | apple_rejected |
apple_rejected?, with Apple's HTTP status in apple_status |
| 503 | device_check_unavailable |
unavailable? |
A write that names neither bit raises Fingerly::ConfigurationError before
anything is sent.
The token may be retried only with the same request. After a 503 or a
transport failure the token is kept, so the client sends the identical request
again, up to three attempts in all; it retries nothing else. If you retry
later yourself, repeat the same call with the same bits: a read after a failed
write, or a write with other bits, answers 409 device_check_spent. Apple asks
that DeviceCheck is never the only fraud check, and that users have a way to
have the bits reset.
The controller and route are in Getting started. Verify the
exact raw bytes before parsing them. request.raw_post is those bytes; a body
reconstructed from parsed parameters is not.
| Behaviour | Detail |
|---|---|
| What a signature covers | the timestamp and the body |
| Replay tolerance | five minutes by default |
| Secret rotation | any matching signature in the comma-separated header is accepted; only the first 32 are read |
| Malformed or missing input | a false result, never an exception; a body that is not valid UTF-8 verifies rather than raising on concatenation |
| Deduplication | persist processed id values to deduplicate deliveries |
WebhookEvent#data stays a plain Hash, so a new event type needs no gem
upgrade. Dispatch on event.type with Fingerly::WebhookEventType:
case event.type
when Fingerly::WebhookEventType::VISITOR_SUSPECT # sent for SuspectLevel::HIGH only
review(event.data["request_id"])
when Fingerly::WebhookEventType::IDENTIFICATION_COMPLETED,
Fingerly::WebhookEventType::IDENTIFICATION_REFUSED
record(event.data)
when Fingerly::WebhookEventType::WEBHOOK_TEST
nil # sent to one endpoint on request; nobody subscribes to it
endThe other types are BILLING_STATUS_CHANGED (billing.status_changed) and
USAGE_DAILY_SETTLED (usage.daily_settled). identification.completed and visitor.suspect deliveries carry the
event's project as data["project_id"]; identification.refused carries it
only when the refused request named a known key.
Content blockers refuse browser requests to third-party APIs, and a refused identification is a visitor never identified. Mount the proxy on a path of your own site and those requests become first-party. The proxy key is what lets that hop declare the visitor's real address, origin and user agent; a public key alone never can, so nobody can spoof them.
Create a proxy in the dashboard (Integration > Proxy keys). It issues a
path such as /k7x2qm4a, and the proxy answers that one path. Rack is the one
interface every Ruby server and framework shares, so there is one middleware
and no per-framework variants.
# config/application.rb, inside `class Application < Rails::Application`
config.middleware.insert_before 0, Fingerly::Proxy,
proxy_key: ENV.fetch("FINGERLY_PROXY_KEY"),
path: "/k7x2qm4a",
client_ip: ->(request) { request.header("CF-Connecting-IP") || request.peer_host }Use insert_before 0, not use. use appends the proxy after Rails' own
middleware, which then rewrites its answers on the way out:
ActionDispatch::RequestId replaces Fingerly's x-request-id with a Rails
one, and Rack::ETag and Rack::Runtime add etag and x-runtime. At the
front of the stack the proxy answers before any of them, and before anything
that could redirect a signed-out visitor.
# config.ru, for Sinatra, Hanami or a bare Rack app
require "fingerly"
require_relative "app" # defines MyApp, your Sinatra or Rack application
use Fingerly::Proxy,
proxy_key: ENV.fetch("FINGERLY_PROXY_KEY"),
path: "/k7x2qm4a",
client_ip: ->(request) { request.header("CF-Connecting-IP") || request.peer_host }
run MyAppPut it first, ahead of authentication: the browser SDK sends no cookies and carries no user, and a filter that redirected it to a sign-in page would break identification for every signed-out visitor.
client_ipis the one thing you must get right. Resolve it from a header your own infrastructure sets, such as your load balancer's or CDN's, and fall back torequest.peer_host, the TCP peer, when it is absent, as in local development. Trust that header only when traffic can reach your application through that CDN alone; otherwise a visitor can set it. Never read the left-mostX-Forwarded-Forvalue: the visitor writes it.
client_ip must return exactly one IPv4 or IPv6 address. Anything else, nil
or an empty string, a list, a port, a prefix length, or an exception, is a
configuration mistake: the proxy sends nothing upstream, answers 500 with
"The client IP callback returned no valid address", and logs it once per
process rather than once per visitor.
Then point the client SDK at the same path. Browser and proxied native SDKs post
a single v: 3 identification envelope there, with nothing appended:
import { load } from '@fingerly/web-js'
const fingerly = await load({ apiKey: 'fly_pk_…', endpoints: '/k7x2qm4a' })proxy_key and path are required. A proxy key that is not
fly_px_<environment>_... for production, staging or development, or a
missing path, is a ConfigurationError at start-up. The proxy matches it
exactly against PATH_INFO, so use it as middleware, as above, or run it as
the whole application. Do not put it behind a Rails mount or a
Rack::URLMap entry: those move the path into SCRIPT_NAME, and the proxy
then sees a path that is not its own and answers 404.
| Rule | Behaviour |
|---|---|
| Path match | Only the configured path, matched exactly and case-sensitively: /k7x2qm4a/, //k7x2qm4a, /k7x2qm4a/., /k7x2qm4a%2F, /k7x2qm4a/admin and retired /supplement paths are not its own. Anything else is passed along to your application, or answered 404 when the proxy has no application behind it. |
| Other methods | On its own path, anything but POST (plus OPTIONS when allowed_origins: is configured) gets 405. Methods are compared exactly, so post gets 405 too. |
| Own answers | Every answer the proxy writes itself carries cache-control: no-store. |
| Upstream | Every request it accepts goes verbatim as raw bytes to one URL, https://api.fingerly.io/api/v1/ingest. api_version: changes only the version in that URL. |
| Event reads | Nothing else is reachable through it, event reads included: they need a secret key and stay unreachable from a browser by construction. |
| Public key | The caller must present a public key (fly_pk_...) from the same environment as the proxy key, or the request gets 401 and nothing is forwarded; a secret key is refused the same way. |
| Credentials upstream | Every request carries the proxy key as X-Fingerly-Proxy-Key and the caller's public key as X-API-Key, never a secret key. |
| Origin or platform | Requests without either Origin or a validated native X-Fingerly-SDK-Platform header (ios, android, react-native, react-native-ios, react-native-android, flutter, flutter-ios, flutter-android, lynx-ios, lynx-android, capacitor, kotlin-multiplatform) are rejected locally with 400 (missing_origin), and x-fingerly-origin is never synthesized from Host, Referer or the request URL. A request is forwarded on one channel only: with an Origin the proxy sends x-fingerly-origin and drops the platform header, and without one it sends the validated platform. |
| Body size | Bodies over 1 MiB get 413, enforced while reading rather than after buffering. |
| Forwarded headers | All incoming x-fingerly-*, cookie and authorization headers are stripped, restoring only a validated x-fingerly-sdk-platform (when there is no Origin) alongside x-fingerly-host, idempotency-key, sec-fetch-* and sec-ch-ua-*. |
| Proxy identity | The proxy reports itself upstream as ruby/0.4.1 in x-fingerly-proxy-version, which the dashboard shows per proxy. |
| Fingerly unreachable | The visitor gets a gateway error rather than your application's 500. |
| Deadline passes | 504 Gateway timeout when timeout: (5 seconds by default) passes. |
| Any other upstream failure | 502 Bad gateway, whether the connection was refused or reset, the name did not resolve, or the answer was malformed, cut short or over 4 MiB. Redirects are never followed, and an upstream redirect or a status outside 200 to 599 is answered 502 as well. |
| Truncated answers | The whole answer is read before anything is written back, so a truncated response is never relayed as a success. |
| Failure logging | Each failure logs one line, without a stack trace, to logger: when you pass one, to rack.logger when your server provides it, and to standard error otherwise. The line names the kind of failure only, never the upstream address or a key. |
| Relayed back | Only content-type, x-request-id, ratelimit-limit, ratelimit-remaining and retry-after, plus cache-control: no-store set by the proxy. A content blocker can match a response header by name, and an allowlist keeps anything that names Fingerly off the response, whatever the API adds later. |
| Header shape | Relayed headers are lowercase and repeats joined with ", ", which is the one shape Rack 2 and Rack 3 both accept: Rack 3 refuses an uppercase name outright, and Rack 2 refuses the array Rack 3 would rather have. |
The 1 MiB limit bounds what the proxy holds. A server that buffers the whole request before calling the application, as Puma does, has already read it by then, so bound request bodies there with the server's or the load balancer's own limit as well. Falcon streams the body, so there the proxy stops reading at the limit.
upstream: takes a bare origin, scheme, host and an optional port, such as
https://api.fingerly.io. A path, query, fragment, credentials, whitespace or
a control character is a ConfigurationError, and so is plain http. For a
local test API, allow_insecure_loopback: true accepts http://127.0.0.1,
http://localhost and http://[::1] (with any port), and nothing else; leave
it off in production.
Why the middleware decides from the path alone, and what path means
The middleware decides from the path alone before it reads anything. It sees
every request in the stack, and reading the body to find out whether one
belongs to Fingerly would have consumed it: under Rack 3 rack.input is not
required to rewind, so your application would receive an empty request rather
than an error.
path is the path within your application. It excludes anything a sub-URI
deployment puts in SCRIPT_NAME, because the proxy matches PATH_INFO, which
means the same thing wherever the application is deployed. Use the one the
dashboard issued rather than inventing one: blockers look for words such as
fingerprint, tracking and analytics in a path.
There is no asynchronous client, and none is needed.
The Python SDK ships two clients because ASGI and WSGI are two live server standards, and a blocking call inside FastAPI stalls its event loop. Ruby has one server interface, Rack, and every framework on it calls your application synchronously.
The stack that is not thread-per-request is covered anyway. On Ruby 3.2+,
the floor this gem requires, Net::HTTP yields to a fiber scheduler, so under
Falcon or the async gem the blocking reads in this SDK hand the thread back
to the scheduler rather than holding it. Concurrent calls overlap without a
second API to choose between, and there are tests asserting exactly that under
both a fiber scheduler and plain threads.
Where there is no fiber scheduler, a call holds its thread until it answers,
for at most timeout:. That is what Puma and Unicorn expect. Do not call the
client from an event loop that is not a fiber scheduler, such as an
EventMachine reactor: there it would stall every connection the loop serves.
Size the thread pool for the slow case, not the average one: while Fingerly is
slow, every proxied request holds its thread for the whole timeout:. At 100
proxied requests a second with 1% of them running into a 5 second timeout, that
is 5 threads busy on average, before any fast request is served. Run more
threads than that across your Puma or Unicorn workers, lower timeout: for the
proxy, or serve with Falcon, where a waiting call holds no thread.
timeout: bounds the whole exchange: connecting, sending, the response
headers and the body.
That takes care on this platform. Net::HTTP has open_timeout,
read_timeout and write_timeout, but each bounds a single operation: a
server that answers and then sends one byte a second would satisfy all three
forever, and so would one that sends a header line a second, because each
header line gets the full read timeout. The client shrinks the socket's own
timeouts to whatever is left of the deadline before each step, and one
Timeout around the whole exchange covers the header lines, so the bound is
tight rather than a multiple of the timeout. Under a fiber scheduler that
Timeout is the scheduler's own.
Idle connections are kept in one pool per process and destination, shared by
every client and proxy in it. Net::HTTP cannot be used by two threads or
fibers at once, so each exchange checks a connection out and hands it back
when it is done: a burst of a few hundred concurrent requests reuses its
sockets rather than opening one each, and a fiber that ends (Falcon runs one
per client connection) returns its socket instead of stranding it.
| Pool rule | Value |
|---|---|
| Idle connections kept | at most 256 per destination |
| Reopened after | 60 seconds, so DNS is asked again |
| Dropped after | 15 seconds idle |
| Closed while idle by the other end | reopened and the request sent again, but only for GET, because a POST that may already have arrived must never be sent twice |
| Forked worker | starts with an empty pool |
Ruby 3.2+, which is what the gemspec declares (required_ruby_version >= 3.2.0),
and fiber-scheduler support needs nothing newer. CI runs Ruby 3.2, 3.3 and 3.4.
No runtime dependencies: everything it needs is in the standard library. Rack is
a contract rather than a dependency, so the proxy speaks it without loading it
and cannot pin a version against your own.
Tests, signatures, contract snapshot, release, source structure
bundle install
bundle exec rake # tests, RuboCop and the RBS signatures
FINGERLY_CONTRACT_DIR=../../contract bundle exec ruby tools/sync_contract.rbTests run with Ruby's own warnings on, and every proxy response goes through
Rack::Lint, which holds it to the Rack 3 spec more strictly than any
assertion written by hand. The fake API is a real WEBrick server on a loopback
port rather than a stubbed Net::HTTP: a stub shares this SDK's assumptions
about framing, keep-alive and compression, so it cannot disprove any of them.
sig/fingerly.rbs describes the public surface. rbs validate proves the
signatures are consistent; test/signatures_test.rb proves they describe the
library that exists, which matters because several readers are defined by
metaprogramming.
The vendored synthetic contract snapshot makes tests independent of sibling
repositories. Its hashes are checked by ContractTest, so there is no
separate check step. Never put production secrets in fixtures.
The gemspec sets allowed_push_host to RubyGems, so a push to any other host
is refused.
Client holds the connection and the options; Events owns the reads and the
list filters, and Event, EventPage and EventTrigger are what they speak
in. Webhooks verifies signatures. Proxy holds every proxy decision, with
ProxyRequest as the shape client_ip is given. Config validates every
caller-supplied option before any network access, and Transport is the one
place that knows how to bound an exchange and reuse a socket.
Open an issue on this repository, or write to support@fingerly.io. Report security issues to security@fingerly.io.
Apache-2.0. See LICENSE.
