LuCI. rpc

The LuCI.rpc class provides high level ubus JSON-RPC abstractions and means for listing and invoking remove RPC methods.

Source

Methods

addInterceptor(interceptorFn) → {LuCI.rpc.interceptorFn}

Registers a new interceptor function.

Parameters:
NameTypeDescription
interceptorFnLuCI.rpc.interceptorFn

The interceptor function to register.

Source
Returns:

Returns the given function value.

Type: 
LuCI.rpc.interceptorFn

declare(options) → {LuCI.rpc.invokeFn}

Describes a remote RPC call procedure and returns a function implementing it.

Parameters:
NameTypeDescription
optionsLuCI.rpc.DeclareOptions

If any object names are given, this function will return the method signatures of each given object.

Source
Returns:

Returns a new function implementing the method call described in options.

Type: 
LuCI.rpc.invokeFn

getBaseURL() → {string}

Returns the current RPC base URL.

Source
Returns:

Returns the RPC URL endpoint to issue requests against.

Type: 
string

getSessionID() → {string}

Returns the current RPC session id.

Source
Returns:

Returns the 32 byte session ID string used for authenticating remote requests.

Type: 
string

getStatusText(statusCode) → {string}

Translates a numeric ubus error code into a human readable description.

Parameters:
NameTypeDescription
statusCodenumber

The numeric status code.

Source
Returns:

Returns the textual description of the code.

Type: 
string

list(…argsopt) → {Promise.<(Array.<string>|Object.<string, Object.<string, Object.<string, string>>>)>}

Lists available remote ubus objects or the method signatures of specific objects.

This function has two signatures and is sensitive to the number of arguments passed to it:

  • list() - Returns an array containing the names of all remote ubus objects
  • list("objname", ...) Returns method signatures for each given ubus object name.
Parameters:
NameTypeAttributesDescription
argsstring<optional>
<repeatable>

(objectNames) If any object names are given, this function will return the method signatures of each given object.

Source
Returns:

When invoked without arguments, this function will return a promise resolving to an array of ubus object names. When invoked with one or more arguments, a promise resolving to an object describing the method signatures of each requested ubus object name will be returned.

Type: 
Promise.<(Array.<string>|Object.<string, Object.<string, Object.<string, string>>>)>

removeInterceptor(interceptorFn) → {boolean}

Removes a registered interceptor function.

Parameters:
NameTypeDescription
interceptorFnLuCI.rpc.interceptorFn

The interceptor function to remove.

Source
Returns:

Returns true if the given function has been removed or false if it has not been found.

Type: 
boolean

setBaseURL(url)

Set the RPC base URL to use.

Parameters:
NameTypeDescription
urlstring

Sets the RPC URL endpoint to issue requests against.

Source

setSessionID(sid)

Set the RPC session id to use.

Parameters:
NameTypeDescription
sidstring

Sets the 32 byte session ID string used for authenticating remote requests.

Source

Type Definitions

DeclareOptions

Type:
  • Object
Properties
NameTypeAttributesDefaultDescription
objectstring

The name of the remote ubus object to invoke.

methodstring

The name of the remote ubus method to invoke.

paramsArray.<string><optional>

Lists the named parameters expected by the remote ubus RPC method. The arguments passed to the resulting generated method call function will be mapped to named parameters in the order they appear in this array.

Extraneous parameters passed to the generated function will not be sent to the remote procedure but are passed to the filter function if one is specified.

Examples:

  • params: [ "foo", "bar" ] - When the resulting call function is invoked with fn(true, false), the corresponding args object sent to the remote procedure will be { foo: true, bar: false }.
  • params: [ "test" ], filter: function(reply, args, extra) { ... } - When the resulting generated function is invoked with fn("foo", "bar", "baz") then { "test": "foo" } will be sent as argument to the remote procedure and the filter function will be invoked with filterFn(reply, [ "foo" ], "bar", "baz")
