jsonrpc-middleware 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e61b560d7db3538454d0d5206eaea1fc2a86a01b25294c4d56de4b6237dd120
-  data.tar.gz: 1d7255ba3a462bbc9d53efbec3ba9b242f773b2c4fa270de280b951ea3b05743
+  metadata.gz: ea48adea36c2a7f311bb0b5c8d1868999f9ec7b6530a2b933600f8433655b63c
+  data.tar.gz: 8e4abe926bb02da6155650d2296d5df0b07562de6ce08163ad433df09ac40e1d
 SHA512:
-  metadata.gz: b3d9b2f802ac5ffd1f342c45d00e001113ebf857e09208deac8560dd75a06f6201bcc4e7a99f0184cb6c1a48497d70e922d59d7f6b476c93f530584b60fa0066
-  data.tar.gz: b07c00f97c85c9a41f82decf00dbf58f10c2655e1011f0e3e6d5e63ff2f90cee88e310f6c892a8d49c2ec94aea5cfa7dccdf9292b7940256f82b1591823df2e2
+  metadata.gz: 90b63747650ce423ae7f5f881db75c0c8fceabc05e627fa0fd6647cd6b67c1445eab3a09dfc19cac3b5d62d9814e9a692b96e50e0bbdc41bd8b83d9d3582b6bc
+  data.tar.gz: 64c40bf854999ce3c0cdc8261a921d603ed8ec664c46a6e0d4578afbc9404e693f7b8ff5456385fdcb671867049d4e07028efa51ac48276a5adfd5c4a24b194d

data/.aiexclude

@@ -0,0 +1,4 @@
+.ruby-lsp
+.vscode
+coverage
+doc

data/.claude/commands/document.md

@@ -0,0 +1,105 @@
+# Document
+
+Generates documentation for Ruby code using YARD with 100% coverage enforcement.
+
+## Commands
+
+Generate documentation:
+```bash
+bundle exec rake yard
+```
+
+Format YARD comments:
+```bash
+bundle exec rake yard:format
+```
+
+Verify 100% documentation coverage:
+```bash
+bundle exec rake verify_measurements
+```
+
+Check for documentation quality issues:
+```bash
+bundle exec rake yard:junk
+```
+
+Generate coverage report:
+```bash
+bundle exec rake yardstick_measure
+```
+
+## Configuration
+
+Requires `.yardstick.yml` in project root with 100% threshold:
+```yaml
+threshold: 100
+rules:
+  ApiTag::Presence: { enabled: true }
+  ApiTag::Inclusion: { enabled: true }
+  ApiTag::ProtectedMethod: { enabled: true }
+  ApiTag::PrivateMethod: { enabled: true }
+  ExampleTag: { enabled: true }
+  ReturnTag: { enabled: true }
+  Summary::Presence: { enabled: true }
+  Summary::Delimiter: { enabled: true }
+```
+
+## Coverage Report
+
+After running measurement, check detailed line-by-line issues:
+```bash
+cat measurements/report.txt
+```
+
+Report shows specific file, line number, method, and documentation issues that need fixing.
+
+## Documentation Standards
+
+### Required Tags
+- Every public/private method, class, and module requires `@api public` or `@api private`
+- All parameters: `@param name [Type] Description`
+- All returns: `@return [Type] Description` (use `[void]` if no return)
+- Examples required for all public methods: `@example Description`
+- Error conditions: `@raise [ExceptionClass] When this occurs`
+
+### Type Notation
+- Use `String` not `string`
+- Arrays: `Array<String>` for string arrays
+- Hashes: `Hash{String=>Object}` for hash types
+- Use `Boolean` not `bool`, `Integer` not `int`
+- Nullable types: `String, nil` or `String|nil`
+
+### Formatting Rules
+- Blank lines required between YARD tag groups
+- Exception: `@param` and `@option` tags can be grouped together
+- Wrap class/method names in `+` markers: `+PrivateKey+`
+- Cross-reference related methods: `@see #other_method`
+
+### Documentation Structure
+```ruby
+# Brief one-line summary ending with period.
+#
+# @api public
+#
+# @example Description of example
+#   code_example
+#   result # => expected_output
+#
+# @param name [Type] Description
+# @param other [Type] Other description  
+#
+# @return [Type] Description
+#
+# @raise [ExceptionClass] When this exception occurs
+#
+def method_name
+end
+```
+
+## Integration
+
+Documentation verification is included in the quality assurance pipeline:
+```bash
+bundle exec rake qa
+```

