Overview

This describes the mechanism used to sync preferences across devices/surfaces.

Structure / Terminology

• a pref: a simple name/value pair (the name could be namespaced if needed)
  • ex: "name": "john", "address.mailing.city": "san francisco"
• prefs: a set of prefs. Prefs will be kept as a hashmap, for instance:

{
	"name": "john", 
	"address.mailing.city": "san francisco",
}

• the prefs for a user are assembled as a combination of 3 prefs (assembled in this exact order):

  • system prefs (defined as constants at compile time). This simply has a the default remix_labs catalog.

    {
    	"search.libs": "# the main remix library\\nhttps://agt.remixlabs.com/ws/remix_labs"
    } 
    

  • default prefs (defined as a record for the workspace). An administrator can change this (dynamically).

  • user prefs (define as a record for a given user). A user can change his own prefs (dynamically)

  Each pref takes precedences over the previous value. This means that if the default prefs redefine a value defined in the system prefs, the value from the default prefs is returned. And the same goes for the user prefs.

  For instance, if you want to change the default catalogs for all users in the org, simply set search.libs in the default prefs. Each user will get these by default instead of the system one. And a given might also want to override this and define its own search.libs.

Agents

Interacting with the prefs is done via agents of the _rmx_prefs app, deployed in the main workspace of a user (the workpace of the user org)

• get_prefs : retrieves the prefs for the current user (a union of system + default + user prefs)
  • input: <nothing>
  • output:
    • prefs hashmap: the prefs for the user
• set_prefs: set the prefs for the current user
  • input:
    • prefs: hashmap: the prefs to merged with the existing user prefs
      • the prefs are merged, meaning you don’t need to pass the entire set of existing prefs every time you want to set one or two prefs (so if there was already 2 prefs name and address.mailing.city, passing an object with 2 new prefs address.mailing.zipcode and address.mailing.street will result in 4 prefs)
      • you can delete an existing pref by passing a value of null
  • output:
    • prefs: hashmap: the prefs for the current user after the changes (a union of system + default + user prefs)
• set_default_prefs : set the default prefs for the workspace (only an admin should have access to this agent). The input/output params are the same as set_prefs
  • note that because of the null rule, you can reset the default prefs to use the system prefs (say, the default catalog search.libs) by simply passing {"search.libs: null } . This will delete the override in the default prefs, which means you will get the value from the system prefs back…

Resources

• builder app: https://remix.remixlabs.com/e/edit/_rmx_prefs
• curl to fetch synced prefs for the current user (assuming a main server/workspace of https://agt.remixlabs.com/erzvkynof)

curl -H "Authorization: Bearer $REMIX_TOKEN" "<https://agt.remixlabs.com/run-agent/erzvkynof/_rmx_prefs/get_prefs>" -d '' | jq