ci(docs-infra): change AIO preview server stuff to pull builds from CircleCI

Previously, Travis pushed the build artitfacts to the preview server.
This required us to use JWT to secure the POST request from Travis, to
ensure we couldn't receive malicious builds.

JWT has been deprecated and we are moving our builds to CircleCI.

This commit rewrites the TypeScript part of the preview server that
handles converting build artifact into hosted previews of the docs.

aio/aio-builds-setup/dockerbuild/scripts-js/lib/common/circle-ci-api.ts

@@ -0,0 +1,90 @@
+// Imports
+import fetch from 'node-fetch';
+import {assertNotMissingOrEmpty} from './utils';
+
+// Constants
+const CIRCLE_CI_API_URL = 'https://circleci.com/api/v1.1/project/github';
+
+// Interfaces - Types
+export interface ArtifactInfo {
+  path: string;
+  pretty_path: string;
+  node_index: number;
+  url: string;
+}
+
+export type ArtifactResponse = ArtifactInfo[];
+
+export interface BuildInfo {
+  reponame: string;
+  failed: boolean;
+  branch: string;
+  username: string;
+  build_num: number;
+  has_artifacts: boolean;
+  outcome: string; // e.g. 'success'
+  vcs_revision: string; // HEAD SHA
+  // there are other fields but they are not used in this code
+}
+
+/**
+ * A Helper that can interact with the CircleCI API.
+ */
+export class CircleCiApi {
+
+  private tokenParam = `circle-token=${this.circleCiToken}`;
+
+  /**
+   * Construct a helper that can interact with the CircleCI REST API.
+   * @param githubOrg The Github organisation whose repos we want to access in CircleCI (e.g. angular).
+   * @param githubRepo The Github repo whose builds we want to access in CircleCI (e.g. angular).
+   * @param circleCiToken The CircleCI API access token (secret).
+   */
+  constructor(
+    private githubOrg: string,
+    private githubRepo: string,
+    private circleCiToken: string,
+  ) {
+    assertNotMissingOrEmpty('githubOrg', githubOrg);
+    assertNotMissingOrEmpty('githubRepo', githubRepo);
+    assertNotMissingOrEmpty('circleCiToken', circleCiToken);
+  }
+
+  /**
+   * Get the info for a build from the CircleCI API
+   * @param buildNumber The CircleCI build number that generated the artifact.
+   * @returns A promise to the info about the build
+   */
+  public async getBuildInfo(buildNumber: number) {
+    try {
+      const baseUrl = `${CIRCLE_CI_API_URL}/${this.githubOrg}/${this.githubRepo}/${buildNumber}`;
+      const response = await fetch(`${baseUrl}?${this.tokenParam}`);
+      if (response.status !== 200) {
+        throw new Error(`${baseUrl}: ${response.status} - ${response.statusText}`);
+      }
+      return response.json<BuildInfo>();
+    } catch (error) {
+        throw new Error(`CircleCI build info request failed (${error.message})`);
+    }
+  }
+
+  /**
+   * Query the CircleCI API to get a URL for a specified artifact from a specified build.
+   * @param artifactPath The path, within the build to the artifact.
+   * @returns A promise to the URL that can be requested to download the actual build artifact file.
+   */
+  public async getBuildArtifactUrl(buildNumber: number, artifactPath: string) {
+    const baseUrl = `${CIRCLE_CI_API_URL}/${this.githubOrg}/${this.githubRepo}/${buildNumber}`;
+    try {
+      const response = await fetch(`${baseUrl}/artifacts?${this.tokenParam}`);
+      const artifacts = await response.json<ArtifactResponse>();
+      const artifact = artifacts.find(item => item.path === artifactPath);
+      if (!artifact) {
+        throw new Error(`Missing artifact (${artifactPath}) for CircleCI build: ${buildNumber}`);
+      }
+      return artifact.url;
+    } catch (error) {
+      throw new Error(`CircleCI artifact URL request failed (${error.message})`);
+    }
+  }
+}

aio/aio-builds-setup/dockerbuild/scripts-js/lib/common/constants.ts

