offline_protocol 0.31.0

data/LICENSE-COMMERCIAL.md

@@ -0,0 +1,89 @@
+# Commercial License
+
+Copyright © 2025-2026 Offline Protocol, Inc.
+
+The Offline Protocol SDK is **dual-licensed**. You may use it under **either** of the
+following licenses, at your option:
+
+1. **GNU Affero General Public License v3.0 (AGPL-3.0-only)** — the full text is in
+   [`LICENSE`](LICENSE). This option is free of charge but carries strong copyleft
+   obligations: software that incorporates this SDK is generally a covered work
+   under the AGPL-3.0 (per section 5) and must be distributed under the same
+   license with corresponding source made available to recipients (per section 6).
+   If you operate a modified version that interacts with users over a network, you
+   must additionally offer those users the corresponding source — this is the
+   network-use clause specific to AGPL (section 13).
+
+2. **Commercial License** — for organizations that cannot or do not wish to comply
+   with the AGPL-3.0 (for example, shipping the SDK inside a proprietary mobile
+   application, embedding it in closed-source firmware, or operating a SaaS without
+   releasing source). A separate commercial license from **Offline Protocol, Inc.**
+   grants the right to use, modify, and distribute the SDK without the AGPL-3.0
+   obligations, subject to the applicable commercial agreement, including the
+   telemetry term below.
+
+You only need **one** of the two licenses, not both.
+
+One distribution channel deserves a specific call-out: Apple's standard App
+Store terms are widely regarded as incompatible with the AGPL-3.0's
+prohibition on further restrictions, so the commercial license is the
+supported option for apps distributed through the Apple App Store — the
+reasoning is laid out in the
+[Licensing FAQ](https://github.com/Offline-Protocol/offline-protocol-sdk/blob/main/docs/licensing-faq.md).
+
+## Telemetry under the Commercial License
+
+The SDK includes an optional telemetry client that, once an application
+enables it with a telemetry API key and application identifier issued by
+Offline Protocol, Inc., collects, batches, and uploads supported operational
+events to Offline Protocol's hosted telemetry service. Service access, usage
+allowances, and metered charges are set out in the applicable commercial
+agreement. The following telemetry term applies to every commercial license,
+as set out in that agreement.
+
+A commercial licensee may leave hosted telemetry off, never supply telemetry
+credentials, or switch it off using the SDK's documented controls. Until it is
+explicitly enabled, the hosted telemetry client does not collect, buffer,
+persist, or upload telemetry. The controls stop new collection; handling of
+previously queued records, final flushes, and in-flight uploads is described
+in the telemetry documentation.
+
+Except as expressly authorized in writing by Offline Protocol, Inc., a
+commercial licensee may not modify, configure, or build the SDK so that its
+bundled telemetry client uploads to an unauthorized endpoint, redirects or
+duplicates its uploads to another telemetry service, or alters the event
+schema or serialized payload format it uploads. Security updates that preserve
+the authorized destination and payload format are permitted. Network proxies
+and gateways that forward uploads unaltered to an authorized endpoint, and
+local test captures in builds that are not shipped, are permitted.
+
+These telemetry restrictions do not limit the licensee's use of information
+received through the SDK's public APIs. Receiving events and diagnostics,
+storing or analyzing them, and forwarding them to the licensee's own systems
+or third-party observability providers are ordinary uses of the SDK.
+Independently implementing telemetry collection and export using those APIs is
+also permitted.
+
+This term applies to the Commercial License only. It does not modify or impose
+additional restrictions on the AGPL-3.0 option, under which the telemetry
+client may be modified, removed, or replaced in accordance with that license.
+Under either option, the SDK performs no commercial-license entitlement
+checks, and core SDK functionality does not require hosted telemetry.
+
+## Obtaining a Commercial License
+
+Commercial licenses are offered by **Offline Protocol, Inc.** To request a quote
+or discuss commercial terms, contact:
+
+- **Email:** legal@offlineprotocol.com
+
+Please include a brief description of your intended use (product, distribution
+model, expected scale) so we can scope the license appropriately.
+
+## Contributions
+
+Contributors grant **Offline Protocol, Inc.** the right to sublicense their
+contributions under this Commercial License alongside the AGPL-3.0. The full terms are in
+[`CLA.md`](https://github.com/Offline-Protocol/offline-protocol-sdk/blob/main/CLA.md);
+see [`CONTRIBUTING.md`](https://github.com/Offline-Protocol/offline-protocol-sdk/blob/main/CONTRIBUTING.md)
+for the signing flow.

data/README.md

@@ -0,0 +1,130 @@
+# The Offline Protocol SDK from Ruby
+
+A typed Ruby API for scripts, tooling and servers, generated from the same
+interface definition as the Swift, Kotlin, Python and Java bindings by UniFFI's
+own Ruby generator. It calls the native library directly through the
+[`ffi`](https://github.com/ffi/ffi) gem: there is no native glue of its own and
+it does not go through the C API.
+
+The whole binding is one file, [`lib/offline_protocol.rb`](lib/offline_protocol.rb).
+The module is `OfflineProtocol` and the engine inside it is
+`OfflineProtocol::OfflineProtocol`. `MeshServices` and `DataStore` hang off the
+engine, every record and enum of the definition is a class, and the things a
+host implements are plain objects that respond to the interface's methods. An
+engine refusal is an exception named for the variant
+(`OfflineProtocol::ProtocolError::EncryptFailed`).
+
+The contract is [docs/bridges/ruby.md](../../docs/bridges/ruby.md), on top of
+the [shared one](../../docs/bridges/README.md). Read it before writing a
+callback or a storage provider.
+
+## What you need
+
+| What | Where it comes from |
+|---|---|
+| Ruby 3.3 or later and the `ffi` gem, `~> 1.17` | Yours; `bundle install` in this directory installs the gem |
+| This binding | The [`offline_protocol`](https://rubygems.org/gems/offline_protocol) gem once a release publishes it (R7), or [`lib/offline_protocol.rb`](lib/offline_protocol.rb) on your load path |
+| `liboffline_protocol_uniffi.so` / `.dylib`, `offline_protocol_uniffi.dll` | The release's desktop archives, or `cargo build --release -p offline-protocol-uniffi` |
+
+The library is found on the loader's search path, and the loader reads the
+variable when the process starts, so set it before Ruby launches:
+
+```sh
+# Linux
+LD_LIBRARY_PATH=/path/to/dir ruby -Ilib your_script.rb
+# macOS
+DYLD_LIBRARY_PATH=/path/to/dir ruby -Ilib your_script.rb
+# Windows (RubyInstaller reads RUBY_DLL_PATH, not PATH)
+$env:RUBY_DLL_PATH = "C:\path\to\dir"; ruby -Ilib your_script.rb
+```
+
+A protected system Ruby on macOS (`/usr/bin/ruby`) drops `DYLD_LIBRARY_PATH`;
+use a Ruby you installed.
+
+## Quick start
+
+```ruby
+require "offline_protocol"
+
+Sdk = OfflineProtocol
+
+# An instance-less function needs no engine.
+puts Sdk.derive_address([0] * 32)
+
+# Name the fields the definition leaves without a default; the rest take it.
+config = Sdk::ProtocolConfig.new(
+  app_id: "com.example.ruby", profile: "ruby-example",
+  ble_enabled: false, wifi_direct_enabled: false, internet_enabled: true,
+  reticulum_enabled: false, nostr_enabled: false, prefer_online: false,
+  initial_ttl: 8, encryption_enabled: true, auto_key_exchange: true,
+  # The pending queue: per peer, global, the SDK's 24 h lifetime, overflow.
+  store_pending: true, max_pending_per_peer: 64, max_pending_global: 4096,
+  pending_ttl_ms: 86_400_000, overflow_policy: Sdk::OverflowPolicy::DROP_OLDEST
+)
+
+engine = Sdk::OfflineProtocol.new(config)
+
+# Any object that responds to on_event. It runs inside the engine call.
+listener = Object.new
+def listener.on_event(json) = puts(json)
+engine.set_event_callback(listener)
+
+engine.emit_test_event
+```
+
+Keep the engine reachable for as long as the process runs. See R3 in the
+contract for what a collected engine costs.
+
+A byte array the engine returns comes back signed, -128 to 127, and has to be
+masked with `map { |b| b & 0xFF }` before it goes back in (R8).
+
+A complete, runnable program is in [examples/ruby-app](../../examples/ruby-app/README.md).
+
+## Storage
+
+The engine needs somewhere to keep key material and protocol state. Either hand
+it the built-in file stores:
+
+```ruby
+engine.initialize_mls_with_file_stores(mls_dir, state_dir, store_key_32_bytes)
+```
+
+or write two providers and pass them to `initialize_mls`. They carry bytes
+differently (R5 in the contract), and a provider you write should pass
+`OfflineProtocol.run_storage_conformance`. [`test/memory_storage.rb`](test/memory_storage.rb)
+is a complete in-memory pair.
+
+## Tests
+
+```sh
+cargo build -p offline-protocol-uniffi
+cd bindings/ruby
+bundle install
+bundle exec rake test
+```
+
+`rake test` puts `../../target/debug` on the loader's search path (set
+`OFFLINE_PROTOCOL_LIBRARY_DIR` for another build) and runs
+[`test/consumer_check_test.rb`](test/consumer_check_test.rb) against the real
+library. The generated code does not compare the library's FFI checksums, so
+these tests are what show that the binding and the library came from the same
+definition. Outside this repository nothing checks it: take the library from
+the same release as the gem (R1).
+
+`bundle exec rake build` writes the gem to `pkg/`, at the version in
+`OFFLINE_PROTOCOL_VERSION` (default `0.0.0`). Use the task, not `gem build`: it
+stages the license notices from the repository root, which the gemspec names
+and `gem build` cannot reach.
+
+## Regenerating
+
+Never edit `lib/offline_protocol.rb`. It is regenerated with the other four
+bindings, which are one artifact set:
+
+```sh
+./scripts/generate-bindings.sh
+```
+
+The Ruby generator is part of `uniffi-bindgen`, so there is nothing more to
+install than the other bindings need. [`uniffi.toml`](uniffi.toml) names the
+library; see R1 in the contract.