nostr 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 669ffcd3d585116e340888ace801690a0c596bb6d20f12acc80a7a8c933fa0e1
-  data.tar.gz: 1abe2ac66bcdd51c175e2ebb7b676d1d8a3508c12e783e674252d33948336215
+  metadata.gz: 90770e269f0c966f76013797314b9e3b4b0743fa57f5b84f2460371b413bc5f1
+  data.tar.gz: 7a4a908a6c1b086781d26dc6f45c289a85859e12e1e854451a0e9f8e75f5fa06
 SHA512:
-  metadata.gz: fb8845670cf90e66204225260aa76d50bcf76f3e8cd9ccae27bbb73e3384bb23fc411fdabcdbe6a2cbdfd1e5023d45ce5c4f8b42077b73c3c1e865e87fa5cce5
-  data.tar.gz: 5e02009ec661e34507a96ddb3c1866e76d3aab0a2f19c80f4228a53c783e01a1b226e76d39a35ef8de27b2be9c7a915435ab55666b7770d98cc54cdf1f387478
+  metadata.gz: 35a4401f078587bed79d6063f4051cca3f8dc170c074c552a202fee7872b75668eb8204a5f6db09f810ed0c5bb84026438d7e942f48a4825d63ba64552d032c7
+  data.tar.gz: b9400efc3228dea17e23e40803e2e7b94ce9966e6a729fcf5ea0b79ffcea07b7e51f7fd9703d01af1d287ffdaf85b6b8d49d325813b8e32518a0be240537e86e

data/.rubocop.yml

@@ -1,3 +1,5 @@
+inherit_from: .rubocop_todo.yml
+
 require:
   - rubocop-rake
   - rubocop-rspec

data/.rubocop_todo.yml

@@ -0,0 +1,23 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2023-01-12 10:00:10 UTC using RuboCop version 1.42.0.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+# Offense count: 2
+# Configuration parameters: AllowedMethods, AllowedPatterns, IgnoredMethods, CountRepeatedAttributes.
+Metrics/AbcSize:
+  Max: 23
+
+# Offense count: 2
+# Configuration parameters: CountComments, CountAsOne, ExcludedMethods, AllowedMethods, AllowedPatterns, IgnoredMethods.
+Metrics/MethodLength:
+  Max: 16
+
+# Offense count: 4
+# Configuration parameters: AssignmentOnly.
+RSpec/InstanceVariable:
+  Exclude:
+    - 'spec/nostr/client_spec.rb'

