Web Locks API

1. Introduction

This section is non-normative.

A lock request is made by script for a particular resource name and mode. A scheduling algorithm looks at the state of current and previous requests, and eventually grants a lock request. A lock is a granted request; it has a resource name and mode. It is represented as an object returned to script. As long as the lock is held it may prevent other lock requests from being granted (depending on the name and mode). A lock can be released by script, at which point it may allow other lock requests to be granted.

The API provides optional functionality that may be used as needed, including:

• returning values from the asynchronous task,

• shared and exclusive lock modes,

• conditional acquisition,

• diagnostics to query the state of locks, and

• an escape hatch to protect against deadlocks.

Cooperative coordination takes place within the scope of agents sharing a storage bucket; this may span multiple agent clusters.

NOTE: Agents roughly correspond to windows (tabs), iframes, and workers. Agent clusters correspond to independent processes in some user agent implementations.

1.1. Usage Overview

The API is used as follows:

1. The lock is requested.

2. Work is done while holding the lock in an asynchronous task.

3. The lock is automatically released when the task completes.

navigator.locks.request('my_resource', async lock => {
   // The lock has been acquired.
   await do_something();
   await do_something_else();
   // Now the lock will be released.
});

// Before requesting the lock.
await navigator.locks.request('my_resource', async lock => {
   // The lock has been acquired.
   await do_something();
   // Now the lock will be released.
});
// After the lock has been released

1.2. Motivating Use Cases

A web-based document editor stores state in memory for fast access and persists changes (as a series of records) to a storage API such as the Indexed Database API for resiliency and offline use, and to a server for cross-device use. When the same document is opened for editing in two tabs the work must be coordinated across tabs, such as allowing only one tab to make changes to or synchronize the document at a time. This requires the tabs to coordinate on which will be actively making changes (and synchronizing the in-memory state with the storage API), knowing when the active tab goes away (navigated, closed, crashed) so that another tab can become active.

In a data synchronization service, a "primary tab" is designated. This tab is the only one that should be performing some operations (e.g. network sync, cleaning up queued data, etc). It holds a lock and never releases it. Other tabs can attempt to acquire the lock, and such attempts will be queued. If the "primary tab" crashes or is closed then one of the other tabs will get the lock and become the new primary.

The Indexed Database API defines a transaction model allowing shared read and exclusive write access across multiple named storage partitions within an origin. Exposing this concept as a primitive allows any Web Platform activity to be scheduled based on resource availability, for example allowing transactions to be composed for other storage types (such as Caches [Service-Workers]), across storage types, even across non-storage APIs (e.g. network fetches).

2. Concepts

For the purposes of this specification:

• Separate user profiles within a browser are considered separate user agents.

• Every private mode browsing session is considered a separate user agent.

A user agent has a lock task queue which is the result of starting a new parallel queue.

The task source for steps enqueued below is the web locks tasks source.

2.1. Resources Names

A resource name is a JavaScript string chosen by the web application to represent an abstract resource.

A resource name has no external meaning beyond the scheduling algorithm, but is global across agents sharing a storage bucket. Web applications are free to use any resource naming scheme.

encodeURIComponent(db_name) + '/' + encodeURIComponent(store_name)

Resource names starting with U+002D HYPHEN-MINUS (-) are reserved; requesting these will cause an exception.

2.2. Lock Managers

A lock manager encapsulates the state of locks and lock requests. Each storage bucket includes one lock manager through an associated storage bottle for the Web Locks API.

NOTE: Pages and workers (agents) sharing a storage bucket opened in the same user agent share a lock manager even if they are in unrelated browsing contexts.

Refine the integration with [Storage] here, including how to get the lock manager properly from the given environment.

2.3. Modes and Scheduling

A mode is either "exclusive" or "shared". Modes can be used to model the common readers-writer lock pattern. If an "exclusive" lock is held, then no other locks with that name can be granted. If a "shared" lock is held, other "shared" locks with that name can be granted — but not any "exclusive" locks. The default mode in the API is "exclusive".

Additional properties may influence scheduling, such as timeouts, fairness, and so on.

2.4. Locks

A lock represents exclusive access to a shared resource.

