Skip to content

Function broker

Info

At the moment, it is only possible to run functions that are hosted by yourself.

The function broker service enables different parties to provide and execute openOBD procedures (referred to as functions). These parties are:

  • function caller: the party who has started an openOBD session and makes a request to run a specific function.
  • function launcher: the party who receives the function caller's request and executes the requested function.

This makes it possible for a party to develop their own openOBD functions and host them for others to use.

Session transfer

In order for another party to execute a function on an openOBD session, the session needs to be transferred to them. It is not required for the party receiving the session to be a partner of Jifeline Networks or for them to have their own API credentials. Everything that is required to use the session is included in the transferred session itself.

As preparation for transferring an openOBD session, it is recommended to call startContext on the session. This will create a new environment in which the function launcher can execute the desired functionality, without having control over the entire session. After the function launcher has received the session (represented by a SessionInfo message) and has called authenticate on it, the desired functionality can be executed. The function caller can monitor the state of the procedure, and view any values that have been set in the context, by calling monitorContext. When the function launcher is done, it can call finish on the session. Because it is called inside a context, finish will close that context and return control to the function caller instead of closing the entire session. If desired, the function caller can then continue working with the session by calling authenticate, or close it by calling finish.

This process of creating, transferring and returning an openOBD session is visualized in the sequence diagram below.

sequenceDiagram
    title Transferring an openOBD session
    participant caller as Function caller
    box lightgray
    participant session as openOBD session
    end
    participant launcher as Function launcher

    %% Starting an openOBD session
    caller ->> session: startSessionOnTicket()
    Note over session: State: available
    activate session
    session -->> caller: SessionInfo

    %% Starting a new context
    caller ->> session: startContext()
    activate session
    session -->> caller: SessionContext

    %% Calling function
    caller -) launcher: SessionInfo and function to execute
    launcher ->> session: authenticate()
    Note over session: State: active
    session -->> launcher: SessionToken

    par Function execution
        loop Waiting for function to finish
            caller ->> session: monitorContext()
            session -->> caller: SessionContext
        end
    and
        Note over launcher, session: Executing function

        launcher ->> session: finish()
        Note over session: State: available
        session -->> launcher: ack
        deactivate session
    end

    opt Continue working with the session
        caller ->> session: authenticate()
        Note over session: State: active
        session -->> caller: SessionToken

        Note over caller, session: Running own code
    end

    caller ->> session: finish()
    Note over session: State: finished
    session -->> caller: ack
    deactivate session

Using the function broker

The function broker acts as a middleman to facilitate the transfer of sessions between parties for the purpose of running functions on them. Function launchers can register their functions to the function broker, which are then available for function callers to run.

The sequence diagram below shows a general overview of registering and calling a function using the function broker. In this diagram, the function launcher calls openFunctionStream to register two functions. The function caller then requests to run one of these functions. The function broker checks which function launcher (if any) provides the requested function, and then forwards the request to that launcher. After the function launcher indicates that the function has been started, this information is returned to the function caller, who can then wait until the function has finished.

sequenceDiagram
    title Function broker interaction
    participant launcher as Function launcher
    participant broker as Function broker
    participant caller as Function caller

    launcher -) broker: openFunctionStream()
    activate broker

    launcher ->> broker: FunctionRegistration A
    launcher ->> broker: FunctionRegistration B

    %% Set up the function caller
    caller ->> caller: Initialize session
    activate caller

    caller ->> broker: runFunction()
    broker ->> launcher: FunctionCall
    launcher ->> launcher: Launching the function
    activate launcher
    launcher -->> broker: FunctionUpdate ack
    broker -->> caller: FunctionUpdate ack

    Note over caller: Waiting for function to finish
    launcher -) caller: Function result
    deactivate launcher

    caller ->> caller: finish()
    deactivate caller

    launcher -->> broker: Close stream
    deactivate broker

Authentication

In order to use the function broker, a valid function broker token is required. A token can be requested by calling getFunctionBrokerToken and passing an Authenticate message that contains Partner API credentials. For subsequent calls to the function broker, this token will need to be added under the "authorization" header as a bearer token. Function broker tokens will expire after 5 minutes.

Generating function ID and signature

Before hosting an openOBD function, an ID must first be generated for the function by making a generateFunctionSignature call. This call returns a FunctionSignature message containing both a new function ID and a corresponding signature. This signature acts as proof that you are allowed to register that function ID, and can only be used by the partner who generated it. The function ID and signature do not expire, meaning you only need to call generateFunctionSignature once for each function.

Function stream

The function broker can be used to make openOBD functions you have written available to other parties. To do this, a stream will have to be created by calling openFunctionStream, on which a variety of messages can be exchanged with the broker. All of these messages are of the type FunctionUpdate, but can contain a variety of data. Each FunctionUpdate message also contains a type field to indicate if the message is a request or response.

Registering functions

For each function that you would like to make available, a FunctionRegistration request can be sent on the stream to indicate that the function is online and can be called. A FunctionRegistration response will then be returned by the function broker to indicate that the function registration was successful. Registered functions will remain online until they are explicitly set as offline, or until the stream is closed. A function can only be registered to a single stream at any given time. Therefore, if the same function is registered by a different stream, the original stream will receive a FunctionRegistration response indicating that the function is now offline for that stream.

Note

A stream stays open as long as at least one function is registered as active. If none of the functions are active for 10 minutes, the broker will close the stream.

Handling function calls

When the broker receives a request to run a function, it forwards the corresponding FunctionCall request to the stream that registered that function. The function launcher must then return a FunctionCall response indicating whether the function was started successfully or if it could not be run. This information can be set in the response and response_description fields of the FunctionUpdate message.

Note

A FunctionCall request expires after 5 seconds and must be responded to within that time.

Token refreshing

Every 2 minutes the function broker sends a request message containing a new FunctionBrokerToken. These messages also act as a heartbeat, ensuring that the stream remains active. Therefore, the function launcher should send the FunctionBrokerToken back as a response. Any FunctionBrokerToken responses received by the broker are ignored, and therefore only function to keep the stream active.

Function broker reconnect

When the function broker needs to shut down, it sends a FunctionBrokerReconnect request. This requests specifies after how many seconds (generally 60) the function broker will shut down and close all streams. The function launcher should then reconnect to the broker by starting a new stream and re-registering all functions.

Running a function

To run an openOBD function, a session will first have to be started. The session needs to be in the available state in order to run a function, so authenticate should not be called. Before running a function, it is recommended to start a context (see Session transfer). A function can then be run by calling runFunction and passing a FunctionCall message, which specifies the ID of the function and the session on which to run it. When the function has started, monitorContext can be called to check if the requested function has finished and what its result is. The monitorContext call requires the monitor_token to be added as a bearer token to the header of the call. This monitor_token is returned when starting a context.