Hello World!¶

In the first chapter of our tutorial series, we will instantiate the skeleton app in developer mode.

Requirements¶

Before starting, make sure to register for Sobamail, download and install the client and login to your account using the native desktop client.

Though not strictly needed, you may want to be able to manipulate SQLite databases. So either:

• Download the official CLI tool from sqlite.org
• Use the CLI tool provided by your operating system,
• Use a GUI tool like DB Browser for SQLite.

Sobamail Applications¶

To reiterate from the concepts section, Sobamail applications, just like regular web applications, are split into two main components that work together:

• A Mutator module that handles all business logic and state changes,
• A user interface that handles all user interaction. It's a regular frontend application.

Apps need to be instantiated before they can be used. Once deployed, Sobamail applications are immutable, which would normally make app development quite impractical. That's why Sobamail platform has two deployment modes for applications: Developer mode and production mode.

Mutations generated by an app in developer mode are not replicated since it's impossible to guarantee convergence.

We will start by instantiating the Sobamail app skeleton in developer mode.

The Application Manager¶

Each Mailbox replica has its own local app manager called Application Manager. It can be used to instantiate apps in developer mode. To do this:

• Launch Sobamail
• In the folders widget, expand the Apps folder.

This folder contains the list of instantiated mailbox-wide Applications. - Find and expand the Application Manager folder. You should see a single entry with a garbled text label. That's the application instance id of your Application Manager app of your mailbox. Click it to launch the Application Manager GUI. - Click the "Instantiate In Dev Mode" button. - Enter your desired app id and app name. Do note that, once published, it's not possible to change the app id of a Sobamail application. - Click "Submit" to instantiate your app.

The Anatomy of a Sobamail App¶

Now you should see your new app instance in the apps folder, under your given app name. Click its instance id to launch the app UI.

Follow on-screen instructions to locate the develroot.

Let's have a detailed look at the mutator module of the starter app before delving into implementation details:

import "soba://computer/R2"; // (1)

import { // (2)
    DeleteRow,
} from "https://sobamail.com/module/base/v1?sha224=lHPRerLbiqHkAShgnv6sjCjr_ReFSXlDJTe6Ew";

export default class Mutator { // (3)
    static id = "tutorial1.alice.app.user.example.com"; // (4)
    static name = "Application Tutorial"; // (5)
    static version = "1.0.0.0"; // (6)
    static objects = new Map([ // (7)
        [ DeleteRow.KEY, false ],
    ]);

    constructor() { // (8)
        // TODO: Create the database schema
        // TODO: Perform any sanity checks
    }

    process(message, metadata) { // (9)
        // TODO: Implement the app logic
    }
}

1. Sobamail runtime is versioned to help with convergeance on all replicas. First thing to do is to choose a computer release to run your application. There is currently only one computer to choose: Replicated-2. It can be chosen by importing the magic "soba://computer/R2" module.

2. For the same reason, all modules use hash values in import statements to guarantee that the same code is run in all replicas from the root module down to the last leaf in the import tree. See Imports for more information.

   You can find the latest hash values in the sobamail/base repository:

   Some examples:

   • https://sobamail.com/module/base/v1
   • https://sobamail.com/module/mailboxmanager/v1

   You can use standard tools to compute hash values of the source code text of the modules that you write. The URL format accepts urlsafe base64, base32hex and hexadecimal encodings of digest values. Currently, only SHA224 is supported. We use the gen-hash.py script to keep our digest values up-to-date.

3. All root modules must contain a default exported class.

4. The default class must have a static id variable of type String.

5. The default class must have a static name variable of type String.

6. The default class must have a static version variable of type String.

7. The default class must have a static objects variable of type Map<String, Boolean>. Since an app that doesn't react to any object at all would not be useful, the Map object can not be empty.

   • The map key is a string of format "{Namespace}Name". See Events for details.

   • The map value is a boolean whose value must be false.

8. In Sobamail, events get processed in two stages: First, The Mutator class is instantiated by the JS runtime. This runs the constructor where the user defines the app schema and performs various sanity checks. The constructor must throw an Error instance if the application environment can not be validated.

9. After the runtime obtains a fresh Mutator instance, it invokes the process method with two arguments:

   • message: The message object that triggered the event
   • metadata: Contains metadata about the processing environment and the provenance of the event at hand.

   If the process() method doesn't throw, the event is considered to be processed sucessfully.

   The return value of the process() method is discarded.

Inspecting the Frontend¶

Since Sobamail uses Chromium under the hood, you can use the Inspect tool from the Chromium project to connect to it.

To do this, launch Chromium and navigate to chrome://inspect and then click "Devices"

ou should a screen similar to this:

Click the "Configure" button next to the "Discover network targets" checkbox:

.. and enter the the localhost:50134 (50134 for SOBA) address.

Now you should see the tabs open in Sobamail. Find the tab for our application and click "inspect".

Now you can use the good old Chromium debugger to inspect Sobamail frontend apps.

Implementation¶

From here on you may want to follow tutorials on different types of applications.

The counter tutorial demonstrates a collaborative web application with an increment-only counter.

The responder tutorial shows email-based process automation capabilities of the Sobamail platform by implementing a vacation auto-responder.