const p1 = navigator.locks.request('resource', lock => {
  const p2 = new Promise(r => {
    // Logic to use lock and resolve promise...
  });
  return p2;
});

const p1 = navigator.locks.request('resource', async lock => {
  // Logic to use lock...
});

2.5. Lock Requests

A lock request represents a pending request for a lock.

A lock request queue is a queue of lock requests.

Each lock manager has a lock request queue map, which is a map of resource names to lock request queues.

2.6. Termination of Locks

Whenever the unloading document cleanup steps run with a document, terminate remaining locks and requests with its agent.

When an agent terminates, terminate remaining locks and requests with the agent.

This is currently only for workers and is vaguely defined, since there is no normative way to run steps on worker termination.

3. API

3.1. Navigator Mixins

[SecureContext]
interface mixin NavigatorLocks {
  readonly attribute LockManager locks;
};
Navigator includes NavigatorLocks;
WorkerNavigator includes NavigatorLocks;

Each environment settings object has a LockManager object.

The locks getter’s steps are to return this's relevant settings object's LockManager object.

3.2. LockManager class

[SecureContext, Exposed=(Window,Worker)]
interface LockManager {
  Promise<any> request(DOMString name,
                       LockGrantedCallback callback);
  Promise<any> request(DOMString name,
                       LockOptions options,
                       LockGrantedCallback callback);

  Promise<LockManagerSnapshot> query();
};

callback LockGrantedCallback = Promise<any> (Lock? lock);

enum LockMode { "shared", "exclusive" };

dictionary LockOptions {
  LockMode mode = "exclusive";
  boolean ifAvailable = false;
  boolean steal = false;
  AbortSignal signal;
};

dictionary LockManagerSnapshot {
  sequence<LockInfo> held;
  sequence<LockInfo> pending;
};

dictionary LockInfo {
  DOMString name;
  LockMode mode;
  DOMString clientId;
};

A LockManager instance allows script to make lock requests and query the state of the lock manager.

3.2.1. The request() method

try {
  const result = await navigator.locks.request('resource', async lock => {
    // The lock is held here.
    await do_something();
    await do_something_else();
    return "ok";
    // The lock will be released now.
  });
  // |result| has the return value of the callback.
} catch (ex) {
  // if the callback threw, it will be caught here.
}

await navigator.locks.request('resource', {mode: 'shared'}, async lock => {
  // Lock is held here. Other contexts might also hold the lock in shared mode,
  // but no other contexts will hold the lock in exclusive mode.
});

await navigator.locks.request('resource', {ifAvailable: true}, async lock => {
  if (!lock) {
    // Didn’t get it. Maybe take appropriate action.
    return;
  }
  // Lock is held here.
});

const controller = new AbortController();
setTimeout(() => controller.abort(), 200); // Wait at most 200ms.

try {
  await navigator.locks.request(
    'resource', {signal: controller.signal}, async lock => {
      // Lock is held here.
  });
  // Done with lock here.
} catch (ex) {
  // |ex| will be a DOMException with error name "AbortError" if timer fired.
}

3.2.2. The query() method

{
  held: [
    { name: "resource1", mode: "exclusive",
      clientId: "8b1e730c-7405-47db-9265-6ee7c73ac153" },
    { name: "resource2", mode: "shared",
      clientId: "8b1e730c-7405-47db-9265-6ee7c73ac153" },
    { name: "resource2", mode: "shared",
      clientId: "fad203a5-1f31-472b-a7f7-a3236a1f6d3b" },
  ],
  pending: [
    { name: "resource1", mode: "exclusive",
      clientId: "fad203a5-1f31-472b-a7f7-a3236a1f6d3b" },
    { name: "resource1", mode: "exclusive",
      clientId: "d341a5d0-1d8d-4224-be10-704d1ef92a15" },
  ]
}

3.3. Lock class

[SecureContext, Exposed=(Window,Worker)]
interface Lock {
  readonly attribute DOMString name;
  readonly attribute LockMode mode;
};

A Lock object has an associated lock.

The name getter’s steps are to return the associated lock's name.

The mode getter’s steps are to return the associated lock's mode.

