Skip to content

feat: implement typed worker message protocol (#189) - #205

Open
code3ks wants to merge 3 commits into
wraith-protocol:developfrom
code3ks:feat/typed-worker-protocol-189
Open

code3ks wants to merge 3 commits into
wraith-protocol:developfrom
code3ks:feat/typed-worker-protocol-189

Conversation

@code3ks

@code3ks code3ks commented Sep 27, 2026

Copy link
Copy Markdown

Changes

New File

  • src/types/messages.ts - Complete typed protocol definition (v1.0.0)
    • Versioned TypeScript message unions for all worker communications
    • Runtime validation functions for ServiceWorker, BroadcastChannel, and WebWorker messages
    • Helper functions (createMessage, postVersionedMessage)

Updated Files

  • Service Workers

    • src/sw/app-sw.ts - Validates incoming messages, sends versioned responses
    • src/sw/stellar-notification-sw.ts - Validates incoming messages, sends versioned responses
  • Web Worker

    • src/workers/stellar-scanner.worker.ts - Validates scan requests, sends versioned responses
  • React Hooks

    • src/hooks/useStellarNotifications.ts - Sends versioned messages to service workers
  • Context

    • src/context/StellarWalletContext.tsx - Validates BroadcastChannel messages for cross-tab sync

Features

✅ Versioned TypeScript message unions - All 21 message types defined with version field
✅ Runtime validation - All message receivers validate incoming messages
✅ Reject unknown versions - Major version must match, descriptive error messages
✅ Shared protocol - Single source of truth in src/types/messages.ts
✅ Backward compatibility - Legacy messages without version accepted with warnings

Message Types Implemented

  • ServiceWorker (12 types): REGISTER_VIEWING_KEY, UNREGISTER_VIEWING_KEY, TRIGGER_SCAN, REGISTER_PUSH_SUBSCRIPTION, UNREGISTER_PUSH_SUBSCRIPTION, SKIP_WAITING + 6 response types
  • BroadcastChannel (5 types): CONNECTED, DISCONNECTED, NETWORK_CHANGED, WRAITH_NOTIFICATION, NAVIGATE_TO_MATCH
  • WebWorker (3 types): SCAN_REQUEST, SUCCESS, ERROR

Testing

  • ✅ TypeScript compilation passes (no diagnostics)
  • ✅ Code formatting passes (prettier)
  • ✅ All modified files use typed protocol
  • ✅ Backward compatibility maintained

Done When (from issue #189)

  • ✅ Define versioned TypeScript message unions
  • ✅ Validate incoming messages at runtime
  • ✅ Reject unknown versions and unsafe payloads
  • ✅ Share the protocol between the app and both worker entrypoints

closes #189

@vercel

vercel Bot commented Sep 27, 2026

Copy link
Copy Markdown

@code3ks is attempting to deploy a commit to the truthixify's projects Team on Vercel.

A member of the Team first needs to authorize it.

@drips-wave

drips-wave Bot commented Sep 27, 2026

Copy link
Copy Markdown

@code3ks Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

@truthixify

Copy link
Copy Markdown
Contributor

This branch includes the idempotency implementation and unrelated wallet and UI changes. Please rebase and keep only the shared message protocol plus the app and worker integrations required by #189.

@code3ks
code3ks force-pushed the feat/typed-worker-protocol-189 branch from f250fcf to 1fc64a1 Compare September 29, 2026 07:09
…nd web worker

- Add validateBroadcastChannelMessage + createMessage to StellarWalletContext
- Add createMessage to useStellarNotifications for all SW postMessage calls
- Add validateServiceWorkerInboundMessage + sendResponse helper to app-sw.ts
- Add validateServiceWorkerInboundMessage + sendResponse helper to stellar-notification-sw.ts
- Add validateWebWorkerMessage to stellar-scanner.worker.ts
- Fix ScanStrategy type conflict (string union vs interface)

Resolves wraith-protocol#189
@code3ks
code3ks force-pushed the feat/typed-worker-protocol-189 branch from 1fc64a1 to e2372b0 Compare September 29, 2026 08:09
@truthixify

Copy link
Copy Markdown
Contributor

RECOVER_SCAN_CURSOR is missing from the union and valid types, so the validator now rejects that existing flow before its handler runs. Include all existing messages, reject missing versions, validate payload types, and add protocol tests.

…ads, add tests

- Add RecoverScanCursorMessage (publicKey, oldestAvailableLedger) to
  ServiceWorkerInboundMessage union
- Add StellarScanRetentionGapMessage and StellarScanRecoveryCompleteMessage
  to ServiceWorkerOutboundMessage union
- isVersionCompatible: reject missing version — no more silent fallback
- validateServiceWorkerInboundMessage: RECOVER_SCAN_CURSOR added to
  validTypes; all payload fields now type-checked (string publicKey,
  positive-integer ledger, object subscription, etc.)
- validateServiceWorkerOutboundMessage: add new broadcast types and tighten
  error-field checks
- app-sw.ts / stellar-notification-sw.ts: remove all 'message as any'
  casts; destructure per handler from the typed message; add explicit
  SKIP_WAITING guard before RECOVER_SCAN_CURSOR
- src/types/messages.test.ts: 49 tests — every validator, all valid paths,
  missing-version rejection, unknown-type rejection, per-field payload checks
@truthixify

Copy link
Copy Markdown
Contributor

The missing version and cursor cases are fixed. Payload validation is still presence-only in several paths: encrypted keys are not checked as ArrayBuffer, BroadcastChannel fields are not type checked, and scan keys and scalars accept any value. Validate the actual payload types and add unsafe-type tests.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Wave 9] Define a typed worker message protocol

2 participants