fix: improve errors for usage processor 2 format (#6472)

Author: n1ru4l

.changeset/small-readers-melt.md

@@ -0,0 +1,6 @@
+---
+'hive': patch
+---
+
+Improve the usage reporting endpoint error responses to include all the errors for invalid JSON
+bodies.

packages/services/usage/__tests__/usage-processor-2-validation.spec.ts

@@ -1009,3 +1009,50 @@ test('$.operations.execution.errorsTotal is required', () => {
     success: false,
   });
 });
+
+test('invalid duration and timestamp (-1) gives helpful error response', () => {
+  expect(
+    decodeReport({
+      size: 1,
+      map: {
+        op1Key: {
+          operation: `query op1Name { field1 }`,
+          fields: ['Query.field1'],
+        },
+      },
+      operations: [
+        {
+          operationMapKey: 'op1Key',
+          timestamp: -1,
+          execution: {
+            ok: true,
+            duration: -1,
+            errorsTotal: 1,
+          },
+        },
+      ],
+    }),
+  ).toEqual({
+    errors: [
+      {
+        errors: [
+          {
+            message: 'Expected valid unix timestamp in milliseconds',
+            path: '/operations/0/timestamp',
+          },
+          {
+            message: 'Expected integer to be greater or equal to 0',
+            path: '/operations/0/execution/duration',
+          },
+          {
+            message: 'Expected null',
+            path: '/operations',
+          },
+        ],
+        message: 'Expected union value',
+        path: '/operations',
+      },
+    ],
+    success: false,
+  });
+});

packages/services/usage/src/usage-processor-2.ts

@@ -8,6 +8,7 @@ import {
 } from '@hive/usage-common';
 import * as tb from '@sinclair/typebox';
 import * as tc from '@sinclair/typebox/compiler';
+import * as tbe from '@sinclair/typebox/errors';
 import { invalidRawOperations, rawOperationsSize, totalOperations, totalReports } from './metrics';
 import { TokensResponse } from './tokens';
 import { isValidOperationBody } from './usage-processor-1';
@@ -34,7 +35,7 @@ export const usageProcessorV2 = traceInlineSync(
     token: TokensResponse,
     targetRetentionInDays: number | null,
   ):
-    | { success: false; errors: Array<tc.ValueError> }
+    | { success: false; errors: Array<ValueError> }
     | {
         success: true;
         report: RawReport;
@@ -307,6 +308,12 @@ function isUnixTimestamp(x: number) {
   return unixTimestampRegex.test(String(x));
 }
 
+tbe.SetErrorFunction(param => {
+  return param.schema[tb.Kind] === 'UnixTimestampInMs'
+    ? 'Expected valid unix timestamp in milliseconds'
+    : tbe.DefaultErrorFunction(param);
+});
+
 tb.TypeRegistry.Set<number>('UnixTimestampInMs', (_, value) =>
   typeof value === 'number' ? isUnixTimestamp(value) : false,
 );
@@ -361,14 +368,20 @@ type ReportType = tb.Static<typeof ReportSchema>;
 
 const ReportModel = tc.TypeCompiler.Compile(ReportSchema);
 
+interface ValueError {
+  path: string;
+  message: string;
+  errors?: ValueError[];
+}
+
 export function decodeReport(
   report: unknown,
-): { success: true; report: ReportType } | { success: false; errors: tc.ValueError[] } {
-  const errors = getFirstN(ReportModel.Errors(report), 5);
-  if (errors.length) {
+): { success: true; report: ReportType } | { success: false; errors: Array<ValueError> } {
+  const errors = ReportModel.Errors(report);
+  if (ReportModel.Errors(report).First()) {
     return {
       success: false,
-      errors,
+      errors: getTypeBoxErrors(errors),
     };
   }
 
@@ -378,19 +391,15 @@ export function decodeReport(
   };
 }
 
-function getFirstN<TValue>(iterable: Iterable<TValue>, max: number): TValue[] {
-  let counter = 0;
-  const items: Array<TValue> = [];
-  for (const item of iterable) {
-    items.push(item);
-    counter++;
-
-    if (counter >= max) {
-      break;
-    }
-  }
-
-  return items;
+function getTypeBoxErrors(errors: tc.ValueErrorIterator): Array<ValueError> {
+  return Array.from(errors).map(error => {
+    const errors = error.errors.flatMap(errors => getTypeBoxErrors(errors));
+    return {
+      path: error.path,
+      message: error.message,
+      errors: errors.length ? errors : undefined,
+    };
+  });
 }
 
 const DAY_IN_MS = 86_400_000;

packages/web/docs/src/content/specs/usage-reports.mdx

@@ -19,8 +19,9 @@ them in batches (as a single report, when a buffer is full or every few seconds)
 | Authorization Header | `Authorization: Bearer token-here`   |
 | API version Header   | `X-Usage-API-Version: 2`             |
 | Method               | `POST`                               |
+| Content-Type Header  | `Content-Type: application/json`     |
 
-## Data structure
+## JSON Body structure
 
 <details>
   <summary>TypeScript schema</summary>
@@ -193,3 +194,58 @@ curl -X POST \
   -H 'content-type: application/json' \
   -d '{ "size": 1, "map": { "aaa": { "operationName": "me", "operation": "query me { me { id } }", "fields": ["Query", "Query.me", "User", "User.id"] } }, "operations": [{ "operationMapKey" : "c3b6d9b0", "timestamp" : 1663158676535, "execution" : { "ok" : true, "duration" : 150000000, "errorsTotal" : 0 }, "metadata" : { "client" : { "name" : "demo" , "version" : "0.0.1" } } } ] }'
 ```
+
+## Response
+
+| Status Code | Meaning                                              |
+| ----------- | ---------------------------------------------------- |
+| `200`       | Usage data was successfully accepted.                |
+| `400`       | Errors while processing the sent JSON body.          |
+| `401`       | Invalid `X-Usage-API-Version` header provided.       |
+| `429`       | Rate limited due to exceeding usage reporting quota. |
+| `500`       | An unexpected error occured.                         |
+
+The endpoint will return a JSON body response body for `200` and `400` status codes.
+
+### 200 Status Body
+
+```json filename="Response 200"
+{
+  "id": "c6ba1f9c-44c0-40a1-8089-65f7e4de5de5",
+  "operations": {
+    "accepted": 20,
+    "rejected": 0
+  }
+}
+```
+
+### 400 Status Body
+
+A response with status 400 indicates that the report sent within the request body is not valid. The
+response body will contain a JSON Schema validation errors that can be used to debug the faulty
+request body.
+
+```json filename="Response 400"
+{
+  "errors": [
+    {
+      "message": "Expected union value",
+      "path": "/operations",
+      "errors": [
+        {
+          "message": "Expected valid unix timestamp in milliseconds",
+          "path": "/operations/0/timestamp"
+        },
+        {
+          "message": "Expected integer to be greater or equal to 0",
+          "path": "/operations/0/execution/duration"
+        },
+        {
+          "message": "Expected null",
+          "path": "/operations"
+        }
+      ]
+    }
+  ]
+}
+```