From 12bdb5f5509c205a7a868e02964ed25d10f4b000 Mon Sep 17 00:00:00 2001 From: Marek Kotewicz Date: Wed, 14 Jan 2015 12:01:11 +0100 Subject: [PATCH] providers documentation --- lib/autoprovider.js | 17 ++++++++++------- lib/contract.js | 23 ++++++++++++++++++++++- lib/httprpc.js | 32 ++++++++++++++++++++++++++++++++ lib/providermanager.js | 11 ++++++++++- lib/qt.js | 12 ++++++++++++ lib/websocket.js | 24 ++++++++++++++++++++++-- 6 files changed, 108 insertions(+), 11 deletions(-) diff --git a/lib/autoprovider.js b/lib/autoprovider.js index 8460a144f8..a2c265ccbf 100644 --- a/lib/autoprovider.js +++ b/lib/autoprovider.js @@ -33,13 +33,16 @@ if (process.env.NODE_ENV !== 'build') { var web3 = require('./web3'); // jshint ignore:line } -/// Automatically tries to setup correct provider -/// First it checkes if we are ethereum browser (if navigator.qt object is available) -/// if yes, we are using QtProvider -/// if no, we check if it is possible to establish websockets connection with ethereum (ws://localhost:40404/eth is default) -/// if it's not possible, we are using httprpc provider (http://localhost:8080) -/// The constructor allows you to specify uris on which we are trying to connect over http or websockets -/// You can do that by passing objects with fields httrpc and websockets +/** + * AutoProvider object prototype is implementing 'provider protocol' + * Automatically tries to setup correct provider(Qt, WebSockets or HttpRpc) + * First it checkes if we are ethereum browser (if navigator.qt object is available) + * if yes, we are using QtProvider + * if no, we check if it is possible to establish websockets connection with ethereum (ws://localhost:40404/eth is default) + * if it's not possible, we are using httprpc provider (http://localhost:8080) + * The constructor allows you to specify uris on which we are trying to connect over http or websockets + * You can do that by passing objects with fields httrpc and websockets + */ var AutoProvider = function (userOptions) { if (web3.haveProvider()) { return; diff --git a/lib/contract.js b/lib/contract.js index eb7fbf0187..d38746f01d 100644 --- a/lib/contract.js +++ b/lib/contract.js @@ -27,9 +27,29 @@ if (process.env.NODE_ENV !== 'build') { var abi = require('./abi'); -// method signature length in bytes +/// method signature length in bytes var ETH_METHOD_SIGNATURE_LENGTH = 4; +/** + * This method should be called when we want to call / transact some solidity method from javascript + * it returns an object which has same methods available as solidity contract description + * usage example: + * + * var abi = [{ + * name: 'myMethod', + * inputs: [{ name: 'a', type: 'string' }], + * outputs: [{name 'd', type: 'string' }] + * }]; // contract abi + * + * var myContract = web3.eth.contract('0x0123123121', abi); // creation of contract object + * + * myContract.myMethod('this is test string param for call').cal(); // myMethod call + * myContract.myMethod('this is test string param for transact').transact() // myMethod transact + * + * @param address - address of the contract, which should be called + * @param desc - abi json description of the contract, which is being created + * @returns contract object + */ var contract = function (address, desc) { var inputParser = abi.inputParser(desc); var outputParser = abi.outputParser(desc); @@ -70,3 +90,4 @@ var contract = function (address, desc) { }; module.exports = contract; + diff --git a/lib/httprpc.js b/lib/httprpc.js index d315201f1c..de3ae84784 100644 --- a/lib/httprpc.js +++ b/lib/httprpc.js @@ -26,11 +26,21 @@ if (process.env.NODE_ENV !== 'build') { var XMLHttpRequest = require('xmlhttprequest').XMLHttpRequest; // jshint ignore:line } +/** + * HttpRpcProvider object prototype is implementing 'provider protocol' + * Should be used when we want to connect to ethereum backend over http && jsonrpc + * It's compatible with cpp client + * The contructor allows to specify host uri + * This provider is using in-browser polling mechanism + */ var HttpRpcProvider = function (host) { this.handlers = []; this.host = host; }; +/// Transforms inner message to proper jsonrpc object +/// @param inner message object +/// @returns jsonrpc object function formatJsonRpcObject(object) { return { jsonrpc: '2.0', @@ -40,6 +50,9 @@ function formatJsonRpcObject(object) { }; } +/// Transforms jsonrpc object to inner message +/// @param incoming jsonrpc message +/// @returns inner message object function formatJsonRpcMessage(message) { var object = JSON.parse(message); @@ -50,6 +63,10 @@ function formatJsonRpcMessage(message) { }; } +/// Prototype object method +/// Asynchronously sends request to server +/// @param payload is inner message object +/// @param cb is callback which is being called when response is comes back HttpRpcProvider.prototype.sendRequest = function (payload, cb) { var data = formatJsonRpcObject(payload); @@ -63,6 +80,11 @@ HttpRpcProvider.prototype.sendRequest = function (payload, cb) { }; }; +/// Prototype object method +/// Should be called when we want to send single api request to server +/// Asynchronous +/// On response it passes message to handlers +/// @param payload is inner message object HttpRpcProvider.prototype.send = function (payload) { var self = this; this.sendRequest(payload, function (request) { @@ -72,6 +94,13 @@ HttpRpcProvider.prototype.send = function (payload) { }); }; +/// Prototype object method +/// Should be called only for polling requests +/// Asynchronous +/// On response it passege message to handlers, but only if message's result is true or not empty array +/// Otherwise response is being silently ignored +/// @param payload is inner message object +/// @id is id of poll that we are calling HttpRpcProvider.prototype.poll = function (payload, id) { var self = this; this.sendRequest(payload, function (request) { @@ -85,6 +114,8 @@ HttpRpcProvider.prototype.poll = function (payload, id) { }); }; +/// Prototype object property +/// Should be used to set message handlers for this provider Object.defineProperty(HttpRpcProvider.prototype, "onmessage", { set: function (handler) { this.handlers.push(handler); @@ -92,3 +123,4 @@ Object.defineProperty(HttpRpcProvider.prototype, "onmessage", { }); module.exports = HttpRpcProvider; + diff --git a/lib/providermanager.js b/lib/providermanager.js index 28122cb42a..00266154da 100644 --- a/lib/providermanager.js +++ b/lib/providermanager.js @@ -28,7 +28,15 @@ if (process.env.NODE_ENV !== 'build') { var web3 = require('./web3'); // jshint ignore:line } -/// Provider manager object prototype +/** + * Provider manager object prototype + * It's responsible for passing messages to providers + * If no provider is set it's responsible for queuing requests + * It's also responsible for polling the ethereum node for incoming messages + * Default poll timeout is 12 seconds + * If we are running ethereum.js inside ethereum browser, there are backend based tools responsible for polling, + * and provider manager polling mechanism is not used + */ var ProviderManager = function() { this.queued = []; this.polls = []; @@ -111,3 +119,4 @@ ProviderManager.prototype.stopPolling = function (pollId) { }; module.exports = ProviderManager; + diff --git a/lib/qt.js b/lib/qt.js index f022395476..1b3a9547b3 100644 --- a/lib/qt.js +++ b/lib/qt.js @@ -21,6 +21,11 @@ * @date 2014 */ +/** + * QtProvider object prototype is implementing 'provider protocol' + * Should be used inside ethereum browser. It's compatible with cpp and go clients. + * It uses navigator.qt object to pass the messages to native bindings + */ var QtProvider = function() { this.handlers = []; @@ -32,10 +37,17 @@ var QtProvider = function() { }; }; +/// Prototype object method +/// Should be called when we want to send single api request to native bindings +/// Asynchronous +/// Response will be received by navigator.qt.onmessage method and passed to handlers +/// @param payload is inner message object QtProvider.prototype.send = function(payload) { navigator.qt.postMessage(JSON.stringify(payload)); }; +/// Prototype object property +/// Should be used to set message handlers for this provider Object.defineProperty(QtProvider.prototype, "onmessage", { set: function(handler) { this.handlers.push(handler); diff --git a/lib/websocket.js b/lib/websocket.js index 5b40075e43..e8663ecf53 100644 --- a/lib/websocket.js +++ b/lib/websocket.js @@ -27,9 +27,17 @@ if (process.env.NODE_ENV !== 'build') { var WebSocket = require('ws'); // jshint ignore:line } +/** + * WebSocketProvider object prototype is implementing 'provider protocol' + * Should be used when we want to connect to ethereum backend over websockets + * It's compatible with go client + * The constructor allows to specify host uri + */ var WebSocketProvider = function(host) { + // onmessage handlers this.handlers = []; + // queue will be filled with messages if send is invoked before the ws is ready this.queued = []; this.ready = false; @@ -46,15 +54,20 @@ var WebSocketProvider = function(host) { this.ws.onopen = function() { self.ready = true; - for(var i = 0; i < self.queued.length; i++) { + for (var i = 0; i < self.queued.length; i++) { // Resend self.send(self.queued[i]); } }; }; +/// Prototype object method +/// Should be called when we want to send single api request to server +/// Asynchronous, it's using websockets +/// Response for the call will be received by ws.onmessage +/// @param payload is inner message object WebSocketProvider.prototype.send = function(payload) { - if(this.ready) { + if (this.ready) { var data = JSON.stringify(payload); this.ws.send(data); @@ -63,13 +76,20 @@ WebSocketProvider.prototype.send = function(payload) { } }; +/// Prototype object method +/// Should be called to add handlers WebSocketProvider.prototype.onMessage = function(handler) { this.handlers.push(handler); }; +/// Prototype object method +/// Should be called to close websockets connection WebSocketProvider.prototype.unload = function() { this.ws.close(); }; + +/// Prototype object property +/// Should be used to set message handlers for this provider Object.defineProperty(WebSocketProvider.prototype, "onmessage", { set: function(provider) { this.onMessage(provider); } });