nexo/docs/linux-notification-test-guide.md

Linux Notification Test Guide

Last verified: 2026-06-02

This guide fixes the preflight contract for Linux notification work before a Linux test machine, distribution, desktop environment, notification daemon, or real OS notification UI evidence is available.

Do not commit private host values, device tokens, auth tokens, signing keys, runtime endpoints, user names, channel names, desktop session details that identify a private machine, or private package repository values into tracked docs. Use placeholders in examples and keep credential files in approved local or secret-store locations.

Current Repository State

• packages/messaging_flutter/pubspec.yaml does not currently register a Linux plugin platform.
• There is no packages/messaging_flutter/linux/ plugin scaffold and no apps/flutter-test/linux/ host scaffold in the current repository.
• Dart already expects native notification and action channels: com.tokilabs.nexo.messaging/notifications and com.tokilabs.nexo.messaging/notification_actions.
• The Linux bridge is therefore not implemented yet. Until it exists, local routing can only be tested through Dart unit tests or a future debug injection bridge.
• Local routing fixtures live under apps/flutter-test/linux/Fixtures/*.json.

The first useful Linux smoke target is:

1. Add a Linux plugin platform registration and generated host scaffold in a controlled implementation plan.
2. Register the expected EventChannel and MethodChannel in the Linux plugin.
3. Implement a debug-only local injection path compatible with debugSendNativeEvent.
4. Choose a notification API path and runtime dependency strategy for the smoke.
5. Map notification daemon action data or portal activation data into the Dart NotificationOpenedEvent contract.
6. Collect display, click/open routing, lifecycle, and known ACK, dismiss, and inline reply gap evidence.

Platform Registration Contract

Do not add a partial Linux platform entry without the matching source and host scaffold. A future implementation plan should update these together:

flutter:
  plugin:
    platforms:
      linux:
        pluginClass: NexoMessagingPlugin

Expected source/host areas for that plan:

• packages/messaging_flutter/linux/ for the Linux plugin implementation.
• apps/flutter-test/linux/ for the test host scaffold generated by Flutter.
• packages/messaging_flutter/pubspec.yaml for platform registration.
• apps/flutter-test/README.md and package docs for smoke instructions.

The current preflight milestone documents this contract only. It does not claim Linux runtime support.

Minimum Bridge Contract

The Dart SDK expects the Linux native side to preserve these channel names:

Channel	Name	Direction	Minimum Linux behavior
EventChannel	com.tokilabs.nexo.messaging/notifications	native to Dart	Emit codec-safe maps for notification, open, token, clear, session, and future action-failure events.
MethodChannel	com.tokilabs.nexo.messaging/notification_actions	Dart to native	Accept SDK action methods used by Dart without crashing the host app.

Minimum methods for the action channel:

Method	Minimum preflight result	Production expectation
debugSendNativeEvent	Validate the argument is a map and emit it on the EventChannel.	Debug/test-only injection path.
saveDeviceToken	Accept and store or no-op a formatted token string without logging secrets.	Store the Linux server-registration token once the platform token source is chosen.
getDeviceToken	Return the last stored formatted token or null.	Return the current formatted Linux server-registration token.
setAuthToken	Validate required string arguments and no-op.	Persist token for ACK/reply work only after storage rules are designed.
clearAuthToken	Validate serverUrl and no-op.	Clear persisted token for the server.
setSigningKey	Validate required string arguments and no-op without persistence.	Persist the signing key only after secure storage rules are designed.

Fallback boundaries:

• Missing bridge methods should return the Flutter Linux equivalent of "not implemented", not a successful placeholder.
• Token, auth, signing-key, ACK, dismiss, and inline reply persistence are not implied by this preflight milestone.
• Real notification display and activation handling belong to Linux 알림 테스트 unless a smaller bridge implementation plan explicitly handles them first.

Notification API Matrix

Candidate	Environment fit	Strength	Preflight constraint
D-Bus org.freedesktop.Notifications	Common desktop notification daemon path	Broad support across GNOME, KDE, XFCE, and other desktops	Action callbacks and capabilities vary by daemon and session.
XDG Desktop Portal notifications	Flatpak/sandbox-friendly desktops	Better fit for portal-mediated desktop environments	Portal availability and notification support vary by distribution and session.
libnotify wrapper	Thin client around the freedesktop notification spec	Simple display smoke for common desktops	Callback/action support still depends on the underlying daemon.
Local debug injection only	No daemon, package, or desktop requirement	Deterministic EventChannel/opened-routing verification	Does not prove OS display or activation.

Preflight default: use local debug injection for contract tests, and defer the D-Bus vs desktop portal vs libnotify runtime decision to the Linux 알림 테스트 milestone or a dedicated implementation plan.

Runtime Dependency Boundaries

Future Linux notification implementation should record the runtime assumptions before claiming smoke support:

• Distribution and version, such as Ubuntu, Fedora, Debian, or another target.
• Desktop environment and session type, such as GNOME/KDE/XFCE and X11/Wayland.
• Notification daemon or portal availability.
• Required build packages and runtime libraries.
• Whether action callbacks are supported by the chosen daemon or portal path.

Tracked docs should keep these as sanitized evidence fields, not private machine configuration dumps.

Payload Mapping

Linux notification action data maps into Dart using the same stable keys as the Android, iOS, macOS, and Windows contracts:

Payload key	Dart event field	Notes
type	type	Use message for visible message notifications and opened for direct open events.
server_url	server_url	Required before host navigation callbacks can run.
server_id	server_id	Diagnostic and future server URL fallback input.
channel_id	channel_id	Drives onNavigateToChannel when thread routing is not selected.
root_id	root_id	Drives onNavigateToThread when CRT is enabled.
is_crt_enabled	is_crt_enabled	Accept boolean true, string "true", or string "1".
ack_id	ack_id	Preserve for future ACK evidence; do not invent ACK behavior.
post_id	post_id	Preserve for notification identity and future ACK/display evidence.
userInteraction	userInteraction	Set to true when a click/open path caused the event.

Routing expectation:

• Channel fixture: server_url and channel_id are present, root_id is empty and is_crt_enabled is false, so Dart calls onNavigateToChannel.
• Thread fixture: server_url and root_id are present and is_crt_enabled is true, so Dart calls onNavigateToThread.

Local Fixtures

Use the fixture files as sanitized payloads for a future debug injection method or for manual D-Bus/portal action data construction during smoke testing:

• apps/flutter-test/linux/Fixtures/open_channel.json
• apps/flutter-test/linux/Fixtures/open_thread.json

The fixtures intentionally use https://example.invalid and smoke IDs. Replace private runtime values only in local run notes or sanitized evidence.

Evidence

Use linux-notification-smoke-evidence-template.md for Linux runs. Preflight evidence should explicitly separate:

• distribution, desktop environment, session, and daemon or portal state
• visible display state
• click/open routing result
• app lifecycle state
• ACK, dismiss, and inline reply implementation gaps

Until the scaffold, bridge, and real OS smoke exist, a valid preflight result may be "not implemented yet" with a concrete follow-up plan, rather than a failed runtime claim.