Messenger API Wrappers

Relevant source files

The following files were used as context for generating this wiki page:

• src/thunderbird/messenger/alarms.ts
• src/thunderbird/messenger/i18n.ts
• src/thunderbird/messenger/scripting.ts
• src/thunderbird/messenger/global.ts
• doc/design.md
• doc/faq-architectural.md
• src/test/startup.test.ts

The Messenger API wrappers are a crucial architectural component within Ghostbird, located in the src/thunderbird/ directory. Their primary purpose is to create an abstraction layer over the native Thunderbird MailExtension API (globalThis.messenger). This isolates the core application logic from direct dependencies on the Thunderbird platform, which is a key strategy for improving testability, maintainability, and resilience against breaking changes in the Thunderbird API.

This design adheres to the Dependency Inversion Principle. Instead of high-level modules depending on low-level platform APIs, both depend on abstractions. The core logic defines its required functionalities as interfaces (typically in api.ts files), and the src/thunderbird/ modules provide concrete implementations of these interfaces by calling the actual messenger API. This approach allows for easy mocking of dependencies during unit and integration testing.

Sources: doc/design.md:74-89, doc/faq-architectural.md:30-36

Architecture and Dependency Flow

The src/thunderbird/ modules serve as the "Adapters" in a Ports and Adapters architecture. They connect the application's core logic to the external Thunderbird environment.

The general dependency flow is as follows:

1. Application modules (e.g., in app-background/, app-compose/) define their external dependencies as TypeScript interfaces in local api.ts files.
2. These application modules use the interfaces, remaining completely unaware of the Thunderbird messenger object.
3. The wrapper classes within src/thunderbird/ implement these interfaces.
4. The implementations within the wrapper classes are the only parts of the application (besides the root entry points) that directly interact with the globalThis.messenger API.

This diagram illustrates the dependency inversion, where app-* modules do not depend directly on thunderbird modules.

Instantiation

Classes within the src/thunderbird/ directory are instantiated as part of the application's startup process. This process uses a custom dependency injection mechanism that scans for classes with a static isSingleton property. The startup*() functions in src/root/startup/ resolve and inject dependencies automatically. This ensures that a single, shared instance of a wrapper (if isSingleton: true) is available to all dependent components.

Sources: doc/design.md:138-158, doc/faq-architectural.md:5-7, src/test/startup.test.ts:28-36

Key Wrapper Components

The wrappers are organized by the part of the messenger API they abstract.

Global Messenger Access

The MessengerGlobal class provides a singleton instance of the root messenger object, making it available for dependency injection into other wrappers.

Class	File	Description
MessengerGlobal	src/thunderbird/messenger/global.ts	Holds a reference to globalThis.messenger and is injected into other messenger wrappers.

Sources: src/thunderbird/messenger/global.ts

Alarms Wrapper

The MessengerAlarms class wraps the messenger.alarms API, which is used for scheduling code to run at a specific time in the future. This is used by Ghostbird to prevent the background script from being suspended by Thunderbird.

Class	File	Implements	Description
MessengerAlarms	src/thunderbird/messenger/alarms.ts	IAlarms	Provides methods to create, clear, and manage alarms.

Methods:

• create(name: string, alarmInfo: messenger.alarms.AlarmCreateInfo): void
• clear(name: string): Promise<boolean>
• clearAll(): Promise<boolean>
• get(name: string): Promise<messenger.alarms.Alarm | undefined>
• getAll(): Promise<messenger.alarms.Alarm[]>

Sources: src/thunderbird/messenger/alarms.ts, manifest_template.json:20

Internationalization (i18n) Wrapper

The MessengerI18n class wraps the messenger.i18n API to provide access to localized strings from the _locales/ directory.

Class	File	Implements	Description
MessengerI18n	src/thunderbird/messenger/i18n.ts	II18n	Provides a method to retrieve translated messages.

Methods:

• getMessage(messageName: string, substitutions?: string | string[]): string

Sources: src/thunderbird/messenger/i18n.ts

Scripting Wrapper

The MessengerScripting class wraps the messenger.scripting API, which is used to inject and manage content scripts in tabs. This is fundamental to Ghostbird's operation, as it's how compose.js gets injected into the mail compose window.

Class	File	Implements	Description
MessengerScripting	src/thunderbird/messenger/scripting.ts	IScripting	Provides methods to register and unregister content scripts.

Methods:

• registerContentScripts(scripts: messenger.scripting.RegisteredContentScript[]): Promise<void>
• getRegisteredContentScripts(filter?: messenger.scripting.ContentScriptFilter): Promise<messenger.scripting.RegisteredContentScript[]>
• unregisterContentScripts(filter?: messenger.scripting.ContentScriptFilter): Promise<void>

The following sequence diagram shows how the scripting wrapper is used to inject the compose script.

Testing and Mocking

The primary benefit of this wrapper architecture is enhanced testability. During tests, concrete wrapper implementations from src/thunderbird/ are replaced with mock objects that implement the same interfaces. This allows for testing the application's logic in isolation without needing a running Thunderbird instance.

The src/test/startup.test.ts file includes a test that verifies all dependencies, including these wrappers, can be instantiated correctly by the dependency injection system. It creates a dummy messenger object to satisfy the dependencies of the wrappers under test.

// From src/test/startup.test.ts
function makeDummyMessenger(): Record<string, symbol> {
  const namespaces = ["runtime", "tabs", "commands", "composeAction", "scripting"] as const

  return Object.fromEntries(namespaces.map((name) => [name, Symbol(`dummy messenger.${name}`)]))
}

Sources: src/test/startup.test.ts:68-74

This demonstrates how the real messenger API can be easily swapped out, validating the effectiveness of the wrapper design.

Sources: doc/testing.md:12-14, src/test/startup.test.ts:28-36