data/CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2023-01-12
+
+### Added
+
+- [NIP-01](https://github.com/nostr-protocol/nips/blob/master/01.md) compliant client
+
 ## [0.1.0] - 2023-01-06
 
 - Initial release
+
+[0.2.0]: https://github.com/wilsonsilva/nostr/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/wilsonsilva/nostr/compare/7fded5...v0.1.0

data/README.md

@@ -1,11 +1,11 @@
 # Nostr
 
 [![Gem Version](https://badge.fury.io/rb/nostr.svg)](https://badge.fury.io/rb/nostr)
-[![Security](https://hakiri.io/github/wilsonsilva/nostr/master.svg)](https://hakiri.io/github/wilsonsilva/nostr/master)
-[![Inline docs](http://inch-ci.org/github/wilsonsilva/nostr.svg?branch=master)](http://inch-ci.org/github/wilsonsilva/nostr)
+[![Maintainability](https://api.codeclimate.com/v1/badges/c7633eb2c89eb95ee7f2/maintainability)](https://codeclimate.com/github/wilsonsilva/nostr/maintainability)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/c7633eb2c89eb95ee7f2/test_coverage)](https://codeclimate.com/github/wilsonsilva/nostr/test_coverage)
 
-Nostr client. Please note that the API is likely to change as the gem is still in development and has not yet reached a
-stable release. Use with caution.
+Asynchronous Nostr client. Please note that the API is likely to change as the gem is still in development and
+has not yet reached a stable release. Use with caution.
 
 ## Installation
 
@@ -19,10 +19,171 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
 ## Usage
 
+### Requiring the gem
+
+All examples below assume that the gem has been required.
+
 ```ruby
 require 'nostr'
 ```
 
+
+### Generating a keypair
+
+```ruby
+keygen  = Nostr::Keygen.new
+keypair = keygen.generate_keypair
+
+keypair.private_key
+keypair.public_key
+```
+
+### Generating a private key and a public key
+
+```ruby
+keygen  = Nostr::Keygen.new
+
+private_key = keygen.generate_private_key
+public_key  = keygen.extract_public_key(private_key)
+```
+
+### Connecting to a Relay
+
+Clients can connect to multiple Relays. In this version, a Client can only connect to a single Relay at a time.
+
+You may instantiate multiple Clients and multiple Relays.
+
+```ruby
+client = Nostr::Client.new
+relay = Nostr::Relay.new(url: 'wss://relay.damus.io', name: 'Damus')
+
+client.connect(relay)
+```
+
+### WebSocket events
+
+All communication between clients and relays happen in WebSockets.
+
+The `:connect` event is fired when a connection with a WebSocket is opened. You must call `Nostr::Client#connect` first.
+
+```ruby
+client.on :connect do
+  # all the code goes here
+end
+```
+
+The `:close` event is fired when a connection with a WebSocket has been closed because of an error.
+
+```ruby
+client.on :error do |error_message|
+  puts error_message
+end
+
+# > Network error: wss://rsslay.fiatjaf.com: Unable to verify the server certificate for 'rsslay.fiatjaf.com'
+```
+
+The `:message` event is fired whenwhen data is received through a WebSocket.
+
+```ruby
+client.on :message do |message|
+  puts message
+end
+
+# > Network error: wss://rsslay.fiatjaf.com: Unable to verify the server certificate for 'rsslay.fiatjaf.com'
+```
+
+The `:close` event is fired when a connection with a WebSocket is closed.
+
+```ruby
+client.on :close do |code, reason|
+  # you may attempt to reconnect
+
+  client.connect(relay)
+end
+```
+
+### Requesting for events / creating a subscription
+
+A client can request events and subscribe to new updates after it has established a connection with the Relay.
+
+You may use a `Nostr::Filter` instance with as many attributes as you wish:
+
+```ruby
+client.on :connect do
+  filter = Nostr::Filter.new(
+    ids: ['8535d5e2d7b9dc07567f676fbe70428133c9884857e1915f5b1cc6514c2fdff8'],
+    authors: ['ae00f88a885ce76afad5cbb2459ef0dcf0df0907adc6e4dac16e1bfbd7074577'],
+    kinds: [Nostr::EventKind::TEXT_NOTE],
+    e: ["f111593a72cc52a7f0978de5ecf29b4653d0cf539f1fa50d2168fc1dc8280e52"],
+    p: ["f1f9b0996d4ff1bf75e79e4cc8577c89eb633e68415c7faf74cf17a07bf80bd8"],
+    since: 1230981305,
+    until: 1292190341,
+    limit: 420,
+  )
+
+  subscription = client.subscribe('a_random_subscription_id', filter)
+end
+```
+
+With just a few:
+
+```ruby
+client.on :connect do
+  filter = Nostr::Filter.new(kinds: [Nostr::EventKind::TEXT_NOTE])
+  subscription = client.subscribe('a_random_subscription_id', filter)
+end
+```
+
+Or omit the filter:
+
+```ruby
+client.on :connect do
+  subscription = client.subscribe('a_random_subscription_id')
+end
+```
+
+Or even omit the subscription id:
+
+```ruby
+client.on :connect do
+  subscription = client.subscribe('a_random_subscription_id')
+end
+```
+
+### Stop previous subscriptions
+
+You can stop receiving messages from a subscription by calling `#unsubscribe`:
+
+```ruby
+client.unsubscribe('your_subscription_id')
+```
+
+### Publishing an event
+
+To publish an event you need a keypair.
+
+```ruby
+# Set up the private key
+private_key = 'a630b06e2f883378d0aa335b9adaf7734603e00433350b684fe53e184f08c58f'
+user = Nostr::User.new(private_key)
+
+# Create a signed event
+event = user.create_event(
+  created_at: 1667422587, # optional, defaults to the current time
+  kind: Nostr::EventKind::TEXT_NOTE,
+  tags: [], # optional, defaults to []
+  content: 'Your feedback is appreciated, now pay $8'
+)
+
+# Send it to the Relay
+client.publish(event)
+```
+
+## NIPS
+
+- [x] [NIP-01 - Client](https://github.com/nostr-protocol/nips/blob/master/01.md)
+- [ ] [NIP-01 - Relay](https://github.com/nostr-protocol/nips/blob/master/01.md)
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies.

data/lib/nostr/client.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require 'event_emitter'
+require 'faye/websocket'
+
+module Nostr
+  # Clients can talk with relays and can subscribe to any set of events using a subscription filters.
+  # The filter represents all the set of nostr events that a client is interested in.
+  #
+  # There is no sign-up or account creation for a client. Every time a client connects to a relay, it submits its
+  # subscription filters and the relay streams the "interested events" to the client as long as they are connected.
+  #
+  class Client
+    include EventEmitter
+
+    # Instantiates a new Client
+    #
+    # @api public
+    #
+    # @example Instantiating a client that logs all the events it sends and receives
+    #   client = Nostr::Client.new(debug: true)
+    #
+    def initialize
+      @subscriptions = {}
+
+      initialize_channels
+    end
+
+    # Connects to the Relay's websocket endpoint
+    #
+    # @api public
+    #
+    # @example Connecting to a relay
+    #   relay = Nostr::Relay.new(url: 'wss://relay.damus.io', name: 'Damus')
+    #   client.connect(relay)
+    #
+    # @param [Relay] relay The relay to connect to
+    #
+    # @return [void]
+    #
+    def connect(relay)
+      execute_within_an_em_thread do
+        client = Faye::WebSocket::Client.new(relay.url, [], { tls: { verify_peer: false } })
+        parent_to_child_channel.subscribe { |msg| client.send(msg) }
+
+        client.on :open do
+          child_to_parent_channel.push(type: :open)
+        end
+
+        client.on :message do |event|
+          child_to_parent_channel.push(type: :message, data: event.data)
+        end
+
+        client.on :error do |event|
+          child_to_parent_channel.push(type: :error, message: event.message)
+        end
+
+        client.on :close do |event|
+          child_to_parent_channel.push(type: :close, code: event.code, reason: event.reason)
+        end
+      end
+    end
+
+    # Subscribes to a set of events using a filter
+    #
+    # @api public
+    #
+    # @example Creating a subscription with no id and no filters
+    #   subscription = client.subscribe
+    #
+    # @example Creating a subscription with an ID
+    #   subscription = client.subscribe(subscription_id: 'my-subscription')
+    #
+    # @example Subscribing to all events created after a certain time
+    #   subscription = client.subscribe(filter: Nostr::Filter.new(since: 1230981305))
+    #
+    # @param subscription_id [String] The subscription id. A random string.
+    # @param filter [Filter] A set of attributes that represent the events that the client is interested in.
+    #
+    # @return [Subscription] The subscription object
+    #
+    def subscribe(subscription_id: SecureRandom.hex, filter: Filter.new)
+      subscriptions[subscription_id] = Subscription.new(id: subscription_id, filter:)
+      parent_to_child_channel.push([ClientMessageType::REQ, subscription_id, filter.to_h].to_json)
+      subscriptions[subscription_id]
+    end
+
+    # Stops a previous subscription
+    #
+    # @api public
+    #
+    # @example Stopping a subscription
+    #  client.unsubscribe(subscription.id)
+    #
+    # @example Stopping a subscription
+    #  client.unsubscribe('my-subscription')
+    #
+    # @param subscription_id [String] ID of a previously created subscription.
+    #
+    # @return [void]
+    #
+    def unsubscribe(subscription_id)
+      subscriptions.delete(subscription_id)
+      parent_to_child_channel.push([ClientMessageType::CLOSE, subscription_id].to_json)
+    end
+
+    # Sends an event to a Relay
+    #
+    # @api public
+    #
+    # @example Sending an event to a relay
+    #  client.publish(event)
+    #
+    # @param event [Event] The event to be sent to a Relay
+    #
+    # @return [void]
+    #
+    def publish(event)
+      parent_to_child_channel.push([ClientMessageType::EVENT, event.to_h].to_json)
+    end
+
+    private
+
+    # The subscriptions that the client has created
+    #
+    # @api private
+    #
+    # @return [Hash{String=>Subscription}>]
+    #
+    attr_reader :subscriptions
+
+    # The channel that the parent thread uses to send messages to the child thread
+    #
+    # @api private
+    #
+    # @return [EventMachine::Channel]
+    #
+    attr_reader :parent_to_child_channel
+
+    # The channel that the child thread uses to send messages to the parent thread
+    #
+    # @api private
+    #
+    # @return [EventMachine::Channel]
+    #
+    attr_reader :child_to_parent_channel
+
+    # Executes a block of code within the EventMachine thread
+    #
+    # @api private
+    #
+    # @return [Thread]
+    #
+    def execute_within_an_em_thread(&block)
+      Thread.new { EventMachine.run(block) }
+    end
+
+    # Creates the communication channels between threads
+    #
+    # @api private
+    #
+    # @return [void]
+    #
+    def initialize_channels
+      @parent_to_child_channel = EventMachine::Channel.new
+      @child_to_parent_channel = EventMachine::Channel.new
+
+      child_to_parent_channel.subscribe do |msg|
+        emit :connect                           if msg[:type] == :open
+        emit :message, msg[:data]               if msg[:type] == :message
+        emit :error,   msg[:message]            if msg[:type] == :error
+        emit :close,   msg[:code], msg[:reason] if msg[:type] == :close
+      end
+    end
+  end
+end

data/lib/nostr/client_message_type.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Nostr
+  # Clients can send 3 types of messages, which must be JSON arrays
+  module ClientMessageType
+    # @return [String] Used to publish events
+    EVENT = 'EVENT'
+
+    # @return [String] Used to request events and subscribe to new updates
+    REQ = 'REQ'
+
+    # @return [String] Used to stop previous subscriptions
+    CLOSE = 'CLOSE'
+  end
+end

data/lib/nostr/event.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Nostr
+  # The only object type that exists in Nostr is an event. Events are immutable.
+  class Event < EventFragment
+    # 32-bytes sha256 of the the serialized event data.
+    # To obtain the event.id, we sha256 the serialized event. The serialization is done over the UTF-8 JSON-serialized
+    # string (with no white space or line breaks)
+    #
+    # @api public
+    #
+    # @example Getting the event id
+    #   event.id # => 'ccf9fdf3e1466d7c20969c71ec98defcf5f54aee088513e1b73ccb7bd770d460'
+    #
+    # @return [String]
+    #
+    attr_reader :id
+
+    # 64-bytes signature of the sha256 hash of the serialized event data, which is
+    # the same as the "id" field
+    #
+    # @api public
+    #
+    # @example Getting the event signature
+    #   event.sig # => ''
+    #
+    # @return [String]
+    #
+    attr_reader :sig
+
+    # Instantiates a new Event
+    #
+    # @api public
+    #
+    # @example Instantiating a new event
+    #   Nostr::Event.new(
+    #    id: 'ccf9fdf3e1466d7c20969c71ec98defcf5f54aee088513e1b73ccb7bd770d460',
+    #    pubkey: '48df4af6e240ac5f7c5de89bf5941b249880be0e87d03685b178ccb1a315f52e',
+    #    created_at: 1230981305,
+    #    kind: 1,
+    #    tags: [],
+    #    content: 'Your feedback is appreciated, now pay $8',
+    #    sig: '123ac2923b792ce730b3da34f16155470ab13c8f97f9c53eaeb334f1fb3a5dc9a7f643
+    #          937c6d6e9855477638f5655c5d89c9aa5501ea9b578a66aced4f1cd7b3'
+    # )
+    #
+    #
+    # @param id [String] 32-bytes sha256 of the the serialized event data.
+    # @param sig [String] 64-bytes signature of the sha256 hash of the serialized event data, which is
+    # the same as the "id" field
+    #
+    def initialize(id:, sig:, **kwargs)
+      super(**kwargs)
+
+      @id = id
+      @sig = sig
+    end
+
+    # Converts the event to a hash
+    #
+    # @api public
+    #
+    # @example Converting the event to a hash
+    #  event.to_h
+    #
+    # @return [Hash] The event as a hash.
+    #
+    def to_h
+      {
+        id:,
+        pubkey:,
+        created_at:,
+        kind:,
+        tags:,
+        content:,
+        sig:
+      }
+    end
+
+    # Compares two events. Returns true if all attributes are equal and false otherwise
+    #
+    # @api public
+    #
+    # @example
+    #  event1 == event2 # => true
+    #
+    # @return [Boolean] True if all attributes are equal and false otherwise
+    #
+    def ==(other)
+      to_h == other.to_h
+    end
+  end
+end

data/lib/nostr/event_fragment.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Nostr
+  # Part of an +Event+. A complete +Event+ must have an +id+ and a +sig+.
+  class EventFragment
+    # 32-bytes hex-encoded public key of the event creator
+    #
+    # @api public
+    #
+    # @example
+    #   event.pubkey # => '48df4af6e240ac5f7c5de89bf5941b249880be0e87d03685b178ccb1a315f52e'
+    #
+    # @return [String]
+    #
+    attr_reader :pubkey
+
+    # Date of the creation of the vent. A UNIX timestamp, in seconds
+    #
+    # @api public
+    #
+    # @example
+    #   event.created_at # => 1230981305
+    #
+    # @return [Integer]
+    #
+    attr_reader :created_at
+
+    # The kind of the event. An integer from 0 to 2
+    #
+    # @api public
+    #
+    # @example
+    #   event.kind # => 1
+    #
+    # @return [Integer]
+    #
+    attr_reader :kind
+
+    # An array of tags. Each tag is an array of strings
+    #
+    # @api public
+    #
+    # @example Tags referencing an event
+    #  event.tags #=> [["e", "event_id", "relay URL"]]
+    #
+    # @example Tags referencing a key
+    #  event.tags #=> [["p", "event_id", "relay URL"]]
+    #
+    # @return [Array<Array>]
+    #
+    attr_reader :tags
+
+    # An arbitrary string
+    #
+    # @api public
+    #
+    # @example
+    #  event.content # => 'Your feedback is appreciated, now pay $8'
+    #
+    # @return [String]
+    #
+    attr_reader :content
+
+    # Instantiates a new EventFragment
+    #
+    # @api public
+    #
+    # @example
+    #   Nostr::EventFragment.new(
+    #     pubkey: 'ccf9fdf3e1466d7c20969c71ec98defcf5f54aee088513e1b73ccb7bd770d460',
+    #     created_at: 1230981305,
+    #     kind: 1,
+    #     tags: [['e', '189df012cfff8a075785b884bd702025f4a7a37710f581c4ac9d33e24b585408']],
+    #     content: 'Your feedback is appreciated, now pay $8'
+    #   )
+    #
+    # @param pubkey [String] 32-bytes hex-encoded public key of the event creator.
+    # @param created_at [Integer] Date of the creation of the vent. A UNIX timestamp, in seconds.
+    # @param kind [Integer] The kind of the event. An integer from 0 to 2.
+    # @param tags [Array<Array>] An array of tags. Each tag is an array of strings.
+    # @param content [String] Arbitrary string.
+    #
+    def initialize(pubkey:, kind:, content:, created_at: Time.now.to_i, tags: [])
+      @pubkey = pubkey
+      @created_at = created_at
+      @kind = kind
+      @tags = tags
+      @content = content
+    end
+
+    # Serializes the event fragment, to obtain a SHA256 hash of it
+    #
+    # @api public
+    #
+    # @example Converting the event to a hash
+    #   event_fragment.serialize
+    #
+    # @return [Array] The event fragment as an array.
+    #
+    def serialize
+      [
+        0,
+        pubkey,
+        created_at,
+        kind,
+        tags,
+        content
+      ]
+    end
+  end
+end

data/lib/nostr/event_kind.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Nostr
+  # Defines the event kinds that can be emitted by clients.
+  module EventKind
+    # The content is set to a stringified JSON object +{name: <username>, about: <string>,
+    # picture: <url, string>}+ describing the user who created the event. A relay may delete past set_metadata
+    # events once it gets a new one for the same pubkey.
+    #
+    # @return [Integer]
+    #
+    SET_METADATA = 0
+
+    # The content is set to the text content of a note (anything the user wants to say).
+    # Non-plaintext notes should instead use kind 1000-10000 as described in NIP-16.
+    #
+    # @return [Integer]
+    #
+    TEXT_NOTE = 1
+
+    # The content is set to the URL (e.g., wss://somerelay.com) of a relay the event creator wants to
+    # recommend to its followers.
+    #
+    # @return [Integer]
+    #
+    RECOMMEND_SERVER = 2
+  end
+end