@@ -1,3 +1,4 @@
 // Constants
+export const AIO_DOWNLOADS_DIR = '/tmp/aio-downloads';
 export const HIDDEN_DIR_PREFIX = 'hidden--';
 export const SHORT_SHA_LEN = 7;

aio/aio-builds-setup/dockerbuild/scripts-js/lib/common/env-variables.ts

@@ -0,0 +1,19 @@
+import {getEnvVar} from './utils';
+
+export const AIO_ARTIFACT_PATH = getEnvVar('AIO_ARTIFACT_PATH');
+export const AIO_BUILDS_DIR = getEnvVar('AIO_BUILDS_DIR');
+export const AIO_GITHUB_TOKEN = getEnvVar('AIO_GITHUB_TOKEN');
+export const AIO_CIRCLE_CI_TOKEN = getEnvVar('AIO_CIRCLE_CI_TOKEN');
+export const AIO_DOMAIN_NAME = getEnvVar('AIO_DOMAIN_NAME');
+export const AIO_GITHUB_ORGANIZATION = getEnvVar('AIO_GITHUB_ORGANIZATION');
+export const AIO_GITHUB_REPO = getEnvVar('AIO_GITHUB_REPO');
+export const AIO_GITHUB_TEAM_SLUGS = getEnvVar('AIO_GITHUB_TEAM_SLUGS');
+export const AIO_NGINX_HOSTNAME = getEnvVar('AIO_NGINX_HOSTNAME');
+export const AIO_NGINX_PORT_HTTP = +getEnvVar('AIO_NGINX_PORT_HTTP');
+export const AIO_NGINX_PORT_HTTPS = +getEnvVar('AIO_NGINX_PORT_HTTPS');
+export const AIO_SIGNIFICANT_FILES_PATTERN = getEnvVar('AIO_SIGNIFICANT_FILES_PATTERN');
+export const AIO_TRUSTED_PR_LABEL = getEnvVar('AIO_TRUSTED_PR_LABEL');
+export const AIO_UPLOAD_HOSTNAME = getEnvVar('AIO_UPLOAD_HOSTNAME');
+export const AIO_UPLOAD_PORT = +getEnvVar('AIO_UPLOAD_PORT');
+export const AIO_UPLOAD_MAX_SIZE = +getEnvVar('AIO_UPLOAD_MAX_SIZE');
+export const AIO_WWW_USER = getEnvVar('AIO_WWW_USER');

aio/aio-builds-setup/dockerbuild/scripts-js/lib/common/github-api.ts

@@ -28,29 +28,17 @@ export class GithubApi {
   }
 
   // Methods - Public
