f37f7bb6a4e8f432d1ddaccaa7d86cb3f2485329
6 rpcSessionID
= L
.env
.sessionid
|| '00000000000000000000000000000000',
7 rpcBaseURL
= L
.url('admin/ubus'),
8 rpcInterceptorFns
= [];
16 * The `LuCI.rpc` class provides high level ubus JSON-RPC abstractions
17 * and means for listing and invoking remove RPC methods.
19 return baseclass
.extend(/** @lends LuCI.rpc.prototype */ {
21 call: function(req
, cb
, nobatch
) {
24 if (Array
.isArray(req
)) {
26 return Promise
.resolve([]);
28 for (var i
= 0; i
< req
.length
; i
++)
30 q
+= '%s%s.%s'.format(
37 return request
.post(rpcBaseURL
+ q
, req
, {
38 timeout
: (L
.env
.rpctimeout
|| 20) * 1000,
44 parseCallReply: function(req
, res
) {
47 if (res
instanceof Error
)
48 return req
.reject(res
);
52 L
.raise('RPCError', 'RPC call to %s/%s failed with HTTP error %d: %s',
53 req
.object
, req
.method
, res
.status
, res
.statusText
|| '?');
62 * The interceptor args are intentionally swapped.
63 * Response is passed as first arg to align with Request class interceptors
65 Promise
.all(rpcInterceptorFns
.map(function(fn
) { return fn(msg
, req
) }))
66 .then(this.handleCallReply
.bind(this, req
, msg
))
70 handleCallReply: function(req
, msg
) {
71 var type
= Object
.prototype.toString
,
75 /* verify message frame */
76 if (!L
.isObject(msg
) || msg
.jsonrpc
!= '2.0')
77 L
.raise('RPCError', 'RPC call to %s/%s returned invalid message frame',
78 req
.object
, req
.method
);
80 /* check error condition */
81 if (L
.isObject(msg
.error
) && msg
.error
.code
&& msg
.error
.message
)
82 L
.raise('RPCError', 'RPC call to %s/%s failed with error %d: %s',
83 req
.object
, req
.method
, msg
.error
.code
, msg
.error
.message
|| '?');
89 if (!req
.object
&& !req
.method
) {
92 else if (Array
.isArray(msg
.result
)) {
93 if (req
.raise
&& msg
.result
[0] !== 0)
94 L
.raise('RPCError', 'RPC call to %s/%s failed with ubus code %d: %s',
95 req
.object
, req
.method
, msg
.result
[0], this.getStatusText(msg
.result
[0]));
97 ret
= (msg
.result
.length
> 1) ? msg
.result
[1] : msg
.result
[0];
101 for (var key
in req
.expect
) {
102 if (ret
!= null && key
!= '')
105 if (ret
== null || type
.call(ret
) != type
.call(req
.expect
[key
]))
106 ret
= req
.expect
[key
];
113 if (typeof(req
.filter
) == 'function') {
115 req
.priv
[1] = req
.params
;
116 ret
= req
.filter
.apply(this, req
.priv
);
123 * Lists available remote ubus objects or the method signatures of
126 * This function has two signatures and is sensitive to the number of
127 * arguments passed to it:
129 * Returns an array containing the names of all remote `ubus` objects
130 * - `list("objname", ...)`
131 * Returns method signatures for each given `ubus` object name.
133 * @param {...string} [objectNames]
134 * If any object names are given, this function will return the method
135 * signatures of each given object.
137 * @returns {Promise<Array<string>|Object<string, Object<string, Object<string, string>>>>}
138 * When invoked without arguments, this function will return a promise
139 * resolving to an array of `ubus` object names. When invoked with one or
140 * more arguments, a promise resolving to an object describing the method
141 * signatures of each requested `ubus` object name will be returned.
148 params
: arguments
.length
? this.varargs(arguments
) : undefined
151 return new Promise(L
.bind(function(resolveFn
, rejectFn
) {
152 /* store request info */
159 this.call(msg
, this.parseCallReply
.bind(this, req
));
164 * @typedef {Object} DeclareOptions
167 * @property {string} object
168 * The name of the remote `ubus` object to invoke.
170 * @property {string} method
171 * The name of the remote `ubus` method to invoke.
173 * @property {string[]} [params]
174 * Lists the named parameters expected by the remote `ubus` RPC method.
175 * The arguments passed to the resulting generated method call function
176 * will be mapped to named parameters in the order they appear in this
179 * Extraneous parameters passed to the generated function will not be
180 * sent to the remote procedure but are passed to the
181 * {@link LuCI.rpc~filterFn filter function} if one is specified.
184 * - `params: [ "foo", "bar" ]` -
185 * When the resulting call function is invoked with `fn(true, false)`,
186 * the corresponding args object sent to the remote procedure will be
187 * `{ foo: true, bar: false }`.
188 * - `params: [ "test" ], filter: function(reply, args, extra) { ... }` -
189 * When the resultung generated function is invoked with
190 * `fn("foo", "bar", "baz")` then `{ "test": "foo" }` will be sent as
191 * argument to the remote procedure and the filter function will be
192 * invoked with `filterFn(reply, [ "foo" ], "bar", "baz")`
194 * @property {Object<string,*>} [expect]
195 * Describes the expected return data structure. The given object is
196 * supposed to contain a single key selecting the value to use from
197 * the returned `ubus` reply object. The value of the sole key within
198 * the `expect` object is used to infer the expected type of the received
201 * If the received data does not contain `expect`'s key, or if the
202 * type of the data differs from the type of the value in the expect
203 * object, the expect object's value is returned as default instead.
205 * The key in the `expect` object may be an empty string (`''`) in which
206 * case the entire reply object is selected instead of one of its subkeys.
208 * If the `expect` option is omitted, the received reply will be returned
209 * as-is, regardless of its format or type.
212 * - `expect: { '': { error: 'Invalid response' } }` -
213 * This requires the entire `ubus` reply to be a plain JavaScript
214 * object. If the reply isn't an object but e.g. an array or a numeric
215 * error code instead, it will get replaced with
216 * `{ error: 'Invalid response' }` instead.
217 * - `expect: { results: [] }` -
218 * This requires the received `ubus` reply to be an object containing
219 * a key `results` with an array as value. If the received reply does
220 * not contain such a key, or if `reply.results` points to a non-array
221 * value, the empty array (`[]`) will be used instead.
222 * - `expect: { success: false }` -
223 * This requires the received `ubus` reply to be an object containing
224 * a key `success` with a boolean value. If the reply does not contain
225 * `success` or if `reply.success` is not a boolean value, `false` will
226 * be returned as default instead.
228 * @property {LuCI.rpc~filterFn} [filter]
229 * Specfies an optional filter function which is invoked to transform the
230 * received reply data before it is returned to the caller.
232 * @property {boolean} [reject=false]
233 * If set to `true`, non-zero ubus call status codes are treated as fatal
234 * error and lead to the rejection of the call promise. The default
235 * behaviour is to resolve with the call return code value instead.
239 * The filter function is invoked to transform a received `ubus` RPC call
240 * reply before returning it to the caller.
242 * @callback LuCI.rpc~filterFn
245 * The received `ubus` reply data or a subset of it as described in the
246 * `expect` option of the RPC call declaration. In case of remote call
247 * errors, `data` is numeric `ubus` error code instead.
249 * @param {Array<*>} args
250 * The arguments the RPC method has been invoked with.
252 * @param {...*} extraArgs
253 * All extraneous arguments passed to the RPC method exceeding the number
254 * of arguments describes in the RPC call declaration.
257 * The return value of the filter function will be returned to the caller
258 * of the RPC method as-is.
262 * The generated invocation function is returned by
263 * {@link LuCI.rpc#declare rpc.declare()} and encapsulates a single
266 * Calling this function will execute a remote `ubus` HTTP call request
267 * using the arguments passed to it as arguments and return a promise
268 * resolving to the received reply values.
270 * @callback LuCI.rpc~invokeFn
272 * @param {...*} params
273 * The parameters to pass to the remote procedure call. The given
274 * positional arguments will be named to named RPC parameters according
275 * to the names specified in the `params` array of the method declaration.
277 * Any additional parameters exceeding the amount of arguments in the
278 * `params` declaration are passed as private extra arguments to the
279 * declared filter function.
281 * @return {Promise<*>}
282 * Returns a promise resolving to the result data of the remote `ubus`
283 * RPC method invocation, optionally substituted and filtered according
284 * to the `expect` and `filter` declarations.
288 * Describes a remote RPC call procedure and returns a function
291 * @param {LuCI.rpc.DeclareOptions} options
292 * If any object names are given, this function will return the method
293 * signatures of each given object.
295 * @returns {LuCI.rpc~invokeFn}
296 * Returns a new function implementing the method call described in
299 declare: function(options
) {
300 return Function
.prototype.bind
.call(function(rpc
, options
) {
301 var args
= this.varargs(arguments
, 2);
302 return new Promise(function(resolveFn
, rejectFn
) {
303 /* build parameter object */
306 if (Array
.isArray(options
.params
))
307 for (p_off
= 0; p_off
< options
.params
.length
; p_off
++)
308 params
[options
.params
[p_off
]] = args
[p_off
];
310 /* all remaining arguments are private args */
311 var priv
= [ undefined, undefined ];
312 for (; p_off
< args
.length
; p_off
++)
313 priv
.push(args
[p_off
]);
315 /* store request info */
317 expect
: options
.expect
,
318 filter
: options
.filter
,
323 object
: options
.object
,
324 method
: options
.method
,
325 raise
: options
.reject
328 /* build message object */
342 rpc
.call(msg
, rpc
.parseCallReply
.bind(rpc
, req
), options
.nobatch
);
344 }, this, this, options
);
348 * Returns the current RPC session id.
351 * Returns the 32 byte session ID string used for authenticating remote
354 getSessionID: function() {
359 * Set the RPC session id to use.
361 * @param {string} sid
362 * Sets the 32 byte session ID string used for authenticating remote
365 setSessionID: function(sid
) {
370 * Returns the current RPC base URL.
373 * Returns the RPC URL endpoint to issue requests against.
375 getBaseURL: function() {
380 * Set the RPC base URL to use.
382 * @param {string} sid
383 * Sets the RPC URL endpoint to issue requests against.
385 setBaseURL: function(url
) {
390 * Translates a numeric `ubus` error code into a human readable
393 * @param {number} statusCode
394 * The numeric status code.
397 * Returns the textual description of the code.
399 getStatusText: function(statusCode
) {
400 switch (statusCode
) {
401 case 0: return _('Command OK');
402 case 1: return _('Invalid command');
403 case 2: return _('Invalid argument');
404 case 3: return _('Method not found');
405 case 4: return _('Resource not found');
406 case 5: return _('No data received');
407 case 6: return _('Permission denied');
408 case 7: return _('Request timeout');
409 case 8: return _('Not supported');
410 case 9: return _('Unspecified error');
411 case 10: return _('Connection lost');
412 default: return _('Unknown error code');
417 * Registered interceptor functions are invoked before the standard reply
418 * parsing and handling logic.
420 * By returning rejected promises, interceptor functions can cause the
421 * invocation function to fail, regardless of the received reply.
423 * Interceptors may also modify their message argument in-place to
424 * rewrite received replies before they're processed by the standard
425 * response handling code.
427 * A common use case for such functions is to detect failing RPC replies
428 * due to expired authentication in order to trigger a new login.
430 * @callback LuCI.rpc~interceptorFn
433 * The unprocessed, JSON decoded remote RPC method call reply.
435 * Since interceptors run before the standard parsing logic, the reply
436 * data is not verified for correctness or filtered according to
437 * `expect` and `filter` specifications in the declarations.
439 * @param {Object} req
440 * The related request object which is an extended variant of the
441 * declaration object, allowing access to internals of the invocation
442 * function such as `filter`, `expect` or `params` values.
444 * @return {Promise<*>|*}
445 * Interceptor functions may return a promise to defer response
446 * processing until some delayed work completed. Any values the returned
447 * promise resolves to are ignored.
449 * When the returned promise rejects with an error, the invocation
450 * function will fail too, forwarding the error to the caller.
454 * Registers a new interceptor function.
456 * @param {LuCI.rpc~interceptorFn} interceptorFn
457 * The inteceptor function to register.
459 * @returns {LuCI.rpc~interceptorFn}
460 * Returns the given function value.
462 addInterceptor: function(interceptorFn
) {
463 if (typeof(interceptorFn
) == 'function')
464 rpcInterceptorFns
.push(interceptorFn
);
465 return interceptorFn
;
469 * Removes a registered interceptor function.
471 * @param {LuCI.rpc~interceptorFn} interceptorFn
472 * The inteceptor function to remove.
475 * Returns `true` if the given function has been removed or `false`
476 * if it has not been found.
478 removeInterceptor: function(interceptorFn
) {
479 var oldlen
= rpcInterceptorFns
.length
, i
= oldlen
;
481 if (rpcInterceptorFns
[i
] === interceptorFn
)
482 rpcInterceptorFns
.splice(i
, 1);
483 return (rpcInterceptorFns
.length
< oldlen
);