feat(windows): Online Update - Background Download - Stage 1 💽

[rc-swag]

Keyman for Windows online updates - Background Download- Stage1

Table of Contents

1. Introduction
2. Detail

Introduction

The ideal end goal of the online updated work is to automate the updated process with zero user interaction.
There are many obstacles to achieving this some of which are out of Keyman control.
However, we can make steps towards this goal.
This issue is for stage 1 in which will download the update in the background without user interaction. There will still
be the need for the user to start the installation either via the configuration dialogue or pop on a Windows restart.
Stage two #8993 will introduce a schedule task to start the installation after downloads which will further reduce the user interaction.

Challenges

Updating Keyman for Windows currently has the following issues which will still require some level of user interaction

• Elevation - installing keyboards and Keyman both require elevation
• Files in use - updating Keyman files often requires a restart (we can’t avoid).
  - Keyman32.dll will be locked with SetWindowsHookEx hooks – with no clean way of releasing it from memory in all processes
  - kmtip.dll can be locked as it is selected as an input method

Detail

1. Automatic updates:

   1. Keyman Configuration dialog will show a panel in the updates tab detailing what the next updates will be.
      Title for whole tab shall be "Online Update"
      For example:

          1.  " New versions of the following components are available and will be applied next time Windows is restarted / No new versions currently available"
          
          2.  Keyman for Windows 18.0.222 [Release Notes]
          
          3.  SIL Euro Latin Keyboard 2.1 [Release Notes]
          
          4.  [Install now] button
          
          5.  [Turn on/off automatic updates] button (here and in Options tab)
          
          6.  Includes a [Check for updates] button
          
          7.  "There are no new versions currently available" see (i)
          
          8.  Icon for Update on the left hand side - which is a different colour/or number of updates available (standard notification pattern) 
          
          9.  Have a grid view for keyboards with columns of current version -> new version.
      

2. The checking for updates will be done automatically (via a schedule). More detail in Functional Spec.

3. We still have a 'manual update' pathway with auto updates off. It will be through a button on the Configuration tab for "Online Updates"

4. stretch task Remove “Keep in Touch” from the left and add the information to “Support” also could add a get involved link stretch task

This is mage was quick hack to show the general layout for the update tab.

Functional Spec

• Handling Checking for and downloading updates

  1. For stage one check for updates shall be done when Configuration or Keyman starts and it has been 7 days since the last check. (after first install wait 7 days)
  2. Automatic check for updates – checks online for an update, and downloads it to a cache.
  3. A user can trigger the same check and download via check for updates button in Keyman Configuration Menu. This will only check for updates and not trigger a background download of the install files. When the user press Apply now the download process will start if the automatic download has not already happened.
  4. A separate process Downloads metadata + binaries and puts them in a cache folder (e.g. Current user AppData\local\Keyman\Updates) without a GUI. The download of the actual install files is also under the current user profile and not an elevated process. A stretch goal is to write its download status to a location that can be used by a separate process to provide a GUI status.
  5. When an automatic download has completed Keyman Configuration will show a banner "Update Available" the next time it is loaded.
  6. Stretch Task Keyman.exe could also could check if file exists when user opens Keyman menu and add a banner the Keyman Menu (task bar).
  7. Keyman Configuration reads the metadata file. (Don't forget about file lock/share conflicts on either side here!)

• Installing the update

  1. When Keyman is starting for the first time in a Windows session and an update is waiting to install, a GUI pop shall notify the user "Install Update" with Yes, Remind me later Buttons.
     Then when they are asked about elevated permissions they are not surprised. (This is especially the case when Keyman is starting with Windows)

  2. Manually started eg clicking the Apply Now button from the Configuration Menu. t

     1. since manually started, at user-level, shutdown Keyman, Keyman Config, to minimize file locks – but we understand that a reboot may still be required - we can’t do anything about this.
     2. Set the background Update State Flag usInstalling
     3. First install keyboard updates
        5 Install updates with the bootstrap executable
     4. Immediately after triggering the Windows Installer, Keyman, Keyman Configuration shutdown – to avoid locking files.

  3. The bootstrap installer, at the end of Install, sets the buState Flag to Idle

  4. Keyman itself (and Keyman Configuration) must check on startup for the state flag for usInstalling, and immediately exit if so to avoid file lock issues, and interfering with installation)

  5. Extra error. If the state flag is Installing after multiple call to kmshell, present UX to the user to allow them to clear the flag, in the case of a failed install:

     1. For the starting Keyman from Start Menu, or starting Keyman Configuration
     2. If install fails in either scenario we don’t want to leave keyman in a broken state. I suggest the we roll back to the previously installed version. To know it fails we may be in the installing state so need have count to count how many times we have been triggered while still in this state. If greater then the threashold move to the usFailed state and handle clean up.

  6. For all other States other than Installing, starting kmshell will run, for example -h, -k etc.

  7. To investigate: what happens when a TIP is selected – is it possible for the TIP to say "NO DON'T ACTIVATE!" Answer: no it is not. In this case, reboots maybe required.
     10.