expectObject.<string, *><optional>

Describes the expected return data structure. The given object is supposed to contain a single key selecting the value to use from the returned ubus reply object. The value of the sole key within the expect object is used to infer the expected type of the received ubus reply data.

If the received data does not contain expect's key, or if the type of the data differs from the type of the value in the expect object, the expect object's value is returned as default instead.

The key in the expect object may be an empty string ('') in which case the entire reply object is selected instead of one of its subkeys.

If the expect option is omitted, the received reply will be returned as-is, regardless of its format or type.

Examples:

  • expect: { '': { error: 'Invalid response' } } - This requires the entire ubus reply to be a plain JavaScript object. If the reply isn't an object but e.g. an array or a numeric error code instead, it will get replaced with { error: 'Invalid response' } instead.
  • expect: { results: [] } - This requires the received ubus reply to be an object containing a key results with an array as value. If the received reply does not contain such a key, or if reply.results points to a non-array value, the empty array ([]) will be used instead.
  • expect: { success: false } - This requires the received ubus reply to be an object containing a key success with a boolean value. If the reply does not contain success or if reply.success is not a boolean value, false will be returned as default instead.
filterLuCI.rpc.filterFn<optional>

Specifies an optional filter function which is invoked to transform the received reply data before it is returned to the caller.

rejectboolean<optional>
false

If set to true, non-zero ubus call status codes are treated as fatal error and lead to the rejection of the call promise. The default behaviour is to resolve with the call return code value instead.

Source

filterFn(data, args, …extraArgs) → {*}

The filter function is invoked to transform a received ubus RPC call reply before returning it to the caller.

Parameters:
NameTypeAttributesDescription
data*

The received ubus reply data or a subset of it as described in the expect option of the RPC call declaration. In case of remote call errors, data is numeric ubus error code instead.

argsArray.<*>

The arguments the RPC method has been invoked with.

extraArgs*<repeatable>

All extraneous arguments passed to the RPC method exceeding the number of arguments describes in the RPC call declaration.

Source
Returns:

The return value of the filter function will be returned to the caller of the RPC method as-is.

Type: 
*

invokeFn(…params) → {Promise.<*>}

The generated invocation function is returned by rpc.declare() and encapsulates a single RPC method call.

Calling this function will execute a remote ubus HTTP call request using the arguments passed to it as arguments and return a promise resolving to the received reply values.

Parameters:
NameTypeAttributesDescription
params*<repeatable>

The parameters to pass to the remote procedure call. The given positional arguments will be named to named RPC parameters according to the names specified in the params array of the method declaration.

Any additional parameters exceeding the amount of arguments in the params declaration are passed as private extra arguments to the declared filter function.

Source
Returns:

Returns a promise resolving to the result data of the remote ubus RPC method invocation, optionally substituted and filtered according to the expect and filter declarations.

Type: 
Promise.<*>

interceptorFn(msg, req) → {Promise.<*>|*}

Registered interceptor functions are invoked before the standard reply parsing and handling logic.

By returning rejected promises, interceptor functions can cause the invocation function to fail, regardless of the received reply.

Interceptors may also modify their message argument in-place to rewrite received replies before they're processed by the standard response handling code.

A common use case for such functions is to detect failing RPC replies due to expired authentication in order to trigger a new login.

Parameters:
NameTypeDescription
msg*

The unprocessed, JSON decoded remote RPC method call reply.

Since interceptors run before the standard parsing logic, the reply data is not verified for correctness or filtered according to expect and filter specifications in the declarations.

reqObject

The related request object which is an extended variant of the declaration object, allowing access to internals of the invocation function such as filter, expect or params values.

Source
Returns:

Interceptor functions may return a promise to defer response processing until some delayed work completed. Any values the returned promise resolves to are ignored.

When the returned promise rejects with an error, the invocation function will fail too, forwarding the error to the caller.

Type: 
Promise.<*> | *