Firefox API Proxy

This service proxies Firefox browser API requests across multiple back end services.

This service is only intended to be used by firefox clients. It has a lot of convention and rigidity that is specifically tailored to that client.

What's different about Firefox?

Firefox is released through a lengthy release process. It takes a long time for code to reach users, and it takes a long time for users to stop using code.

https://whattrainisitnow.com/calendar/ Provides dates when specific releases will reach end users.

https://endoflife.date/firefox Provides dates when specific versions will reach support end of life (but not necessarily when users will stop using it!)

The bookkeeping we have for other services can be lacking here, because the date code is committed can be so far from when it actually reaches end users, and the code in firefox never really leaves production use.

The OpenAPI Spec in this repo codifies the contract this service has with firefox in a single place, and documents the at least first and last versions of firefox stable to consume each API path. This documentation bridges the gap between agile and waterfall processes, and allows us to make confident decisions around API support requirements and deprecation without digging into multiple commits in multiple code bases.

Types are also generated from this API spec, ensuring that internal GraphQL client changes are compatible with the API spec and contract.

Application Overview

Express is being used to receive requests.

OpenAPI is being used for documentation, request validation, response validation, and will be leveraged in the future for additional protections against breaking changes.

This initial implementation transforms requests against this proxy, into requests against the 'pocket-graph' via the Web graphql proxy, providing a subset of the V3 Web API's functionality specifically for firefox clients (desktop, and probably mobile in the future).

File structure

• the infrastructure code is present in .aws
• the application code is in src
• .circleci contains circleCI setup
• openapi.yml contains api documentation

Develop Locally

First time setup

Clone the repo:

git clone [email protected]:Pocket/firefox-api-proxy.git
cd firefox-api-proxy

Running tests

npm run test

Testing locally

Start the server with:

npm ci
npm run start:dev

You will need authentication appropriate for the web V3 API deployment environment that is backing requests.

E2E local testing with curl

Local E2E testing requires production Session Auth (cookie) authentication.

A helper script for generating authentication curl args can be found at ./scripts/scrapeCookie.js.

Curl sample:

`curl 'http://localhost:4028/desktop/v1/recent-saves?count=1' <AUTH HEADERS GO HERE>`

Leading with documentation, generated types

It is strongly suggested to lead implementation of features with changes to:

• ./openapi.yml
• ./src/graphql-proxy/**/*.graphql

These files are used to generate the types files in ./src/generated/* with the following npm script:

npm run codegen

Upon changing these files and generating types, the compiler and unit tests should guide you through required changes to remain compatible with older versions of the APIs.

About errors in this service

All errors contain an id. These are just random strings that you can search for in this repo to get more context on an error.

This service needs to provide an API for every version of Firefox that ever gets deployed against this service. When a client receives a 5XX error response, follow these guidelines:

• 500 Error
  • This service itself can have bugs, or may not be equipped to handle every error that can result from utilizing dependencies. In these cases, this service needs to protect itself and will redact errors. If you see one of these errors, please open a bug against this service.
• 502 Error
  • This service is equipped to handle the currently known GraphQL errors associated with its queries. When these errors are encountered, this service will forward the GraphQL error to Firefox for informational purposes, however do not handle GraphQL errors directly in Firefox. The graph internals may change without notice, and the names in error messages may also change without notice in turn. In this case, do one of the following:
    1. If the error includes all of the details needed to handle it, implement a new error handler in this service that transforms the error into an appropriate 4XX error. Add it to defaultHandlers in GraphQLErrorHandler if it is an error all routes must handle. Otherwise, add it to a route specific error handler if not.
    2. If the error is too vague to handle it in this service, open a bug against the appropriate GraphQL server component. #support-backend can help identify the appropriate component if needed.

All 5XX errors get recorded as events in sentry, and logged into cloudwatch with correlating tags between the two.