4. Algorithms

4.1. Request a lock

4.2. Release a lock

4.3. Abort a request

4.4. Process a lock request queue for a given resource name

4.5. Snapshot the lock state

5. Usage Considerations

This section is non-normative.

5.1. Deadlocks

Deadlocks are a concept in concurrent computing, and deadlocks scoped to a particular lock manager can be introduced by this API.

navigator.locks.request('A', async a => {
  await navigator.locks.request('B', async b => {
    // do stuff with A and B
  });
});

navigator.locks.request('B', async b => {
  await navigator.locks.request('A', async a => {
    // do stuff with A and B
  });
});

Preventing deadlocks requires care. One approach is to always acquire multiple locks in a strict order.

async function requestMultiple(resources, callback) {
  const sortedResources = [...resources];
  sortedResources.sort(); // Always request in the same order.

  async function requestNext(locks) {
    return await navigator.locks.request(sortedResources.shift(), async lock => {
      // Now holding this lock, plus all previously requested locks.
      locks.push(lock);

      // Recursively request the next lock in order if needed.
      if (sortedResources.length > 0)
        return await requestNext(locks);

      // Otherwise, run the callback.
      return await callback(locks);

      // All locks will be released when the callback returns (or throws).
    });
  }
  return await requestNext([]);
}

6. Security and Privacy Considerations

6.1. Lock Scope

The definition of a lock manager's scope is important as it defines a privacy boundary. Locks can be used as an ephemeral state retention mechanism and, like storage APIs, can be used as a communication mechanism, and must be no more privileged than storage facilities. User agents that impose finer granularity on one of these services must impose it on others; for example, a user agent that exposes different storage partitions to a top-level page (first-party) and a cross-origin iframe (third-party) in the same origin for privacy reasons must similarly partition locking.

This also provides reasonable expectations for web application authors; if a lock is acquired over a storage resource, all same-origin browsing contexts must observe the same state.

6.2. Private Browsing

Every private mode browsing session is considered a separate user agent for the purposes of this API. That is, locks requested/held outside such a session have no affect on requested/held inside such a session, and vice versa. This prevents a website from determining that a session is "incognito" while also not allowing a communication mechanism between such sessions.

6.3. Implementation Risks

Implementations must ensure that locks do not span origins. Failure to do so would provide a side-channel for communication between script running in two origins, or allow one script in one origin to disrupt the behavior of another (e.g. denying service).

6.4. Checklist

The W3C TAG has developed a Self-Review Questionnaire: Security and Privacy for editors of specifications to informatively answer. Revisiting the questions here:

• The specification does not deal with personally identifiable information, or high-value data.

• No new state for an origin that persists across browsing sessions is introduced.

• No new persistent, cross-origin state is exposed to the web.

• No new data is exposed to an origin that it doesn’t currently have access to (e.g. via polling [IndexedDB-2].)

• No new script execution/loading mechanisms are enabled.

• This specification does not allow an origin access to any of the following:

  • The user’s location.

  • Sensors on a user’s device.

  • Aspects of a user’s local computing environment.

  • Access to other devices.

  • Any measure of control over a user agent’s native UI.

• No temporary identifiers to the web are exposed to the web. All resource names are provided by the web application itself.

• Behavior in first-party and third-party contexts is distinguished in a user agent if storage is distinguished. See § 6.1 Lock Scope.

• Behavior in the context of a user agent’s "incognito" mode is described in § 6.2 Private Browsing.

• No data is persisted to a user’s local device by this API.

• This API does not allow downgrading default security characteristics.

7. Acknowledgements

Many thanks to Alex Russell, Andreas Butler, Anne van Kesteren, Boris Zbarsky, Chris Messina, Darin Fisher, Domenic Denicola, Gus Caplan, Harald Alvestrand, Jake Archibald, Kagami Sascha Rosylight, L. David Baron, Luciano Pacheco, Marcos Caceres, Ralph Chelala, Raymond Toy, Ryan Fioravanti, and Victor Costan for helping craft this proposal.

Special thanks to Tab Atkins, Jr. for creating and maintaining Bikeshed, the specification authoring tool used to create this document, and for his general authoring advice.