[public-api] improve request exception logging

[akosyakov]

Description

During rollout we see some functions are failing with Unknown reason, but they are not logged on server side and there is no information to correlate them from a client side. This PR ensures that all exceptional situations are logged on server side, plus on client side we provide request id and method to look up the entire chain in logs.

It also fixes a missing conversion for invalid argument which is reported as Unknown reason right now.

Summary generated by Copilot

🤖[deprecated] Generated by Copilot at 895242f

This pull request improves the error handling, tracing, and documentation of the public API communication between the dashboard and the server components. It uses the handleError and PublicAPIConverter functions to report errors consistently and with context information. It also adds a README file to the components/public-api/typescript-common package and updates the test case for the error message change.

Related Issue(s)

Fixes #

How to test

• Check that each gRPC request has x-request-id response header (for any status code)

• Trigger invalid argument from browser console. Check that it is reported as 400 now, not unknown error. Check that server logs don't log it as public api exception.

fetch("https://ak-request9e413561ca.preview.gitpod-dev.com/public-api/gitpod.v1.OrganizationService/GetOrganizationSettings", {
  "headers": {
    "connect-protocol-version": "1",
    "content-type": "application/json",
  },
  "referrer": "https://ak-request9e413561ca.preview.gitpod-dev.com/settings",
  "referrerPolicy": "no-referrer-when-downgrade",
  "body": "{\"organizationId\":\"xyz\"}",
  "method": "POST",
  "mode": "cors",
  "credentials": "include"
});

• Go to workspaces page, check that you see WatchWorkspaceStatus or LotsOfReplies stream, and then delete server pod to trigger its failure. Check that reportError has info about requestId as well as requestMethod.

Documentation

Preview status

https://ak-request9e413561ca.preview.gitpod-dev.com/workspaces

Build Options

Build

• /werft with-werft
  Run the build with werft instead of GHA
• leeway-no-cache
• /werft no-test
  Run Leeway with --dont-test

Publish

• /werft publish-to-npm
• /werft publish-to-jb-marketplace

Installer

• analytics=segment
• with-dedicated-emulation
• workspace-feature-flags
  Add desired feature flags to the end of the line above, space separated

Preview Environment / Integration Tests

• /werft with-local-preview
  If enabled this will build install/preview
• /werft with-preview
• /werft with-large-vm
• /werft with-gce-vm
  If enabled this will create the environment on GCE infra
• /werft preemptible
  Saves cost. Untick this only if you're really sure you need a non-preemtible machine.
• with-integration-tests=all
  Valid options are all, workspace, webapp, ide, jetbrains, vscode, ssh. If enabled, with-preview and with-large-vm will be enabled.
• with-monitoring

/hold

[geropl]

Starting preview...

[geropl]

Code LGTM (sans this comment), tested and works. 🏁

✔️ to unblock (re-ping if you want another review 👍)

[akosyakov]

@geropl i overcomplicated it, but using proper APIs even with stream response headers are enough. I pushed an update. Fine to unhold?

If server stream fails after succesful connection requestId is present:

If server stream is not able to connect at all requestId is missing:

[akosyakov]

/unhold

[geropl]

Cool, let's go!