feat: Report coverage latency in shield metrics (#7133)

## Explanation

This PR adds latency reporting to shield coverage and signature coverage
results. The latency (in milliseconds) is included as part of the
`metrics` property in each coverage response, allowing downstream
consumers and analytics systems to track and analyze the performance of
coverage checks.

Unit tests have been updated to verify correct latency values in the
metrics.

### Changes

- Add `metrics.latency` to coverage and signature coverage responses.
- Update backend and test logic to use `Date.now()` for latency
measurements.
- Extend unit test coverage to validate latency reporting in result
metrics.

<!--
Thanks for your contribution! Take a moment to answer these questions so
that reviewers have the information they need to properly understand
your changes:

* What is the current state of things and why does it need to change?
* What is the solution your changes offer and how does it work?
* Are there any changes whose purpose might not obvious to those
unfamiliar with the domain?
* If your primary goal was to update one package but you found you had
to update another one along the way, why did you do so?
* If you had to upgrade a dependency, why did you do so?
-->

## References

<!--
Are there any issues that this pull request is tied to?
Are there other links that reviewers should consult to understand these
changes better?
Are there client or consumer pull requests to adopt any breaking
changes?

For example: 

* Fixes #12345
* Related to #67890
-->

Fixes MetaMask/MetaMask-planning#6136

## Checklist

- [x] I've updated the test suite for new or updated code as appropriate
- [x] I've updated documentation (JSDoc, Markdown, etc.) for new or
updated code as appropriate
- [x] I've communicated my changes to consumers by [updating changelogs
for packages I've
changed](https://github.com/MetaMask/core/tree/main/docs/contributing.md#updating-changelogs),
highlighting breaking changes as necessary
- [x] I've prepared draft pull requests for clients and consumer
packages to resolve any breaking changes

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> Add `metrics.latency` to coverage and signature coverage responses,
measuring end-to-end latency (including retries) and update tests and
changelog accordingly.
> 
> - **Backend**:
> - Add `metrics.latency` to `GetCoverageResultResponse` and
`CoverageResult` returned by `ShieldRemoteBackend`.
> - Measure end-to-end latency in `#getCoverageResult` using
`Date.now()`, including retries/delays via polling policy.
> - **Types**:
> - Extend `CoverageResult` and `GetCoverageResultResponse` with
`metrics.latency` in `src/types.ts` and `src/backend.ts`.
> - **Tests**:
> - Update `src/backend.test.ts` to assert presence and correctness of
`metrics.latency` for both transaction and signature coverage, including
retry-delay scenarios.
> - **Changelog**:
> - Document addition of latency metrics in
`packages/shield-controller/CHANGELOG.md`.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
fc9d432. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Tuna <tunguyenanh@tunatech.org>
Co-authored-by: Chaitanya Potti <chaitanya.potti@gmail.com>

Author: 3 people

packages/shield-controller/CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Added metrics in the Shield coverage response to track the latency ( [#7133](https://github.com/MetaMask/core/pull/7133))
+
 ## [2.0.0]
 
 ### Changed

packages/shield-controller/src/backend.test.ts

@@ -51,6 +51,10 @@ function setup({
 }
 
 describe('ShieldRemoteBackend', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
   it('should check coverage', async () => {
     const { backend, fetchMock, getAccessToken } = setup();
 
@@ -70,14 +74,24 @@ describe('ShieldRemoteBackend', () => {
 
     const txMeta = generateMockTxMeta();
     const coverageResult = await backend.checkCoverage({ txMeta });
-    expect(coverageResult).toStrictEqual({ coverageId, ...result });
+    expect({
+      coverageId: coverageResult.coverageId,
+      message: result.message,
+      reasonCode: result.reasonCode,
+      status: result.status,
+    }).toStrictEqual({
+      coverageId,
+      ...result,
+    });
+    expect(typeof coverageResult.metrics.latency).toBe('number');
     expect(fetchMock).toHaveBeenCalledTimes(2);
     expect(getAccessToken).toHaveBeenCalledTimes(2);
   });
 
   it('should check coverage with delay', async () => {
+    const pollInterval = 100;
     const { backend, fetchMock, getAccessToken } = setup({
-      getCoverageResultPollInterval: 100,
+      getCoverageResultPollInterval: pollInterval,
     });
 
     // Mock init coverage check.
@@ -101,13 +115,38 @@ describe('ShieldRemoteBackend', () => {
     } as unknown as Response);
 
     const txMeta = generateMockTxMeta();
+
+    // generateMockTxMeta also use Date.now() to set the time, only do this after generateMockTxMeta
+    // Mock Date.now() to control latency measurement
+    // Simulate latency that includes the retry delay (poll interval + processing time)
+    let callCount = 0;
+    const startTime = 1000;
+    const expectedLatency = pollInterval + 50; // poll interval + processing time
+    const nowSpy = jest.spyOn(Date, 'now').mockImplementation(() => {
+      callCount += 1;
+      // First call: start of #getCoverageResult
+      if (callCount === 1) {
+        return startTime;
+      }
+      // Final call: end of #getCoverageResult (after retry delay)
+      return startTime + expectedLatency;
+    });
+
     const coverageResult = await backend.checkCoverage({ txMeta });
-    expect(coverageResult).toStrictEqual({
+
+    expect(coverageResult).toMatchObject({
       coverageId,
-      ...result,
+      status: result.status,
+      message: result.message,
+      reasonCode: result.reasonCode,
     });
+    expect(coverageResult.metrics.latency).toBe(expectedLatency);
+    // Latency should include the retry delay (at least the poll interval)
+    expect(coverageResult.metrics.latency).toBeGreaterThanOrEqual(pollInterval);
     expect(fetchMock).toHaveBeenCalledTimes(3);
     expect(getAccessToken).toHaveBeenCalledTimes(2);
+
+    nowSpy.mockRestore();
   });
 
   it('should throw on init coverage check failure', async () => {
@@ -187,6 +226,66 @@ describe('ShieldRemoteBackend', () => {
     await new Promise((resolve) => setTimeout(resolve, 10));
   });
 
+  it('returns latency in coverageResult', async () => {
+    const { backend, fetchMock } = setup();
+
+    fetchMock.mockResolvedValueOnce({
+      status: 200,
+      json: jest.fn().mockResolvedValue({ coverageId: 'coverageId' }),
+    } as unknown as Response);
+
+    const result = { status: 'covered', message: 'ok', reasonCode: 'E104' };
+    fetchMock.mockResolvedValueOnce({
+      status: 200,
+      json: jest.fn().mockResolvedValue(result),
+    } as unknown as Response);
+
+    let nowValue = 1000;
+    const latencyMs = 123;
+    const nowSpy = jest.spyOn(Date, 'now').mockImplementation(() => {
+      const val = nowValue;
+      nowValue += latencyMs;
+      return val;
+    });
+
+    const txMeta = generateMockTxMeta();
+    const coverageResult = await backend.checkCoverage({ txMeta });
+    expect(coverageResult.metrics.latency).toBe(latencyMs);
+
+    nowSpy.mockRestore();
+  });
+
+  it('returns latency in signatureCoverageResult', async () => {
+    const { backend, fetchMock } = setup();
+
+    fetchMock.mockResolvedValueOnce({
+      status: 200,
+      json: jest.fn().mockResolvedValue({ coverageId: 'coverageId' }),
+    } as unknown as Response);
+
+    const result = { status: 'covered', message: 'ok', reasonCode: 'E104' };
+    fetchMock.mockResolvedValueOnce({
+      status: 200,
+      json: jest.fn().mockResolvedValue(result),
+    } as unknown as Response);
+
+    let nowValue = 2000;
+    const latencyMs = 456;
+    const nowSpy = jest.spyOn(Date, 'now').mockImplementation(() => {
+      const val = nowValue;
+      nowValue += latencyMs;
+      return val;
+    });
+
+    const signatureRequest = generateMockSignatureRequest();
+    const coverageResult = await backend.checkSignatureCoverage({
+      signatureRequest,
+    });
+    expect(coverageResult.metrics.latency).toBe(latencyMs);
+
+    nowSpy.mockRestore();
+  });
+
   describe('checkSignatureCoverage', () => {
     it('should check signature coverage', async () => {
       const { backend, fetchMock, getAccessToken } = setup();
@@ -209,10 +308,16 @@ describe('ShieldRemoteBackend', () => {
       const coverageResult = await backend.checkSignatureCoverage({
         signatureRequest,
       });
-      expect(coverageResult).toStrictEqual({
+      expect({
+        coverageId: coverageResult.coverageId,
+        message: result.message,
+        reasonCode: result.reasonCode,
+        status: result.status,
+      }).toStrictEqual({
         coverageId,
         ...result,
       });
+      expect(typeof coverageResult.metrics.latency).toBe('number');
       expect(fetchMock).toHaveBeenCalledTimes(2);
       expect(getAccessToken).toHaveBeenCalledTimes(2);
     });

packages/shield-controller/src/backend.ts

@@ -57,6 +57,9 @@ export type GetCoverageResultResponse = {
   message?: string;
   reasonCode?: string;
   status: CoverageStatus;
+  metrics: {
+    latency?: number;
+  };
 };
 
 export class ShieldRemoteBackend implements ShieldBackend {
@@ -117,6 +120,7 @@ export class ShieldRemoteBackend implements ShieldBackend {
       message: coverageResult.message,
       reasonCode: coverageResult.reasonCode,
       status: coverageResult.status,
+      metrics: coverageResult.metrics,
     };
   }
 
@@ -143,6 +147,7 @@ export class ShieldRemoteBackend implements ShieldBackend {
       message: coverageResult.message,
       reasonCode: coverageResult.reasonCode,
       status: coverageResult.status,
+      metrics: coverageResult.metrics,
     };
   }
 
@@ -220,15 +225,20 @@ export class ShieldRemoteBackend implements ShieldBackend {
 
     const headers = await this.#createHeaders();
 
+    // Start measuring total end-to-end latency including retries and delays
+    const startTime = Date.now();
+
     const getCoverageResultFn = async (signal: AbortSignal) => {
       const res = await this.#fetch(coverageResultUrl, {
         method: 'POST',
         headers,
         body: JSON.stringify(reqBody),
         signal,
       });
+
       if (res.status === 200) {
-        return (await res.json()) as GetCoverageResultResponse;
+        // Return the result without latency here - we'll add total latency after polling completes
+        return (await res.json()) as Omit<GetCoverageResultResponse, 'metrics'>;
       }
 
       // parse the error message from the response body
@@ -242,7 +252,19 @@ export class ShieldRemoteBackend implements ShieldBackend {
       throw new HttpError(res.status, errorMessage);
     };
 
-    return this.#pollingPolicy.start(requestId, getCoverageResultFn);
+    const result = await this.#pollingPolicy.start(
+      requestId,
+      getCoverageResultFn,
+    );
+
+    // Calculate total end-to-end latency including all retries and delays
+    const now = Date.now();
+    const totalLatency = now - startTime;
+
+    return {
+      ...result,
+      metrics: { latency: totalLatency },
+    } as GetCoverageResultResponse;
   }
 
   async #createHeaders() {

packages/shield-controller/src/types.ts

@@ -6,6 +6,9 @@ export type CoverageResult = {
   message?: string;
   reasonCode?: string;
   status: CoverageStatus;
+  metrics: {
+    latency?: number;
+  };
 };
 
 export const coverageStatuses = ['covered', 'malicious', 'unknown'] as const;