modules/luci-base/htdocs/luci-static/resources/rpc.js

   1 'use strict';
   2 'require baseclass';
   3 'require request';
   4
   5 var rpcRequestID = 1,
   6     rpcSessionID = L.env.sessionid || '00000000000000000000000000000000',
   7     rpcBaseURL = L.url('admin/ubus'),
   8     rpcInterceptorFns = [];
   9
  10 /**
  11  * @class rpc
  12  * @memberof LuCI
  13  * @hideconstructor
  14  * @classdesc
  15  *
  16  * The `LuCI.rpc` class provides high level ubus JSON-RPC abstractions
  17  * and means for listing and invoking remove RPC methods.
  18  */
  19 return baseclass.extend(/** @lends LuCI.rpc.prototype */ {
  20         /* privates */
  21         call: function(req, cb, nobatch) {
  22                 var q = '';
  23
  24                 if (Array.isArray(req)) {
  25                         if (req.length == 0)
  26                                 return Promise.resolve([]);
  27
  28                         for (var i = 0; i < req.length; i++)
  29                                 if (req[i].params)
  30                                         q += '%s%s.%s'.format(
  31                                                 q ? ';' : '/',
  32                                                 req[i].params[1],
  33                                                 req[i].params[2]
  34                                         );
  35                 }
  36                 else if (req.params) {
  37                         q += '/%s.%s'.format(req.params[1], req.params[2]);
  38                 }
  39
  40                 return request.post(rpcBaseURL + q, req, {
  41                         timeout: (L.env.rpctimeout || 20) * 1000,
  42                         nobatch: nobatch,
  43                         credentials: true
  44                 }).then(cb, cb);
  45         },
  46
  47         parseCallReply: function(req, res) {
  48                 var msg = null;
  49
  50                 if (res instanceof Error)
  51                         return req.reject(res);
  52
  53                 try {
  54                         if (!res.ok)
  55                                 L.raise('RPCError', 'RPC call to %s/%s failed with HTTP error %d: %s',
  56                                         req.object, req.method, res.status, res.statusText || '?');
  57
  58                         msg = res.json();
  59                 }
  60                 catch (e) {
  61                         return req.reject(e);
  62                 }
  63
  64                 /*
  65                  * The interceptor args are intentionally swapped.
  66                  * Response is passed as first arg to align with Request class interceptors
  67                  */
  68                 Promise.all(rpcInterceptorFns.map(function(fn) { return fn(msg, req) }))
  69                         .then(this.handleCallReply.bind(this, req, msg))
  70                         .catch(req.reject);
  71         },
  72
  73         handleCallReply: function(req, msg) {
  74                 var type = Object.prototype.toString,
  75                     ret = null;
  76
  77                 try {
  78                         /* verify message frame */
  79                         if (!L.isObject(msg) || msg.jsonrpc != '2.0')
  80                                 L.raise('RPCError', 'RPC call to %s/%s returned invalid message frame',
  81                                         req.object, req.method);
  82
  83                         /* check error condition */
  84                         if (L.isObject(msg.error) && msg.error.code && msg.error.message)
  85                                 L.raise('RPCError', 'RPC call to %s/%s failed with error %d: %s',
  86                                         req.object, req.method, msg.error.code, msg.error.message || '?');
  87                 }
  88                 catch (e) {
  89                         return req.reject(e);
  90                 }
  91
  92                 if (!req.object && !req.method) {
  93                         ret = msg.result;
  94                 }
  95                 else if (Array.isArray(msg.result)) {
  96                         if (req.raise && msg.result[0] !== 0)
  97                                 L.raise('RPCError', 'RPC call to %s/%s failed with ubus code %d: %s',
  98                                         req.object, req.method, msg.result[0], this.getStatusText(msg.result[0]));
  99
 100                         ret = (msg.result.length > 1) ? msg.result[1] : msg.result[0];
 101                 }
 102
 103                 if (req.expect) {
 104                         for (var key in req.expect) {
 105                                 if (ret != null && key != '')
 106                                         ret = ret[key];
 107
 108                                 if (ret == null || type.call(ret) != type.call(req.expect[key]))
 109                                         ret = req.expect[key];
 110
 111                                 break;
 112                         }
 113                 }
 114
 115                 /* apply filter */
 116                 if (typeof(req.filter) == 'function') {
 117                         req.priv[0] = ret;
 118                         req.priv[1] = req.params;
 119                         ret = req.filter.apply(this, req.priv);
 120                 }
 121
 122                 req.resolve(ret);
 123         },
 124
 125         /**
 126          * Lists available remote ubus objects or the method signatures of
 127          * specific objects.
 128          *
 129          * This function has two signatures and is sensitive to the number of
 130          * arguments passed to it:
 131          *  - `list()` -
 132          *    Returns an array containing the names of all remote `ubus` objects
 133          *  - `list("objname", ...)`
 134          *    Returns method signatures for each given `ubus` object name.
 135          *
 136          * @param {...string} [objectNames]
 137          * If any object names are given, this function will return the method
 138          * signatures of each given object.
 139          *
 140          * @returns {Promise<Array<string>|Object<string, Object<string, Object<string, string>>>>}
 141          * When invoked without arguments, this function will return a promise
 142          * resolving to an array of `ubus` object names. When invoked with one or
 143          * more arguments, a promise resolving to an object describing the method
 144          * signatures of each requested `ubus` object name will be returned.
 145          */
 146         list: function() {
 147                 var msg = {
 148                         jsonrpc: '2.0',
 149                         id:      rpcRequestID++,
 150                         method:  'list',
 151                         params:  arguments.length ? this.varargs(arguments) : undefined
 152                 };
 153
 154                 return new Promise(L.bind(function(resolveFn, rejectFn) {
 155                         /* store request info */
 156                         var req = {
 157                                 resolve: resolveFn,
 158                                 reject:  rejectFn
 159                         };
 160
 161                         /* call rpc */
 162                         this.call(msg, this.parseCallReply.bind(this, req));
 163                 }, this));
 164         },
 165
 166         /**
 167          * @typedef {Object} DeclareOptions
 168          * @memberof LuCI.rpc
 169          *
 170          * @property {string} object
 171          * The name of the remote `ubus` object to invoke.
 172          *
 173          * @property {string} method
 174          * The name of the remote `ubus` method to invoke.
 175          *
 176          * @property {string[]} [params]
 177          * Lists the named parameters expected by the remote `ubus` RPC method.
 178          * The arguments passed to the resulting generated method call function
 179          * will be mapped to named parameters in the order they appear in this
 180          * array.
 181          *
 182          * Extraneous parameters passed to the generated function will not be
 183          * sent to the remote procedure but are passed to the
 184          * {@link LuCI.rpc~filterFn filter function} if one is specified.
 185          *
 186          * Examples:
 187          *  - `params: [ "foo", "bar" ]` -
 188          *    When the resulting call function is invoked with `fn(true, false)`,
 189          *    the corresponding args object sent to the remote procedure will be
 190          *    `{ foo: true, bar: false }`.
 191          *  - `params: [ "test" ], filter: function(reply, args, extra) { ... }` -
 192          *    When the resultung generated function is invoked with
 193          *    `fn("foo", "bar", "baz")` then `{ "test": "foo" }` will be sent as
 194          *    argument to the remote procedure and the filter function will be
 195          *    invoked with `filterFn(reply, [ "foo" ], "bar", "baz")`
 196          *
 197          * @property {Object<string,*>} [expect]
 198          * Describes the expected return data structure. The given object is
 199          * supposed to contain a single key selecting the value to use from
 200          * the returned `ubus` reply object. The value of the sole key within
 201          * the `expect` object is used to infer the expected type of the received
 202          * `ubus` reply data.
 203          *
 204          * If the received data does not contain `expect`'s key, or if the
 205          * type of the data differs from the type of the value in the expect
 206          * object, the expect object's value is returned as default instead.
 207          *
 208          * The key in the `expect` object may be an empty string (`''`) in which
 209          * case the entire reply object is selected instead of one of its subkeys.
 210          *
 211          * If the `expect` option is omitted, the received reply will be returned
 212          * as-is, regardless of its format or type.
 213          *
 214          * Examples:
 215          *  - `expect: { '': { error: 'Invalid response' } }` -
 216          *    This requires the entire `ubus` reply to be a plain JavaScript
 217          *    object. If the reply isn't an object but e.g. an array or a numeric
 218          *    error code instead, it will get replaced with
 219          *    `{ error: 'Invalid response' }` instead.
 220          *  - `expect: { results: [] }` -
 221          *    This requires the received `ubus` reply to be an object containing
 222          *    a key `results` with an array as value. If the received reply does
 223          *    not contain such a key, or if `reply.results` points to a non-array
 224          *    value, the empty array (`[]`) will be used instead.
 225          *  - `expect: { success: false }` -
 226          *    This requires the received `ubus` reply to be an object containing
 227          *    a key `success` with a boolean value. If the reply does not contain
 228          *    `success` or if `reply.success` is not a boolean value, `false` will
 229          *    be returned as default instead.
 230          *
 231          * @property {LuCI.rpc~filterFn} [filter]
 232          * Specfies an optional filter function which is invoked to transform the
 233          * received reply data before it is returned to the caller.
 234          *
 235          * @property {boolean} [reject=false]
 236          * If set to `true`, non-zero ubus call status codes are treated as fatal
 237          * error and lead to the rejection of the call promise. The default
 238          * behaviour is to resolve with the call return code value instead.
 239          */
 240
 241         /**
 242          * The filter function is invoked to transform a received `ubus` RPC call
 243          * reply before returning it to the caller.
 244          *
 245          * @callback LuCI.rpc~filterFn
 246          *
 247          * @param {*} data
 248          * The received `ubus` reply data or a subset of it as described in the
 249          * `expect` option of the RPC call declaration. In case of remote call
 250          * errors, `data` is numeric `ubus` error code instead.
 251          *
 252          * @param {Array<*>} args
 253          * The arguments the RPC method has been invoked with.
 254          *
 255          * @param {...*} extraArgs
 256          * All extraneous arguments passed to the RPC method exceeding the number
 257          * of arguments describes in the RPC call declaration.
 258          *
 259          * @return {*}
 260          * The return value of the filter function will be returned to the caller
 261          * of the RPC method as-is.
 262          */
 263
 264         /**
 265          * The generated invocation function is returned by
 266          * {@link LuCI.rpc#declare rpc.declare()} and encapsulates a single
 267          * RPC method call.
 268          *
 269          * Calling this function will execute a remote `ubus` HTTP call request
 270          * using the arguments passed to it as arguments and return a promise
 271          * resolving to the received reply values.
 272          *
 273          * @callback LuCI.rpc~invokeFn
 274          *
 275          * @param {...*} params
 276          * The parameters to pass to the remote procedure call. The given
 277          * positional arguments will be named to named RPC parameters according
 278          * to the names specified in the `params` array of the method declaration.
 279          *
 280          * Any additional parameters exceeding the amount of arguments in the
 281          * `params` declaration are passed as private extra arguments to the
 282          * declared filter function.
 283          *
 284          * @return {Promise<*>}
 285          * Returns a promise resolving to the result data of the remote `ubus`
 286          * RPC method invocation, optionally substituted and filtered according
 287          * to the `expect` and `filter` declarations.
 288          */
 289
 290         /**
 291          * Describes a remote RPC call procedure and returns a function
 292          * implementing it.
 293          *
 294          * @param {LuCI.rpc.DeclareOptions} options
 295          * If any object names are given, this function will return the method
 296          * signatures of each given object.
 297          *
 298          * @returns {LuCI.rpc~invokeFn}
 299          * Returns a new function implementing the method call described in
 300          * `options`.
 301          */
 302         declare: function(options) {
 303                 return Function.prototype.bind.call(function(rpc, options) {
 304                         var args = this.varargs(arguments, 2);
 305                         return new Promise(function(resolveFn, rejectFn) {
 306                                 /* build parameter object */
 307                                 var p_off = 0;
 308                                 var params = { };
 309                                 if (Array.isArray(options.params))
 310                                         for (p_off = 0; p_off < options.params.length; p_off++)
 311                                                 params[options.params[p_off]] = args[p_off];
 312
 313                                 /* all remaining arguments are private args */
 314                                 var priv = [ undefined, undefined ];
 315                                 for (; p_off < args.length; p_off++)
 316                                         priv.push(args[p_off]);
 317
 318                                 /* store request info */
 319                                 var req = {
 320                                         expect:  options.expect,
 321                                         filter:  options.filter,
 322                                         resolve: resolveFn,
 323                                         reject:  rejectFn,
 324                                         params:  params,
 325                                         priv:    priv,
 326                                         object:  options.object,
 327                                         method:  options.method,
 328                                         raise:   options.reject
 329                                 };
 330
 331                                 /* build message object */
 332                                 var msg = {
 333                                         jsonrpc: '2.0',
 334                                         id:      rpcRequestID++,
 335                                         method:  'call',
 336                                         params:  [
 337                                                 rpcSessionID,
 338                                                 options.object,
 339                                                 options.method,
 340                                                 params
 341                                         ]
 342                                 };
 343
 344                                 /* call rpc */
 345                                 rpc.call(msg, rpc.parseCallReply.bind(rpc, req), options.nobatch);
 346                         });
 347                 }, this, this, options);
 348         },
 349
 350         /**
 351          * Returns the current RPC session id.
 352          *
 353          * @returns {string}
 354          * Returns the 32 byte session ID string used for authenticating remote
 355          * requests.
 356          */
 357         getSessionID: function() {
 358                 return rpcSessionID;
 359         },
 360
 361         /**
 362          * Set the RPC session id to use.
 363          *
 364          * @param {string} sid
 365          * Sets the 32 byte session ID string used for authenticating remote
 366          * requests.
 367          */
 368         setSessionID: function(sid) {
 369                 rpcSessionID = sid;
 370         },
 371
 372         /**
 373          * Returns the current RPC base URL.
 374          *
 375          * @returns {string}
 376          * Returns the RPC URL endpoint to issue requests against.
 377          */
 378         getBaseURL: function() {
 379                 return rpcBaseURL;
 380         },
 381
 382         /**
 383          * Set the RPC base URL to use.
 384          *
 385          * @param {string} sid
 386          * Sets the RPC URL endpoint to issue requests against.
 387          */
 388         setBaseURL: function(url) {
 389                 rpcBaseURL = url;
 390         },
 391
 392         /**
 393          * Translates a numeric `ubus` error code into a human readable
 394          * description.
 395          *
 396          * @param {number} statusCode
 397          * The numeric status code.
 398          *
 399          * @returns {string}
 400          * Returns the textual description of the code.
 401          */
 402         getStatusText: function(statusCode) {
 403                 switch (statusCode) {
 404                 case 0: return _('Command OK');
 405                 case 1: return _('Invalid command');
 406                 case 2: return _('Invalid argument');
 407                 case 3: return _('Method not found');
 408                 case 4: return _('Resource not found');
 409                 case 5: return _('No data received');
 410                 case 6: return _('Permission denied');
 411                 case 7: return _('Request timeout');
 412                 case 8: return _('Not supported');
 413                 case 9: return _('Unspecified error');
 414                 case 10: return _('Connection lost');
 415                 default: return _('Unknown error code');
 416                 }
 417         },
 418
 419         /**
 420          * Registered interceptor functions are invoked before the standard reply
 421          * parsing and handling logic.
 422          *
 423          * By returning rejected promises, interceptor functions can cause the
 424          * invocation function to fail, regardless of the received reply.
 425          *
 426          * Interceptors may also modify their message argument in-place to
 427          * rewrite received replies before they're processed by the standard
 428          * response handling code.
 429          *
 430          * A common use case for such functions is to detect failing RPC replies
 431          * due to expired authentication in order to trigger a new login.
 432          *
 433          * @callback LuCI.rpc~interceptorFn
 434          *
 435          * @param {*} msg
 436          * The unprocessed, JSON decoded remote RPC method call reply.
 437          *
 438          * Since interceptors run before the standard parsing logic, the reply
 439          * data is not verified for correctness or filtered according to
 440          * `expect` and `filter` specifications in the declarations.
 441          *
 442          * @param {Object} req
 443          * The related request object which is an extended variant of the
 444          * declaration object, allowing access to internals of the invocation
 445          * function such as `filter`, `expect` or `params` values.
 446          *
 447          * @return {Promise<*>|*}
 448          * Interceptor functions may return a promise to defer response
 449          * processing until some delayed work completed. Any values the returned
 450          * promise resolves to are ignored.
 451          *
 452          * When the returned promise rejects with an error, the invocation
 453          * function will fail too, forwarding the error to the caller.
 454          */
 455
 456         /**
 457          * Registers a new interceptor function.
 458          *
 459          * @param {LuCI.rpc~interceptorFn} interceptorFn
 460          * The inteceptor function to register.
 461          *
 462          * @returns {LuCI.rpc~interceptorFn}
 463          * Returns the given function value.
 464          */
 465         addInterceptor: function(interceptorFn) {
 466                 if (typeof(interceptorFn) == 'function')
 467                         rpcInterceptorFns.push(interceptorFn);
 468                 return interceptorFn;
 469         },
 470
 471         /**
 472          * Removes a registered interceptor function.
 473          *
 474          * @param {LuCI.rpc~interceptorFn} interceptorFn
 475          * The inteceptor function to remove.
 476          *
 477          * @returns {boolean}
 478          * Returns `true` if the given function has been removed or `false`
 479          * if it has not been found.
 480          */
 481         removeInterceptor: function(interceptorFn) {
 482                 var oldlen = rpcInterceptorFns.length, i = oldlen;
 483                 while (i--)
 484                         if (rpcInterceptorFns[i] === interceptorFn)
 485                                 rpcInterceptorFns.splice(i, 1);
 486                 return (rpcInterceptorFns.length < oldlen);
 487         }
 488 });