-  public get<T>(pathname: string, params?: RequestParamsOrNull): Promise<T> {
+  public get<T = any>(pathname: string, params?: RequestParamsOrNull): Promise<T> {
     const path = this.buildPath(pathname, params);
     return this.request<T>('get', path);
   }
 
-  public post<T>(pathname: string, params?: RequestParamsOrNull, data?: any): Promise<T> {
+  public post<T = any>(pathname: string, params?: RequestParamsOrNull, data?: any): Promise<T> {
     const path = this.buildPath(pathname, params);
     return this.request<T>('post', path, data);
   }
 
-  // Methods - Protected
-  protected buildPath(pathname: string, params?: RequestParamsOrNull): string {
-    if (params == null) {
-      return pathname;
-    }
-
-    const search = (params === null) ? '' : this.serializeSearchParams(params);
-    const joiner = search && '?';
-
-    return `${pathname}${joiner}${search}`;
-  }
-
-  protected getPaginated<T>(pathname: string, baseParams: RequestParams = {}, currentPage: number = 0): Promise<T[]> {
+  public getPaginated<T>(pathname: string, baseParams: RequestParams = {}, currentPage: number = 0): Promise<T[]> {
     const perPage = 100;
     const params = {
       ...baseParams,
@@ -67,7 +55,19 @@ export class GithubApi {
     });
   }
 
-  protected request<T>(method: string, path: string, data: any = null): Promise<T> {
+  // Methods - Protected
+  protected buildPath(pathname: string, params?: RequestParamsOrNull) {
+    if (params == null) {
+      return pathname;
+    }
+
+    const search = (params === null) ? '' : this.serializeSearchParams(params);
+    const joiner = search && '?';
+
+    return `${pathname}${joiner}${search}`;
+  }
+
+  protected request<T>(method: string, path: string, data: any = null) {
     return new Promise<T>((resolve, reject) => {
       const options = {
         headers: {...this.requestHeaders},
@@ -81,7 +81,7 @@ export class GithubApi {
         reject(`Request to '${url}' failed (status: ${statusCode}): ${responseText}`);
       };
       const onSuccess = (responseText: string) => {
-        try { resolve(JSON.parse(responseText)); } catch (err) { reject(err); }
+        try { resolve(responseText && JSON.parse(responseText)); } catch (err) { reject(err); }
       };
       const onResponse = (res: IncomingMessage) => {
         const statusCode = res.statusCode || -1;
@@ -101,7 +101,7 @@ export class GithubApi {
     });
   }
 
-  protected serializeSearchParams(params: RequestParams): string {
+  protected serializeSearchParams(params: RequestParams) {
     return Object.keys(params).
       filter(key => params[key] != null).
       map(key => `${key}=${encodeURIComponent(String(params[key]))}`).

aio/aio-builds-setup/dockerbuild/scripts-js/lib/common/github-pull-requests.ts

@@ -1,46 +1,79 @@
-// Imports
-import {assertNotMissingOrEmpty} from '../common/utils';
+import {assert, assertNotMissingOrEmpty} from '../common/utils';
 import {GithubApi} from './github-api';
 
-// Interfaces - Types
-export interface PullRequest  {
+export interface PullRequest {
   number: number;
   user: {login: string};
   labels: {name: string}[];
 }
 
+export interface FileInfo {
+  sha: string;
+  filename: string;
+}
+
 export type PullRequestState = 'all' | 'closed' | 'open';
 
-// Classes
-export class GithubPullRequests extends GithubApi {
-  // Constructor
-  constructor(githubToken: string, protected repoSlug: string) {
-    super(githubToken);
-    assertNotMissingOrEmpty('repoSlug', repoSlug);
+/**
+ * Access pull requests on GitHub.
+ */
+export class GithubPullRequests {
+  public repoSlug: string;
+
+  /**
+   * Create an instance of this helper
+   * @param api An instance of the Github API helper.
+   * @param githubOrg The organisation on GitHub whose repo we will interrogate.
+   * @param githubRepo The repository on Github with whose PRs we will interact.
+   */
+  constructor(private api: GithubApi, githubOrg: string, githubRepo: string) {
+    assertNotMissingOrEmpty('githubOrg', githubOrg);
+    assertNotMissingOrEmpty('githubRepo', githubRepo);
+    this.repoSlug = `${githubOrg}/${githubRepo}`;
   }
 
-  // Methods - Public
-  public addComment(pr: number, body: string): Promise<void> {
-    if (!(pr > 0)) {
-      throw new Error(`Invalid PR number: ${pr}`);
-    } else if (!body) {
-      throw new Error(`Invalid or empty comment body: ${body}`);
-    }
-
-    return this.post<void>(`/repos/${this.repoSlug}/issues/${pr}/comments`, null, {body});
+  /**
+   * Post a comment on a PR.
+   * @param pr The number of the PR on which to comment.
+   * @param body The body of the comment to post.
+   * @returns A promise that resolves when the comment has been posted.
+   */
+  public addComment(pr: number, body: string) {
+    assert(pr > 0, `Invalid PR number: ${pr}`);
+    assert(!!body, `Invalid or empty comment body: ${body}`);
+    return this.api.post<any>(`/repos/${this.repoSlug}/issues/${pr}/comments`, null, {body});
   }
 
-  public fetch(pr: number): Promise<PullRequest> {
+  /**
+   * Request information about a PR.
+   * @param pr The number of the PR for which to request info.
+   * @returns A promise that is resolves with information about the specified PR.
+   */
+  public fetch(pr: number) {
+    assert(pr > 0, `Invalid PR number: ${pr}`);
     // Using the `/issues/` URL, because the `/pulls/` one does not provide labels.
-    return this.get<PullRequest>(`/repos/${this.repoSlug}/issues/${pr}`);
+    return this.api.get<PullRequest>(`/repos/${this.repoSlug}/issues/${pr}`);
   }
 
-  public fetchAll(state: PullRequestState = 'all'): Promise<PullRequest[]> {
-    console.log(`Fetching ${state} pull requests...`);
-
+  /**
+   * Request information about all PRs that match the given state.
+   * @param state Only retrieve PRs that have this state.
+   * @returns A promise that is resolved with information about the requested PRs.
+   */
+  public fetchAll(state: PullRequestState = 'all') {
     const pathname = `/repos/${this.repoSlug}/pulls`;
     const params = {state};
 
-    return this.getPaginated<PullRequest>(pathname, params);
+    return this.api.getPaginated<PullRequest>(pathname, params);
+  }
+
+  /**
+   * Request a list of files for the given PR.
+   * @param pr The number of the PR for which to request files.
+   * @returns A promise that resolves to an array of file information
+   */
+  public fetchFiles(pr: number) {
+    assert(pr > 0, `Invalid PR number: ${pr}`);
+    return this.api.get<FileInfo[]>(`/repos/${this.repoSlug}/pulls/${pr}/files`);
   }
 }

aio/aio-builds-setup/dockerbuild/scripts-js/lib/common/github-teams.ts

@@ -1,45 +1,72 @@
-// Imports
 import {assertNotMissingOrEmpty} from '../common/utils';
 import {GithubApi} from './github-api';
 
-// Interfaces - Types
-interface Team {
+export interface Team {
   id: number;
   slug: string;
 }
 
-interface TeamMembership {
+export interface TeamMembership {
   state: string;
 }
 
-// Classes
-export class GithubTeams extends GithubApi {
-  // Constructor
-  constructor(githubToken: string, protected organization: string) {
-    super(githubToken);
-    assertNotMissingOrEmpty('organization', organization);
+export class GithubTeams {
+  /**
+   * Create an instance of this helper
+   * @param api An instance of the Github API helper.
+   * @param githubOrg The organisation on GitHub whose repo we will interrogate.
+   */
+  constructor(private api: GithubApi, protected githubOrg: string) {
+    assertNotMissingOrEmpty('githubOrg', githubOrg);
   }
 
-  // Methods - Public
-  public fetchAll(): Promise<Team[]> {
-    return this.getPaginated<Team>(`/orgs/${this.organization}/teams`);
+  /**
+   * Request information about all the organisation's teams in GitHub.
+   * @returns A promise that is resolved with information about the teams.
+   */
+  public fetchAll() {
+    return this.api.getPaginated<Team>(`/orgs/${this.githubOrg}/teams`);
   }
 
-  public isMemberById(username: string, teamIds: number[]): Promise<boolean> {
-    const getMembership = (teamId: number) =>
-      this.get<TeamMembership>(`/teams/${teamId}/memberships/${username}`).
-        then(membership => membership.state === 'active').
-        catch(() => false);
-    const reduceFn = (promise: Promise<boolean>, teamId: number) =>
-      promise.then(isMember => isMember || getMembership(teamId));
+  /**
+   * Check whether the specified username is a member of the specified team.
+   * @param username The usernane to check for in the team.
+   * @param teamIds The team to check for the username.
+   * @returns a Promise that resolves to `true` if the username is a member of the team.
+   */
+  public async isMemberById(username: string, teamIds: number[]) {
 
-    return teamIds.reduce(reduceFn, Promise.resolve(false));
+    const getMembership = async (teamId: number) => {
+      try {
+        const {state} = await this.api.get<TeamMembership>(`/teams/${teamId}/memberships/${username}`);
+        return state === 'active';
+      } catch (error) {
+        return false;
+      }
+    };
+
+    for (const teamId of teamIds) {
+      if (await getMembership(teamId)) {
+        return true;
+      }
+    }
+
+    return false;
   }
 
-  public isMemberBySlug(username: string, teamSlugs: string[]): Promise<boolean> {
-    return this.fetchAll().
-      then(teams => teams.filter(team => teamSlugs.includes(team.slug)).map(team => team.id)).
-      then(teamIds => this.isMemberById(username, teamIds)).
-      catch(() => false);
+  /**
+   * Check whether the given username is a member of the teams specified by the team slugs.
+   * @param username The username to check for in the teams.
+   * @param teamSlugs A collection of slugs that represent the teams to check for the the username.
+   * @returns a Promise that resolves to `true` if the usernane is a member of at least one of the specified teams.
+   */
+  public async isMemberBySlug(username: string, teamSlugs: string[]) {
+    try {
+      const teams = await this.fetchAll();
+      const teamIds = teams.filter(team => teamSlugs.includes(team.slug)).map(team => team.id);
+      return await this.isMemberById(username, teamIds);
+    } catch (error) {
+      return false;
+    }
   }
 }

aio/aio-builds-setup/dockerbuild/scripts-js/lib/common/utils.ts

@@ -1,16 +1,74 @@
-// Functions
-export const assertNotMissingOrEmpty = (name: string, value: string | null | undefined) => {
+import {basename, resolve as resolvePath} from 'path';
+import {SHORT_SHA_LEN} from './constants';
+
+/**
+ * Shorten a SHA to make it more readable
+ * @param sha The SHA to shorten.
+ */
+export function computeShortSha(sha: string) {
+  return sha.substr(0, SHORT_SHA_LEN);
+}
+
+/**
+ * Compute the path for a downloaded artifact file.
+ * @param downloadsDir The directory where artifacts are downloaded
+ * @param pr The PR associated with this artifact.
+ * @param sha The SHA associated with the build for this artifact.
+ * @param artifactPath The path to the artifact on CircleCI.
+ * @returns The fully resolved location for the specified downloaded artifact.
+ */
+export function computeArtifactDownloadPath(downloadsDir: string, pr: number, sha: string, artifactPath: string) {
+  return resolvePath(downloadsDir, `${pr}-${computeShortSha(sha)}-${basename(artifactPath)}`);
+}
+
+/**
+ * Extract the PR number and latest commit SHA from a downloaded file path.
+ * @param downloadPath the path to the downloaded file.
+ * @returns An object whose keys are the PR and SHA extracted from the file path.
+ */
+export function getPrInfoFromDownloadPath(downloadPath: string) {
+  const file = basename(downloadPath);
+  const [pr, sha] = file.split('-');
+  return {pr: +pr, sha};
+}
+
+/**
+ * Assert that a value is true.
+ * @param value The value to assert.
+ * @param message The message if the value is not true.
+ */
+export function assert(value: boolean, message: string) {
   if (!value) {
-    throw new Error(`Missing or empty required parameter '${name}'!`);
+    throw new Error(message);
   }
+}
+
+/**
+ * Assert that a parameter is not equal to "".
+ * @param name The name of the parameter.
+ * @param value The value of the parameter.
+ */
+export const assertNotMissingOrEmpty = (name: string, value: string | null | undefined) => {
+  assert(!!value, `Missing or empty required parameter '${name}'!`);
 };
 
+/**
+ * Get an environment variable.
+ * @param name The name of the environment variable.
+ * @param isOptional True if the variable is optional.
+ * @returns The value of the variable or "" if it is optional and falsy.
+ * @throws `Error` if the variable is falsy and not optional.
+ */
 export const getEnvVar = (name: string, isOptional = false): string => {
   const value = process.env[name];
 
   if (!isOptional && !value) {
-    console.error(`ERROR: Missing required environment variable '${name}'!`);
-    process.exit(1);
+    try {
+     throw new Error(`ERROR: Missing required environment variable '${name}'!`);
+    } catch (error) {
+      console.error(error.stack);
+      process.exit(1);
+    }
   }
 
   return value || '';