feat: Implementation of gelocation controller by MarioAslau · Pull Request #8037 · MetaMask/core

MarioAslau · 2026-02-25T01:44:08Z

Explanation

Problem

On mobile, four separate features (Ramp, Perps, Rewards, Card) independently call the same geolocation API endpoint (https://on-ramp.api.cx.metamask.io/geolocation), each with its own implementation, URL constants, caching strategy, and trigger mechanism. This results in 2–4 redundant HTTP calls on every app load (~1.8–3.1 seconds each), inconsistent environment URL handling across features, and no shared cache.

Feature	Fetch Method	Caching	Trigger
Ramp	`fetch()`	None	`useEffect` on mount
Perps	`successfulFetch()`	5-min TTL + promise dedup	`checkEligibility()` call
Rewards	`successfulFetch()`	Controller-level in-memory	`getGeoRewardsMetadata()` call
Card	`fetch()`	None	`getCardholder()` call

Solution

This PR introduces a new @metamask/geolocation-controller package that centralises geolocation fetching behind a single GeolocationController. The controller extends BaseController from @metamask/base-controller and follows established controller conventions (matching the patterns in connectivity-controller).

Key design decisions:

TTL-based caching (configurable, default 5 minutes) — prevents redundant network calls when the cached value is still fresh.
Promise coalescing — concurrent calls to getGeolocation() share a single in-flight promise, so multiple consumers calling simultaneously produce only one HTTP request.
Injectable fetch function — the controller accepts a fetch parameter (defaults to globalThis.fetch), consistent with the RampsService pattern. This makes the controller fully testable without global mocks.
Environment-aware URL resolution — a getGeolocationUrl callback is provided at construction time, allowing the host application to resolve the correct API URL (prod vs. dev/UAT) without the controller having to know about environment configuration.
No persistence — state is in-memory only (persist: false on all metadata fields). Geolocation is re-fetched on every app restart, which is appropriate since the data is IP-based and lightweight.
Platform-agnostic — no dependency on mobile or extension-specific code. The package is reusable across all MetaMask clients.

What's included

New package: packages/geolocation-controller/

src/GeolocationController.ts — Controller implementation with state management, TTL cache, and promise deduplication
src/types.ts — GeolocationStatus type ('idle' | 'loading' | 'complete' | 'error')
src/GeolocationController-method-action-types.ts — Messenger action types for getGeolocation and refreshGeolocation
src/index.ts — Public exports
src/GeolocationController.test.ts — 25 test cases covering cache behaviour, promise deduplication, fetch success/failure, refresh, messenger integration, metadata, and edge cases
Package scaffolding: package.json, tsconfig.json, tsconfig.build.json, jest.config.js, typedoc.json, README.md, CHANGELOG.md, LICENSE

Modified: tsconfig.json — added project reference for the new package (alphabetical order, after gator-permissions-controller)

Public API

State:

type GeolocationControllerState = {
  location: string;            // ISO country code, e.g. "US", "GB", or "UNKNOWN"
  status: GeolocationStatus;   // 'idle' | 'loading' | 'complete' | 'error'
  lastFetchedAt: number | null; // Epoch ms of last successful fetch
  error: string | null;         // Last error message
};

Messenger actions:

GeolocationController:getGeolocation — Returns the cached location if fresh, otherwise fetches and returns it. Concurrent calls are deduplicated.
GeolocationController:refreshGeolocation — Forces a fresh fetch, bypassing the cache.
GeolocationController:getState — Returns the current controller state (provided by BaseController).

Messenger events:

GeolocationController:stateChange — Fires on every state transition (provided by BaseController).

References

Jira Ticket: https://consensyssoftware.atlassian.net/browse/MCWP-350
Related ADR: decisions/decisions/core/0019-geolocation-controller.md
Messenger pattern ADR: decisions/decisions/core/0001-messaging-non-controllers.md
Reference controller used as template: packages/connectivity-controller/
Follow-up ticket: Mobile integration and consumer migration (register in Engine, migrate Ramp/Perps/Rewards/Card, remove duplicate implementations)

Checklist

I've updated the test suite for new or updated code as appropriate
I've updated documentation (JSDoc, Markdown, etc.) for new or updated code as appropriate
I've communicated my changes to consumers by updating changelogs for packages I've changed
I've introduced breaking changes in this PR and have prepared draft pull requests for clients and consumer packages to resolve them

Note: No breaking changes — this is an entirely new package with no existing consumers.

Note

Medium Risk
New shared controller introduces caching and concurrency/race-handling logic around network fetches; while well-tested, incorrect integration or TTL semantics could affect feature eligibility decisions across clients.

Overview
Introduces a new @metamask/geolocation-controller package that centralizes geolocation fetching behind a BaseController, exposing getGeolocation (TTL-cached + in-flight request deduplication) and refreshGeolocation (bypass cache) via messenger actions and emitting standard stateChange events.

The controller maintains in-memory-only state (location, status, lastFetchedAt, error), supports injectable fetch and environment-provided getGeolocationUrl, and includes extensive Jest coverage for caching, concurrency, refresh race handling, and error/edge cases. Monorepo wiring is updated by adding a TS project reference and yarn workspace lock entry for the new package.

^{Written by Cursor Bugbot for commit 9e74c1c. This will update automatically on new commits. Configure here.}