ibl-graph-fallbacks-key-generator

[!NOTE] From 2.1.0 onwards a new version of the query config is needed for programme fallbacks. The version can be found here https://fallbacks.ibl.api.bbci.co.uk/query-config-v2.json. The new query config should include default properties for some variables for a programme query.

Library to encapsulate generating fallback keys for iBL Graph Edge. Ultimately the 'keys' access fallback data in an S3 bucket that is available via CloudFront. They should be used to build a url ie https://fallbacks.ibl.api.bbci.co.uk/query-nested-variable-o18-signedOut.json

iBL use a generated list of persisted query configurations in the fallbacks system. This list is used to build the fallbacks keys in a predictable manner, as well as to provide validation and overrides during the rebuilding process. It is publically available via https://fallbacks.ibl.api.bbci.co.uk/query-config-v2.json and can be loaded by clients and passed in to the key generator as the second argument.

Clients may want to use a version of this list that only includes the queries they make, this will mean they have to manually update it when they add a new query. Currently it is not known if there are any other reasons the persisted query conf list may differ that would matter in the context of building the file keys.

The persisted query api also has the full list of queries but it is NOT designed for large number of requests and requires the service to be within the iBL account's VPC. It could be used to source a valid list of known query ids, ie: https://persisted-queries.ibl.api.bbci.co.uk/queries/5bf0f14684528c5112d71e3472e6d1f8, again it is NOT designed for high consumption.

The latest version of this library needs to be kept up to date with the current categories list available in the ibl-categories (which is returned unmodified) client api otherwise it may produce inconsistent results for fallbacks that use queries.

We do have a publicly available version of the categories list at https://ibl.api.bbci.co.uk/ibl/v1/categories but this list has been transformed and filtered.

Tests in both projects have been added to prevent drift. When publishing a new version with a new/changed category it will become temporarily impossible to publish without these tests failing, as one of the packages will unpublished. np has a --no-tests option which can be used. Be sure that the only test that is failing is the synchronicity test before doing this.

Install

pnpm install --save @bbc/ibl-graph-fallbacks-key-generator

Usage

const key: string = generateKey({
  //The POST body sent to the ibl graphql endpoint that has failed
  query: postQuery, 
  //List of QueryConfigurations that should be considered, either the 
  //contents of https://fallbacks.ibl.api.bbci.co.uk/query-config-v2.json
  //or a subset of queries a client is interested in.
  conf: persistedQueryConfigurations,
  //Optional category client, wrap the latest @ibl/categories-client version for accuracy
  categoryClient
});

import generateKey from '@bbc/ibl-graph-fallbacks-key-generator' 

//The POST body of the query sent to the graphql endpoint
const query = {
  id: "0eeadbf5d769e99f13bd798538ce7897",
  variables:{
    userState:"signedIn",
    userAgeBracket: "u16"
  }
}

//See https://fallbacks.ibl.api.bbci.co.uk/query-config-v2.json for a full example 
const persistedQueryConfigurations = [
  {
    id: '0eeadbf5d769e99f13bd798538ce7897',
    viewId: 'home',
    name: 'client-home-query',
    query: 'query Home(....)',
    rootQueries: [
      'view'
    ],
    queryVariables: [
      {
        name: 'userState',
        type: 'UserState'
      }
    ],
    variables: {
      userAgeBracket: {
        values: [
          'o18',
          'u18',
          'u16',
          'u13'
        ],
        override: 'o18'
      },
      userState: {
        values: [
          'signedOut'
        ],
        override: 'signedOut'
      }
    },
    hasFallback: true
  }
];

//For programme fallbacks see https://fallbacks.ibl.api.bbci.co.uk/query-config-v2.json for a full example 
const persistedProgrammeQueryConfigurations = [
  {
    id: '0eeadbf5d769e99f13bd798538ce7897',
    viewId: 'home',
    name: 'client-home-query',
    query: 'query Home(....)',
    rootQueries: [
      'programme'
    ],
    queryVariables: [
      {
        name: 'userState',
        type: 'UserState'
      }
    ],
    variables: {
      userAgeBracket: {
        values: [
          'o18',
          'u18',
          'u16',
          'u13'
        ],
        override: 'o18',
        fallbackDefaultValue: 'o18'
      },
      userState: {
        values: [
          'signedOut'
        ],
        override: 'signedOut',
        fallbackDefaultValue: 'signOut'
      }
    },
    hasFallback: true
  }
];

//Example fallback categories client with single method used by the key generator.
//see https://github.com/bbc/ibl-categories
const fallbackCategoryClient = {
  getTopLevelIds: (): string[] => {
    return [ 'drama-and-soaps' ... ]
  }
}

const key: string = generateKey({query, conf: persistedQueryConfigurations, categoriesClient: fallbackCategoryClient});

Release

npx np