Page 1 of 1

Barrister RPC IDL of Namecoin API brainstorm [closed]

Posted: Wed Apr 02, 2014 4:51 am
by indolering
Barrister RPC generates native JSON-RPC libraries uses an Interface Description Language. This would give Namecoin client libraries in Python, Java, PHP, Node.js, and Ruby, greatly reducing the amount of work needed to get started with Namecoin. I think such a library would be a prudent use of the NMC development fund, especially given its current size.

I would suggest 3 goals, one for a basic command set, another for the full command set, and a third which includes full unit tests for all functions akin to node-bitcoin's test harness (although, a mock server might be an acceptable substitute to a live Namecoin testnet-in-a-box).

For the basline goal:
  • name_list
  • name_scan
  • name_show
  • name_filter
  • getblockcount
  • getinfo
  • validateaddress
  • stop
Perhaps list and get functions as well? They would not be difficult to test....

**Update**
The IDL files have to have full in-line documentation as well, nothing major, mostly copy and paste from the wiki. Barrister will wrangle this into a standardized format so we can use it to generate generic Namecoin's API documentation : ).

Re: Barrister RPC IDL of Namecoin API

Posted: Thu Apr 03, 2014 12:49 pm
by phelix
hmm... there are already libs in c++ and python by domob.

Anybody else having an opinion on this?

In general I agree we should get the funds moving. But is this among the most pressing things?

Re: Barrister RPC IDL of Namecoin API

Posted: Thu Apr 03, 2014 9:11 pm
by indolering
That's just the problem, I've written an RPC library, domob has written 2 (one in C++ and one in PHP) it's not *hard* per-se. NMControl is just an RPC library + python convenience calls for Namecoind, but it's own for programmers working in Python. If we want more developers, we need high quality libraries that have full test coverage and documentation. At the moment, the documentation for each function is scattered all over. It makes development unpleasant, I mean, here is what it took for me to create wrangle name_filter():

Code: Select all

/**
   * Arguments for filter().
   * @typedef {Object} filter-args
   * @property {string} regex,
   * @property {?number} age,
   * @property {?number} start,
   * @property {?number} max,
   * @property {?boolean} stat
   * */

  /**
   * Returns all values whose name matches Regex.
   * @param {( string | {filter-args} )} args String regex or query parameters.
   * @returns {Array.<Object>}
   * TODO: turn namespace (d/) into parameter
   */
  this.filter = function(args) {
    args = args || '^d/';
    if (typeof args === 'string') {
      args = {'regex': args};
    }

    args.age = args.age || 36000;
    args.start = args.start || 0;
    args.max = args.max || 0;
    args.stat = args.stat || false;

    var query = [args.regex, args.age, args.start, args.max];


    //NOTE falsy check @ init, 'true' input COULD be 'stat' or 'hamburger'
    //check for (not false) and enter in 'stat'!
    if (args.stat !== false) {
      query.push('stat');
    }

    return new Promise(function(resolve, reject) {
      //Note that jsonrpc was modified and it looks for this specific
      //query, you cannot replace with generic jsonrpc w/out that mod.

      n.client.name_filter(query, function(err, value) {
          if (err) {
            console.log(err);
            reject(err);
          } else {
            resolve(value);
          }
        }
      );
    });

  };
  return this;
}
Fifty lines of code for one function call. Fifty. I shouldn't need to build an entire RPC library AND convenience libs just to communicate smoothly with Namecoin. My convenience functions for dealing with 5 Namecoin weigh in at ~200 lines. All just for *read only* functions! Multiply that across NMControl, NamecoinToBind, nameID, NMChain, MeowBit, Speech.js, Convergence ... 7 * 200 = 1,400 lines of code and most of it lacks test coverage and documentation.

I also tried doing the bare minimum of effort at first but it made writing the rest of my code a real pain. Debugging RPC libraries sucks because the debugger cannot trace it to the real problem. Sometimes it's your code throwing something your string construction didn't expect, sometimes it's Namecoin taking to long to respond and the debugger just gives up, and don't get me started on cross-platform development and config parsing. I spent a day trying to fix a single function before I gave up and just make a weird hack inside the RPC library to get working.

This is a good bounty project because a new developer can cut their teeth on it and the maintenance will be relatively low-effort.