Skip to content

The cordova simulate bootstrap protocol

Jump to bottom
Arzhan "kai" Kinzhalin edited this page May 20, 2016 · 1 revision

The problem

Today the cordova application lifecycle and the process of launching taco-simulate (the server and the browsers) are decoupled from one another. It specifically means that 'deviceReady' may be fired on the app-host before app-host and sim-host are connected and capable of exchanging plugin messages.

Abbreviations

  • SRV -- server, both HTTP and WS/socket.io

  • SIM -- sim-host, a client which holds the plugins state and UI to manipulate them. Simulates "native" part of cordova.

  • APP -- app-host, a client which runs the application and provides cordova environment.

The solution

The basic idea behind the proposal is very simple: ensure that both app-host and sim-host are ready before firing 'deviceReady' on the app-host. However, a couple of additional usecases should be taken into account:

  1. Potentially, single SIM could have multiple APP connected. Since the SIM is where the 'device state' resides, the opposite case -- multiple SIM per single APP -- is not realistic, IMO, and unnecessarily complex. The protocol should contemplate single SIM/multiple APP scenario.

  2. Currently, taco-simulate launches both APP and SIM (and the SRV) at about the same time. However, for us, in XDK, it is a requirement, that APP could be launched at any time after the SIM is started. A SIM restart while APP is running is also a reasonable scenario. In general, it should be taken into account that any of the participating parties (APP and SIM) may go online or offline.

  3. Not a hard requirement, but rather a useful "feature" of the bootstrap protocol would be "plugin support status". Currently, the list of plugins that the application loads in runtime is not known to the SIM (it just loads plugins that are installed by the app and for which simulation is supported). If it was known, then SIM could display a "plugin status" of the connected APP.

So, with these in mind, here is the proposal.

  1. Launch

    The sequence of launching the server (SRV), the sim-host (SIM), and the app-host (APP) is recommended to be the following: first the SRV is launched, then the SIM and the APP (order must not matter for the latter two).

    However, the system should be resilient to any order of launching, given it happens within a reasonable period of time.

  2. Initial connection

    The flow is on the digram below. Important notes:

    a) APP could connect to SRV at any time, but it will not be sent init until a SIM is connected and ready;

    b) After (init) message is sent to APP, SRV no longer performs any active role, it just passes the messages from APP to SIM and the other way around.

    c) The deviceReady event is not fired on the client until start message is sent by SIM to APP. Note that the start message plays the same role as the channel.onNativeReady event.

          SIM                   SRV                   APP
       |     (connect)       |                     |
       |-------------------->+                     |
       |       (init)        +                     |
       +<--------------------+                     |
       +                     |     (connect)       |
       +                     *<--------------------|
       +      (ready)        |                     |
       +-------------------->o                     |
       |                     |      (init)         |
       |                     *-------------------->+
       |                    (x)                    +
       |                                           +
       |            (plugin list)                  +
       +<----------------------------------------- +
       +             (start)                       |
       +------------------------------------------>+
       |                                           +
       |                                           +
       |                                          (x)<--- deviceReady
       |                                           |

  3. SRV restart

    The server plays crucial part and maintains the communication channel between SIM and APP. If it goes offline, SIM and APP become unusable. They should display "offline" message and/or disable interaction with their UI.

  4. SIM restart

    The SIM holds the state of the "virtual device". It's not guaranteed that after the restart the SIM will have the same state as it had right before the restart. A correct implementation would require restart (reload) of the APP once SIM disconnects from the SRV (going offline permanently or just restarting). Once APP will restart, the initial connection protocol kicks in ensuring APP will not initialize until a SIM host is connected.

  5. APP restart

    APP can be restarted (reloaded) at any given point in time. SRV should clean up any bookkeeping data corresponding to the APP and let SIM know an APP has disconnected. Reconnecting is taken care of by the initial connection protocol.

  6. Supporting multiple APP

    In order to support multiple APP per single SIM, the protocol needs to assign a random token to each APP connected to SRV to route them properly. SIM may keep the track of the APPs connected in order, for example, to visualize their information and status.

  7. Multiple SIM

    Multiple SIM at the same time are not supported. In case another SIM is connected, in addition to already existing one, either of the following two scenarios may happen:

    a) The new SIM connection is closed. It is the responsibility of the SIM to handle such behavior (i.e. disable the UI or otherwise indicate the error condition visually);

    b) The existing SIM is disconnected and the new one is registered. This scenario is similar to the behavious described in 3. SIM restart above.

    The implementation may chose which scenario to follow based on a configuration or a runtime option.

Clone this wiki locally