data/.claude/docs/yard.md

@@ -0,0 +1,602 @@
+# Ruby YARD Documentation Guidelines
+
+This document outlines the comprehensive documentation standards for Ruby projects, based on the best practices demonstrated in professional Ruby gems. These guidelines ensure 100% documentation coverage and maintainable, professional-quality code documentation.
+
+## Table of Contents
+
+- [Documentation Philosophy](#documentation-philosophy)
+- [YARD Configuration](#yard-configuration)
+- [Basic Documentation Structure](#basic-documentation-structure)
+- [API Visibility Tags](#api-visibility-tags)
+- [Method Documentation](#method-documentation)
+- [Class and Module Documentation](#class-and-module-documentation)
+- [Attribute Documentation](#attribute-documentation)
+- [Examples](#examples)
+- [Parameter and Return Documentation](#parameter-and-return-documentation)
+- [Error Documentation](#error-documentation)
+- [Constants Documentation](#constants-documentation)
+- [Inheritance Documentation](#inheritance-documentation)
+- [Quality Enforcement](#quality-enforcement)
+- [Best Practices](#best-practices)
+
+## Documentation Philosophy
+
+Every piece of public and private code must be documented. Documentation serves multiple purposes:
+- **API Contract**: Clearly defines what methods do and how to use them
+- **Maintenance**: Helps future developers (including yourself) understand the code
+- **Testing Guide**: Examples serve as additional test cases
+- **User Experience**: Enables IDE autocompletion and contextual help
+
+## YARD Configuration
+
+Create a `.yardstick.yml` file in your project root with 100% coverage requirements:
+
+```yaml
+threshold: 100
+rules:
+  ApiTag::Presence:
+    enabled: true
+  ApiTag::Inclusion:
+    enabled: true
+  ApiTag::ProtectedMethod:
+    enabled: true
+  ApiTag::PrivateMethod:
+    enabled: true
+  ExampleTag:
+    enabled: true
+  ReturnTag:
+    enabled: true
+  Summary::Presence:
+    enabled: true
+  Summary::Length:
+    enabled: false
+  Summary::Delimiter:
+    enabled: true
+  Summary::SingleLine:
+    enabled: false
+```
+
+## Basic Documentation Structure
+
+Every documented element follows this structure:
+
+```ruby
+# Brief one-line summary ending with a period
+#
+# @api public|private
+#
+# @example Description of example
+#   code_example
+#   result # => expected_output
+#
+# @param name [Type] Description
+# @param other_name [Type] Other description
+#
+# @return [Type] Description
+#
+# @raise [ExceptionClass] When this exception occurs
+#
+```
+
+### YARD Tag Spacing Rules
+
+**IMPORTANT**: All YARD tags must have a blank line between them, with the following exceptions:
+- `@param` tags can be grouped together without blank lines
+- `@option` tags can be grouped together without blank lines
+- `@param` and `@option` tags can be grouped together without blank lines when they relate to the same parameter
+
+This ensures readable documentation while allowing logical grouping of parameter-related tags.
+
+## API Visibility Tags
+
+**REQUIRED**: Every public and private method, class, and module must have an `@api` tag.
+
+### Public API
+```ruby
+# @api public
+```
+Use for:
+- Public methods intended for external use
+- Public classes and modules
+- Public attributes and constants
+
+### Private API
+```ruby
+# @api private
+```
+Use for:
+- Private methods
+- Internal implementation details
+- Protected methods
+- Private attributes
+
+## Method Documentation
+
+### Public Method Example
+```ruby
+# Generates a pair of private and public keys
+#
+# @api public
+#
+# @example
+#   keypair = keygen.generate_key_pair
+#   keypair # #<Nostr::KeyPair:0x0000000107bd3550
+#    @private_key="893c4cc8088924796b41dc788f7e2f746734497010b1a9f005c1faad7074b900",
+#    @public_key="2d7661527d573cc8e84f665fa971dd969ba51e2526df00c149ff8e40a58f9558">
+#
+# @return [KeyPair] An object containing a private key and a public key.
+#
+def generate_key_pair
+  # implementation
+end
+```
+
+### Private Method Example
+```ruby
+# Validates the keys
+#
+# @api private
+#
+# @param private_key [PrivateKey] 32-bytes hex-encoded private key.
+# @param public_key [PublicKey] 32-bytes hex-encoded public key.
+#
+# @raise ArgumentError when the private key is not a +PrivateKey+
+# @raise ArgumentError when the public key is not a +PublicKey+
+#
+# @return [void]
+#
+def validate_keys(private_key, public_key)
+  # implementation
+end
+```
+
+### Constructor Documentation
+```ruby
+# 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'
+#   )
+#
+# @param id [String|nil] 32-bytes sha256 of the the serialized event data.
+# @param sig [String|nil] 64-bytes signature of the sha256 hash.
+# @param pubkey [String] 32-bytes hex-encoded public key of the event creator.
+# @param created_at [Integer] Date of the creation. A UNIX timestamp, in seconds.
+# @param kind [Integer] The kind of the event. An integer from 0 to 3.
+# @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: [], id: nil, sig: nil)
+  # implementation
+end
+```
+
+### Methods with Keyword Arguments
+```ruby
+# Instantiates a new Filter
+#
+# @api public
+#
+# @example
+#   Nostr::Filter.new(
+#     ids: ['c24881c305c5cfb7c1168be7e9b0e150'],
+#     authors: ['000000001c5c45196786e79f83d21fe801549fdc98e2c26f96dcef068a5dbcd7'],
+#     kinds: [0, 1, 2],
+#     since: 1230981305,
+#     until: 1292190341
+#   )
+#
+# @param kwargs [Hash]
+# @option kwargs [Array<String>, nil] ids A list of event ids
+# @option kwargs [Array<String>, nil] authors A list of pubkeys
+# @option kwargs [Array<Integer>, nil] kinds A list of a kind numbers
+# @option kwargs [Integer, nil] since A timestamp, events must be newer than this
+# @option kwargs [Integer, nil] until A timestamp, events must be older than this
+# @option kwargs [Integer, nil] limit Maximum number of events to be returned
+#
+def initialize(**kwargs)
+  # implementation
+end
+```
+
+## Class and Module Documentation
+
+### Class Documentation
+```ruby
+# The only object type that exists in Nostr is an event. Events are immutable.
+class Event
+  # class body
+end
+```
+
+### Module Documentation
+```ruby
+# Performs cryptographic operations.
+class Crypto
+  # class body
+end
+```
+
+### Inheritance Documentation
+```ruby
+# 32-bytes lowercase hex-encoded private key
+class PrivateKey < Key
+  # class body
+end
+```
+
+### Namespace Module
+```ruby
+# Encapsulates all the gem's logic
+module Nostr
+  # module body
+end
+```
+
+## Attribute Documentation
+
+### Reader Attributes
+```ruby
+# 32-bytes hex-encoded public key of the event creator
+#
+# @api public
+#
+# @example
+#   event.pubkey # => '48df4af6e240ac5f7c5de89bf5941b249880be0e87d03685b178ccb1a315f52e'
+#
+# @return [String]
+#
+attr_reader :pubkey
+```
+
+### Accessor Attributes
+```ruby
+# 64-bytes signature of the sha256 hash of the serialized event data
+#
+# @api public
+#
+# @example Getting the event signature
+#   event.sig # => '058613f8d34c053294cc28b7f9e1f8f0e80fd1ac94fb20f2da6ca514e7360b39'
+#
+# @example Setting the event signature
+#   event.sig = '058613f8d34c053294cc28b7f9e1f8f0e80fd1ac94fb20f2da6ca514e7360b39'
+#   event.sig # => '058613f8d34c053294cc28b7f9e1f8f0e80fd1ac94fb20f2da6ca514e7360b39'
+#
+# @return [String|nil]
+#
+attr_accessor :sig
+```
+
+### Private Attributes
+```ruby
+# The elliptic curve group. Used to generate public and private keys
+#
+# @api private
+#
+# @return [ECDSA::Group]
+#
+attr_reader :group
+```
+
+## Examples
+
+### Multiple Examples
+```ruby
+# 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
+# @param filter [Filter] A set of attributes representing events of interest
+#
+# @return [Subscription] The subscription object
+#
+def subscribe(subscription_id: SecureRandom.hex, filter: Filter.new)
+  # implementation
+end
+```
+
+### Complex Examples
+```ruby
+# Allows array destructuring of the KeyPair
+#
+# @api public
+#
+# @example Implicit usage of `to_ary` for destructuring
+#   keypair = Nostr::KeyPair.new(
+#     private_key: Nostr::PrivateKey.new('7d1e4219a5e7d8342654c675085bfbdee143f0eb0f0921f5541ef1705a2b407d'),
+#     public_key: Nostr::PublicKey.new('15678d8fbc126fa326fac536acd5a6dcb5ef64b3d939abe31d6830cba6cd26d6'),
+#   )
+#   # The `to_ary` method can be implicitly used for array destructuring:
+#   private_key, public_key = keypair
+#   # Now `private_key` and `public_key` hold the respective values.
+#
+# @example Explicit usage of `to_ary`
+#   array_representation = keypair.to_ary
+#   # array_representation is now an array: [PrivateKey, PublicKey]
+#
+# @return [Array<PrivateKey, PublicKey>] An array containing the keys in order
+#
+def to_ary
+  # implementation
+end
+```
+
+## Parameter and Return Documentation
+
+### Parameter Types
+```ruby
+# @param event [Event] The event to be signed
+# @param private_key [PrivateKey] 32-bytes hex-encoded private key
+# @param kwargs [Hash] Configuration options
+# @param subscription_id [String] The subscription id
+# @param filter [Filter, nil] Optional filter for events
+# @param items [Array<String>] List of string items
+# @param enabled [Boolean] Whether feature is enabled
+# @param count [Integer] Number of items
+# @param rate [Float] Processing rate
+```
+
+### Return Types
+```ruby
+# @return [Event] A signed event
+# @return [String] The generated private key
+# @return [Array<Event>] List of matching events
+# @return [Hash{String=>Object}] Configuration mapping
+# @return [Boolean] True if valid, false otherwise
+# @return [void] This method does not return a value
+# @return [String, nil] The result or nil if not found
+```
+
+### Complex Return Types
+```ruby
+# @return [Array<PrivateKey, PublicKey>] An array containing the PrivateKey and PublicKey in that order
+# @return [Hash{String=>Subscription}] Mapping of subscription IDs to objects
+```
+
+## Error Documentation
+
+### Exception Handling
+```ruby
+# Validates the hex value of the private key
+#
+# @api private
+#
+# @param hex_value [String] The private key in hex format
+#
+# @raise InvalidKeyTypeError when the private key is not a string
+# @raise InvalidKeyLengthError when the private key's length is not 64 characters
+# @raise InvalidKeyFormatError when the private key is in an invalid format
+#
+# @return [void]
+#
+def validate_hex_value(hex_value)
+  # implementation
+end
+```
+
+### Error Class Documentation
+```ruby
+# Raised when the private key's length is not 64 characters
+#
+# @api public
+#
+class InvalidKeyLengthError < KeyValidationError
+  # Initializes the error
+  #
+  # @example
+  #   InvalidKeyLengthError.new('private')
+  #
+  # @param key_kind [String] The kind of key that is invalid (public or private)
+  #
+  def initialize(key_kind)
+    super("Invalid #{key_kind} key length. It should have 64 characters.")
+  end
+end
+```
+
+## Constants Documentation
+
+### Simple Constants
+```ruby
+# Numeric base of the OpenSSL big number used in an event content's encryption.
+#
+# @return [Integer]
+#
+BN_BASE = 16
+```
+
+### Complex Constants
+```ruby
+# The regular expression for hexadecimal lowercase characters
+#
+# @return [Regexp] The regular expression for hexadecimal lowercase characters
+#
+FORMAT = /^[a-f0-9]+$/
+```
+
+## Inheritance Documentation
+
+### Subclass with Custom Behavior
+```ruby
+# 64-bytes lowercase hex of the signature of the sha256 hash of the serialized event data,
+# which is the same as the "id" field
+class Signature < String
+  # Custom implementation
+end
+```
+
+### Module Inclusion
+```ruby
+# Clients can talk with relays and can subscribe to any set of events using a subscription filters.
+#
+# 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
+
+  # class body
+end
+```
+
+## Quality Enforcement
+
+Our project enforces 100% documentation coverage using the `yardstick` gem and maintains documentation quality with the `yard:junk` task. This ensures that all code is thoroughly documented, maintainable, and easy for developers to use.
+
+### How it Works
+
+1.  **Configuration**: A `.yardstick.yml` file in the project root sets the documentation coverage threshold to 100% and defines specific documentation rules.
+
+2.  **Measurement**: The `yardstick_measure` Rake task measures the current documentation coverage against the configured rules. Run it using:
+
+    ```bash
+    bundle exec rake yardstick_measure
+    ```
+
+    This task generates a detailed report in `measurements/report.txt` that lists all documentation issues that need to be addressed.
+
+3.  **Verification**: The `verify_measurements` Rake task checks if the coverage meets the 100% threshold. Run it using:
+
+    ```bash
+    bundle exec rake verify_measurements
+    ```
+
+    This task will fail if coverage is below 100%, displaying the current coverage percentage and indicating that documentation improvements are needed.
+
+4.  **Review Report**: Always check the contents of `measurements/report.txt` after running measurement tasks. This file contains specific details about:
+    - Missing method documentation
+    - Incomplete parameter descriptions
+    - Missing return value documentation
+    - Missing examples
+    - Incorrect API tags
+
+    Each line in the report shows the file, line number, method, and specific issue that needs to be addressed to achieve 100% documentation compliance.
+
+### Rake Integration
+
+The `Rakefile` integrates `yardstick` into our development workflow. The `qa` task, which runs a full suite of tests and checks, includes the documentation verification step.
+
+```ruby
+# Rakefile
+require 'yardstick/rake/measurement'
+require 'yardstick/rake/verify'
+
+yardstick_options = YAML.load_file('.yardstick.yml')
+
+Yardstick::Rake::Measurement.new(:yardstick_measure, yardstick_options)
+Yardstick::Rake::Verify.new
+
+desc 'Test, lint and perform security and documentation audits'
+task qa: %w[spec rubocop yard:junk verify_measurements bundle:audit]
+```
+
+### CI Integration
+
+Continuous Integration (CI) automatically enforces our documentation standard on every commit by running:
+
+```bash
+bundle exec rake verify_measurements
+```
+
+This prevents any code with incomplete documentation from being merged.
+
+## Best Practices
+
+### 1. **Always Use @api Tags**
+Every method, class, and module must have an `@api public` or `@api private` tag.
+
+### 2. **Provide Meaningful Examples**
+Examples should show real usage, not trivial cases:
+
+```ruby
+# GOOD
+# @example Subscribing to text notes from the last hour
+#   filter = Nostr::Filter.new(
+#     kinds: [Nostr::EventKind::TEXT_NOTE],
+#     since: Time.now.to_i - 3600
+#   )
+#   subscription = client.subscribe(filter: filter)
+
+# BAD
+# @example
+#   client.subscribe
+```
+
+### 3. **Document All Parameters**
+Even obvious parameters should be documented:
+
+```ruby
+# @param id [String] The unique identifier
+# @param name [String] The human-readable name
+```
+
+### 4. **Use Consistent Type Notation**
+- `String` not `string`
+- `Array<String>` for arrays of strings
+- `Hash{String=>Object}` for hash types
+- `Boolean` not `bool`
+- `Integer` not `int`
+
+### 5. **Document Return Values**
+Every method must have a `@return` tag, even if it returns `void`.
+
+### 6. **Cross-Reference Related Methods**
+```ruby
+# @see #valid_sig?
+# @see Crypto#check_sig!
+```
+
+### 7. **Use Code Formatting**
+Wrap class names and method names in `+` markers:
+```ruby
+# @raise ArgumentError when the private key is not a +PrivateKey+
+```
+
+### 8. **Document Inheritance Clearly**
+When a class inherits behavior, mention it:
+```ruby
+# Base error class for all signature validation errors
+class SignatureValidationError < Error; end
+```
+
+### 9. **Version Constants**
+```ruby
+# The version of the gem
+VERSION = '0.7.0'
+```
+
+### 10. **Multi-line Examples**
+For complex examples, use proper formatting:
+```ruby
+# @example Creating a comprehensive filter
+#   filter = Nostr::Filter.new(
+#     kinds: [
+#       Nostr::EventKind::TEXT_NOTE,
+#       Nostr::EventKind::ENCRYPTED_DIRECT_MESSAGE
+#     ],
+#     since: Time.now.to_i - 3600, # 1 hour ago
+#     until: Time.now.to_i,
+#     limit: 20,
+#   )
+```
+
+This documentation standard ensures that your Ruby projects maintain professional-quality documentation that supports both development and maintenance activities while providing excellent IDE integration and user experience.