This is a link to the State Transition Matrix in a spreadsheet that shows the different state the update process can be in. The rows show the only events that can be applied to the "state". This matrix makes it very clear what action will take place for any given event, and the only permitted paths to transition from one state to the next.
This mermaid diagram has also been added to the code base.

stateDiagram
    [*] --> Idle
    Idle --> UpdateAvailable
    UpdateAvailable --> Downloading
    Downloading --> Installing
    Downloading --> Pending
    Pending --> Installing
    Installing --> WaitingPostInstall
    WaitingPostInstall --> Idle

Loading

Issues and Todo Items

• feat(windows): Refactor OnlineUpdateCheck to remove UI coupling 💽 #10119
  • Remove all UI calls from it and use callbacks
  • Keep parsing separate
  • Consider merging TOnlineUpdateCheckParams and TUpdateCheckResponse
  • Figure out how SPackageUpgradeFilename is used for upgrading packages and how it fits into the new check/download, with later install model
  • Implement background download of updates into cache
• feat(windows): Add state machine to control the check, download and installation. 💽 #10210
  • on first-run-in-session
    • Add atom check for first-run-in-session app startup
  • Implement installation of updates from cache
  • This should be handled as part of this work bug(windows): represent current status to the user checking or downloading updates #4544
  • feat(windows): add install packages to the update state machine 💽 #12794 Update Keyboards.

Manual update process

• feat(windows): add toast interstitial install updates now 💽 #10348
  • Add toast interstitial for installing updates on app startup feat(windows): toast interstitial install now💽 #12353
  • Make sure 'automatic check for updates' option is honoured. In this case updates are downloaded in the background. feat(windows): automatic updates option 💽 #12375
  • "Check for Updates" button only checks without downloading updates for the manual update process. Then when the user selects Apply Now download the updates and install.
    .
• feat(windows): Update Tab for Keyman Configuration as per functional spec 💽 #10045
  • feat(windows): Banner in menu of the Update Tab for Keyman Configuration 💽 #10117
• Make download non UI bound a separate process, including the check for updates. Maybe part of feat(windows): Online Update check stream update data 💽 #10042
• chore(windows): Remove old Update tasktray icon, old OnlineUpdate dialog 💽 #10363
• feat(windows): investigate can removing the proxy settings altogether and rely on Windows settings 💽 #10234
  figure out when the updates are downloaded

PRs

• feat(windows): background update state machine 📲 #10032 - This will be cherry picked into a new branch

Related PRs

• bug(windows): Downgrading without restart can cause apps to crash with exception in keyman32.dll/keyman64.dll #7749
• bug(windows): represent current status to the user checking or downloading updates #4544

[Meng-Heng]

Hello, this is a feedback from the community site. I will leave it here. Thank you.

Original post: https://community.software.sil.org/t/keyboard-optimization-mobile-versions/9422/24

I had to uninstall and reinstall the keyboard twice but now it’s working.
None of my colleagues seem to have received the update automatically though, neither on phone nor on their computer.