nostr 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 669ffcd3d585116e340888ace801690a0c596bb6d20f12acc80a7a8c933fa0e1
-  data.tar.gz: 1abe2ac66bcdd51c175e2ebb7b676d1d8a3508c12e783e674252d33948336215
+  metadata.gz: 371ed11c0474fd944cc55a054d553945623f7439f67c55f3eadc564805d2fb11
+  data.tar.gz: f7fbe86119bd7816e7066ea3603263dee7327b06daeb4b92f9e90977f52ef8ae
 SHA512:
-  metadata.gz: fb8845670cf90e66204225260aa76d50bcf76f3e8cd9ccae27bbb73e3384bb23fc411fdabcdbe6a2cbdfd1e5023d45ce5c4f8b42077b73c3c1e865e87fa5cce5
-  data.tar.gz: 5e02009ec661e34507a96ddb3c1866e76d3aab0a2f19c80f4228a53c783e01a1b226e76d39a35ef8de27b2be9c7a915435ab55666b7770d98cc54cdf1f387478
+  metadata.gz: fa602354304ce9e77377b80cab60146f51ac8943b1399070a87ce81a5e44582f0a23b50f1736fafd9d7d0f13042b8b7292b9d29684077ad878e2439ddf7970ef
+  data.tar.gz: 83fc3d535a1e35438522779ef7dc3e101b4fea3a3f9874db9457b4f6c61d74469ded6ba973923d731789d3c50d7aa66b1c0770d62451794d45b52720c7928ebf

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,22 @@ 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.3.0] - 2023-02-15
+
+### Added
+
+- Client compliance wth [NIP-02](https://github.com/nostr-protocol/nips/blob/master/02.md) (manage contact lists)
+
+## [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.3.0]: https://github.com/wilsonsilva/nostr/compare/v0.2.0...v0.3.0
+[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,212 @@ 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 when data is received through a WebSocket.
+
+```ruby
+client.on :message do |message|
+  puts message
+end
+
+# [
+#   "EVENT",
+#   "d34107357089bfc9882146d3bfab0386",
+#   {
+#     "content":"",
+#     "created_at":1676456512,
+#     "id":"18f63550da74454c5df7caa2a349edc5b2a6175ea4c5367fa4b4212781e5b310",
+#     "kind":3,
+#     "pubkey":"117a121fa41dc2caa0b3d6c5b9f42f90d114f1301d39f9ee96b646ebfee75e36",
+#     "sig":"d171420bd62cf981e8f86f2dd8f8f86737ea2bbe2d98da88db092991d125535860d982139a3c4be39886188613a9912ef380be017686a0a8b74231dc6e0b03cb",
+#     "tags":[
+#       ["p","1cc821cc2d47191b15fcfc0f73afed39a86ac6fb34fbfa7993ee3e0f0186ef7c"]
+#     ]
+#   }
+# ]
+```
+
+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)
+```
+
+### Creating/updating your contact list
+
+Every new contact list that gets published overwrites the past ones, so it should contain all entries.
+
+```ruby
+# Creating a contact list event with 2 contacts
+update_contacts_event = user.create_event(
+  kind: Nostr::EventKind::CONTACT_LIST,
+  tags: [
+    [
+      "p", # mandatory
+      "32e1827635450ebb3c5a7d12c1f8e7b2b514439ac10a67eef3d9fd9c5c68e245", # public key of the user to add to the contacts
+      "wss://alicerelay.com/", # can be an empty string or can be omitted
+      "alice" # can be an empty string or can be omitted
+    ],
+    [
+      "p", # mandatory
+      "3efdaebb1d8923ebd99c9e7ace3b4194ab45512e2be79c1b7d68d9243e0d2681", # public key of the user to add to the contacts
+      "wss://bobrelay.com/nostr", # can be an empty string or can be omitted
+      "bob" # can be an empty string or can be omitted
+    ],
+  ],
+)
+
+# Send it to the Relay
+client.publish(update_contacts_event)
+```
+
+## NIPS
+
+- [x] [NIP-01 - Client](https://github.com/nostr-protocol/nips/blob/master/01.md)
+- [x] [NIP-02 - Client](https://github.com/nostr-protocol/nips/blob/master/02.md)
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies.
@@ -39,17 +241,34 @@ The health and maintainability of the codebase is ensured through a set of
 Rake tasks to test, lint and audit the gem for security vulnerabilities and documentation:
 
 ```
-rake bundle:audit          # Checks for vulnerable versions of gems
-rake qa                    # Test, lint and perform security and documentation audits
-rake rubocop               # Lint the codebase with RuboCop
-rake rubocop:auto_correct  # Auto-correct RuboCop offenses
-rake spec                  # Run RSpec code examples
-rake verify_measurements   # Verify that yardstick coverage is at least 100%
-rake yard                  # Generate YARD Documentation
-rake yard:junk             # Check the junk in your YARD Documentation
-rake yardstick_measure     # Measure docs in lib/**/*.rb with yardstick
+rake build                    # Build nostr.gem into the pkg directory
+rake build:checksum           # Generate SHA512 checksum if nostr.gem into the checksums directory
+rake bundle:audit:check       # Checks the Gemfile.lock for insecure dependencies
+rake bundle:audit:update      # Updates the bundler-audit vulnerability database
+rake clean                    # Remove any temporary products
+rake clobber                  # Remove any generated files
+rake coverage                 # Run spec with coverage
+rake install                  # Build and install nostr.gem into system gems
+rake install:local            # Build and install nostr.gem into system gems without network access
+rake qa                       # Test, lint and perform security and documentation audits
+rake release[remote]          # Create a tag, build and push nostr.gem to rubygems.org
+rake rubocop                  # Run RuboCop
+rake rubocop:autocorrect      # Autocorrect RuboCop offenses (only when it's safe)
+rake rubocop:autocorrect_all  # Autocorrect RuboCop offenses (safe and unsafe)
+rake spec                     # Run RSpec code examples
+rake verify_measurements      # Verify that yardstick coverage is at least 100%
+rake yard                     # Generate YARD Documentation
+rake yard:junk                # Check the junk in your YARD Documentation
+rake yardstick_measure        # Measure docs in lib/**/*.rb with yardstick
 ```
 
+### Type checking
+
+This gem leverages [RBS](https://github.com/ruby/rbs), a language to describe the structure of Ruby programs. It is
+used to provide type checking and autocompletion in your editor. Run `bundle exec typeprof FILENAME` to generate
+an RBS definition for the given Ruby file. And validate all definitions using [Steep](https://github.com/soutaro/steep)
+with the command `bundle exec steep check`.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/wilsonsilva/nostr.

data/Steepfile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+target :lib do
+  signature 'sig'
+
+  check 'lib'
+
+  # Core libraries
+  library 'digest'
+  library 'securerandom'
+
+  # Gems
+  library 'json'
+end

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