Class BSV::Network::Protocol ¶

Inherits: Object

Protocol is the base class for all BSV network protocol definitions.

Subclasses declare their commands via the endpoint DSL macro. Each endpoint maps a command name (Symbol) to an HTTP method, a path template, and a response handler. The subscription macro is a placeholder for future WebSocket support.

Subclass isolation is enforced via an inherited hook — each subclass receives its own empty +@endpoints+ and +@subscriptions+ hashes. Adding endpoints to a subclass never affects the parent.

HTTP dispatch routes through call: if a +call_+ escape hatch method exists on the instance, it is called; otherwise default_call interpolates the URL template, makes the HTTP request, and maps the response to a Result.

Example¶

class MyProtocol < BSV::Network::Protocol
  endpoint :get_tx, :get, '/v1/tx/{txid}'
  endpoint :broadcast, :post, '/v1/tx', response: :json
end

p = MyProtocol.new(base_url: 'https://api.example.com', network: 'main')
MyProtocol.commands #=> #<Set: {:get_tx, :broadcast}>

Attributes¶

api_key [R] ¶

Returns the value of attribute api_key.

base_url [R] ¶

Returns the value of attribute base_url.

http_client [R] ¶

Returns the value of attribute http_client.

network [R] ¶

Returns the value of attribute network.

Public Class Methods¶

commands() ¶

Returns a Set of command names declared on this protocol class. - @return [Set]

endpoint(command_name, http_method, path_template, response: = :raw) ¶

Registers an endpoint definition for this protocol class. - @param command_name [Symbol] the command name (e.g. +:broadcast+) - @param http_method [Symbol] +:get+ or +:post+ - @param path_template [String] path with +{param}+ placeholders - @param response [Symbol, #call] response handler — +:raw+, +:json+, +:json_array+, or a callable (lambda/proc)

endpoints() ¶

Returns a frozen copy of the endpoints hash for introspection. - @return [Hash]

inherited(subclass) ¶

Give each subclass its own isolated +@endpoints+ and +@subscriptions+ hashes. Deep-copies the parent's endpoints so that existing declarations are inherited but mutations on the subclass do not affect the parent.

subscription(event_name, path, **opts) ¶

Registers a subscription definition. Placeholder for Phase C WebSocket support. Stored but not callable at runtime. - @param event_name [Symbol] the event name - @param path [String] WebSocket path - @param opts [Hash] additional options (reserved)

subscriptions() ¶

Returns a frozen copy of the subscriptions hash for introspection. - @return [Hash]

Public Instance Methods¶

call(command_name, *args, **kwargs) ¶

Dispatches a command by name.

If a method named +call_+ exists on the instance it is used as an escape hatch — that method receives args and kwargs and MUST return a Result. Otherwise default_call is invoked.

Subscriptions are not callable; calling one raises NotImplementedError. - @param command_name [Symbol, String] command to invoke - @param args [Array] positional arguments forwarded to path interpolation - @param kwargs [Hash] keyword arguments forwarded to path interpolation - @raise [ArgumentError] when command_name is not registered - @return [Result::Success, Result::Error, Result::NotFound]

default_call(command_name, *args, **kwargs) ¶

Dispatches a command directly via HTTP, bypassing any escape hatch.

Path placeholders (+{param}+) are filled from kwargs first; any remaining placeholders are filled positionally from args. Named kwargs take precedence over positional args for the same placeholder.

POST body is taken from +kwargs.delete(:body)+ (removed before path interpolation). - @param command_name [Symbol] registered command name - @param args [Array] positional path parameters - @param kwargs [Hash] named path parameters (and optional +:body+) - @raise [ArgumentError] when command_name is not registered or a required path parameter is missing - @return [Result::Success, Result::Error, Result::NotFound]

initialize(base_url:, api_key: = nil, network: = nil, http_client: = nil) ¶

• @param base_url [String] base URL, may contain +{network}+ placeholder
• @param api_key [String, nil] API key for authenticated requests
• @param network [String, Symbol, nil] network name (e.g. 'main', 'test')
• @param http_client [Object, nil] injectable HTTP client (used in Task 3)
• @return [Protocol] a new instance of Protocol