@metaplay/metaplay-auth 1.6.1 → 1.7.0

package/index.ts

@@ -2,7 +2,6 @@
 import { Command } from 'commander'
 import { randomBytes } from 'crypto'
 import Docker from 'dockerode'
-import { existsSync } from 'fs'
 import { writeFile, unlink } from 'fs/promises'
 import { tmpdir } from 'os'
 import { exit } from 'process'
@@ -19,11 +18,8 @@ import { TargetEnvironment } from './src/targetenvironment.js'
 import { pathJoin, isValidFQDN, executeCommand, removeTrailingSlash, fetchHelmChartVersions, resolveBestMatchingVersion } from './src/utils.js'
 import { PACKAGE_VERSION } from './src/version.js'
 
-/**
- * Base URL of StackAPI infra to use -- defaults to p1.metaplay.io. Override with the global --stack-api flag.
- * Note: The dynamic `kubeconfig`s generated by `metaplay-auth` override this with '--stack-api <url>' flag.
- */
-let defaultStackApiBaseUrl = 'https://infra.p1.metaplay.io/stackapi'
+/** Stack API base url override, specified with the '--stack-api' global flag. */
+let stackApiBaseUrlOverride: string | undefined
 
 /**
  * Resolve a TargetEnvironment from a fully-qualified domain name (eg, 'idler-develop.p1.metaplay.io').
@@ -32,9 +28,13 @@ let defaultStackApiBaseUrl = 'https://infra.p1.metaplay.io/stackapi'
  * @returns The TargetEnvironment instance needed to operate with the environment.
  */
 function resolveTargetEnvironmentFromFQDN(tokens: TokenSet, environmentDomain: string): TargetEnvironment {
+  // Default p1.metaplay.io StackAPI base URL. This code path is deprecated so not a problem to do this here.
+  const defaultStackApiBaseUrl = 'https://infra.p1.metaplay.io/stackapi'
+
   // Extract the humanId from the domain, eg: 'idler-develop.p1.metaplay.io' -> 'idler-develop'
+  // When using FQDNs, we assume the target is on p1.metaplay.io -- the only stack supported with FQDNs.
   const humanId = environmentDomain.split('.')[0]
-  return new TargetEnvironment(tokens.access_token, humanId, defaultStackApiBaseUrl) // \todo We could probably infer the stack API URL from the domain?
+  return new TargetEnvironment(tokens.access_token, humanId, defaultStackApiBaseUrl)
 }
 
 /**
@@ -67,7 +67,18 @@ interface PortalEnvironmentInfo {
   // \todo Make field mandatory when portal returns valid values
   human_id?: string
 
-  // \todo Add stackapi url that the portal should return?
+  /**
+   * Domain that the environment uses, eg, 'metaplay.games'. Old environments use 'p1.metaplay.io'.
+   * This domain is where the clients connect to, the one that JWKS signatures use, and so on.
+   */
+  env_domain?: string
+
+  /**
+   * Domain of the infra stack where the environment is provisioned, eg, 'p1.metaplay.io'.
+   * Note that the environment does not exist on the infra stack if it hasn't been created yet,
+   * but the decision can still have been made where to put it.
+   */
+  stack_domain?: string
 }
 
 /**
@@ -79,7 +90,7 @@ interface PortalEnvironmentInfo {
  * @returns The portal's information about the environment.
  */
 // eslint-disable-next-line @typescript-eslint/max-params
-async function fetchManagedEnvironmentInfo(
+async function fetchManagedEnvironmentInfoWithSlugs(
   tokens: TokenSet,
   organization: string,
   project: string,
@@ -102,7 +113,35 @@ async function fetchManagedEnvironmentInfo(
   }
 
   // \todo Validate response?
-  return (await response.json()) as PortalEnvironmentInfo
+  const portalEnvInfo = (await response.json()) as PortalEnvironmentInfo
+  logger.debug(`Portal returned environment info: ${JSON.stringify(portalEnvInfo, undefined, 2)}`)
+  return portalEnvInfo
+}
+
+async function fetchManageEnvironmentInfoWithHumanId(tokens: TokenSet, humanId: string): Promise<PortalEnvironmentInfo> {
+  const url = `${portalBaseUrl}/api/v1/environments?human_id=${humanId}`
+  logger.debug(`Getting environment information from portal: ${url}...`)
+  const response = await fetch(url, {
+    method: 'GET',
+    headers: {
+      Authorization: `Bearer ${tokens.access_token}`,
+      'Content-Type': 'application/json',
+    },
+  })
+
+  // Throw on server errors (eg, forbidden)
+  if (!response.ok) {
+    const errorData = await response.json()
+    throw new Error(`Failed to fetch environment details with error ${response.status}: ${JSON.stringify(errorData)}`)
+  }
+
+  // Return the result
+  const portalEnvInfos = (await response.json()) as PortalEnvironmentInfo[]
+  logger.debug(`Portal returned environment infos: ${JSON.stringify(portalEnvInfos, undefined, 2)}`)
+  if (portalEnvInfos.length === 0) {
+    throw new Error(`Failed to fetch details from portal for environment ${humanId}: no matching environment found`)
+  }
+  return portalEnvInfos[0]
 }
 
 /**
@@ -123,19 +162,33 @@ async function resolveTargetEnvironmentFromSlugs(
   environment: string
 ): Promise<TargetEnvironment> {
   // Fetch the deployment information from the portal
-  const portalEnvInfo = await fetchManagedEnvironmentInfo(tokens, organization, project, environment)
+  const portalEnvInfo = await fetchManagedEnvironmentInfoWithSlugs(tokens, organization, project, environment)
   const humanId = portalEnvInfo.human_id
   if (!humanId) {
     throw new Error(`Portal returned missing human_id for environment '${organization}-${project}-${environment}'`)
   }
 
-  return new TargetEnvironment(tokens.access_token, humanId, defaultStackApiBaseUrl)
+  const stackDomain = portalEnvInfo.stack_domain
+  if (!stackDomain) {
+    throw new Error(`The environment ${portalEnvInfo.human_id} has not been provisioned to any infra stack (environment.stack_domain is empty).`)
+  }
+
+  return new TargetEnvironment(tokens.access_token, humanId, `https://infra.${stackDomain}/stackapi`)
 }
 
 async function resolveTargetEnvironmentHumanId(tokens: TokenSet, humanId: string): Promise<TargetEnvironment> {
-  // \todo Validate that the target environment exists?
+  // Resolve the StackAPI base URL to use: prefer the --stack-api override, or if not defined, fetch it from the portal
+  let stackApiBaseUrl = stackApiBaseUrlOverride
+  if (!stackApiBaseUrl) {
+    const portalEnvInfo = await fetchManageEnvironmentInfoWithHumanId(tokens, humanId)
+    if (!portalEnvInfo.stack_domain) {
+      throw new Error(`The environment ${portalEnvInfo.human_id} has not been provisioned to any infra stack (environment.stack_domain is empty).`)
+    }
+    stackApiBaseUrl = `https://infra.${portalEnvInfo.stack_domain}/stackapi`
+  }
 
-  return new TargetEnvironment(tokens.access_token, humanId, defaultStackApiBaseUrl)
+
+  return new TargetEnvironment(tokens.access_token, humanId, stackApiBaseUrl)
 }
 
 /**
@@ -156,6 +209,7 @@ async function resolveTargetEnvironment(
     // - Tuple of '<organization>-<project>-<environment>' slugs (eg, 'metaplay-idler-develop')
     // - Stable humanId, eg, 'delicious-elephant'
     if (isValidFQDN(address)) {
+      console.warn('Using the FQDN to specify target environment is deprecated. Use the "<organization>-<project>-<environment>" slugs instead.')
       return resolveTargetEnvironmentFromFQDN(tokens, address)
     } else {
       const parts = address.split('-')
@@ -171,9 +225,7 @@ async function resolveTargetEnvironment(
     }
   } else if (options.organization && options.project && options.environment) {
     // Parse tuple from command-line options (output to stderr to avoid messing up '$(eval metaplay-auth ... --format env)' invocations
-    console.warn(
-      `Warning: Specifying the target environment with -o (--organization), -p (--project), and -e (--environment) is deprecated! Use the '${options.organization}-${options.project}-${options.environment}' syntax instead.`
-    )
+    console.warn(`Warning: Specifying the target environment with -o (--organization), -p (--project), and -e (--environment) is deprecated! Use the '${options.organization}-${options.project}-${options.environment}' syntax instead.`)
     return await resolveTargetEnvironmentFromSlugs(tokens, options.organization, options.project, options.environment)
   } else {
     throw new Error('Could not determine target environment from arguments: You need to specify either an environment FQDN or an organization, project, and environment. Run this command with --help flag for more information.')
@@ -205,7 +257,7 @@ program
 
     // Store the stack API base URL for accessing globally
     if (opts.stackApi) {
-      defaultStackApiBaseUrl = opts.stackApi as string
+      stackApiBaseUrlOverride = opts.stackApi as string
     }
   })
 
@@ -744,7 +796,7 @@ program
         // - Unknown, error out!
         const helmChartVersionSpec = options.helmChartVersion ?? imageLabels['io.metaplay.default_server_chart_version']
         if (!options.helmChartVersion) {
-          console.warn('You should specify the Helm chart version with --helm-chart-version=<version>!')
+          console.warn('Warning: You should specify the Helm chart version with --helm-chart-version=<version>!')
         }
         if (!helmChartVersionSpec) {
           throw new Error('No Helm chart version defined. With pre-R28 SDK versions, you must specify the Helm chart version explicitly with --helm-chart-version=<version>.')
@@ -817,7 +869,7 @@ program
               ? ` from repo ${helmChartRepo}`
               : ''
           console.log(
-            `Game server deployed to ${gameserver} with tag ${imageTag} using chart version ${resolvedHelmChartVersion}${testingRepoSuffix}!`
+            `Game server deployed to ${gameserver} with tag ${imageTag} using chart version ${resolvedHelmChartVersion}${testingRepoSuffix}`
           )
         } finally {
           // Remove temporary kubeconfig file
@@ -830,12 +882,7 @@ program
           kubeconfig.loadFromString(kubeconfigPayload)
 
           console.log('Validating game server deployment...')
-          const exitCode = await checkGameServerDeployment(
-            envInfo.deployment.kubernetes_namespace,
-            kubeconfig,
-            imageTag
-          )
-          exit(exitCode)
+          await checkGameServerDeployment(envInfo, kubeconfig, imageTag)
         } catch (error) {
           const errMessage = error instanceof Error ? error.message : String(error)
           console.error(`Failed to resolve game server deployment status: ${errMessage}`)
@@ -867,7 +914,6 @@ program
       try {
         logger.debug('Get environment info')
         const envInfo = await targetEnv.getEnvironmentDetails()
-        const kubernetesNamespace = envInfo.deployment.kubernetes_namespace
 
         // Load kubeconfig from file and throw error if validation fails.
         logger.debug('Get kubeconfig')
@@ -883,10 +929,9 @@ program
         }
 
         // Run the checks and exit with success/failure exitCode depending on result
-        console.log(`Validating game server deployment in namespace ${kubernetesNamespace}`)
+        console.log(`Validating game server deployment`)
         // \todo Get requiredImageTag from the Helm chart
-        const exitCode = await checkGameServerDeployment(kubernetesNamespace, kubeconfig, /* requiredImageTag: */ null)
-        exit(exitCode)
+        await checkGameServerDeployment(envInfo, kubeconfig, /* requiredImageTag: */ null)
       } catch (error: any) {
         console.error(`Failed to check deployment status: ${error.message}`)
         exit(1)
@@ -894,52 +939,6 @@ program
     }
   )
 
-program
-  .command('check-deployment')
-  .description('[deprecated] check that a game server was successfully deployed, or print out useful error messages in case of failure')
-  .argument('[namespace]', 'kubernetes namespace of the deployment')
-  .action(async (namespace: string) => {
-    console.error(
-      'DEPRECATED! Use the "metaplay-auth check-server-status [gameserver]" command instead! This command will be removed soon.'
-    )
-
-    try {
-      if (!namespace) {
-        throw new Error('Must specify value for argument "namespace"')
-      }
-
-      // Check that the KUBECONFIG environment variable exists
-      const kubeconfigPath = process.env.KUBECONFIG
-      if (!kubeconfigPath) {
-        throw new Error('The KUBECONFIG environment variable must be specified')
-      }
-
-      // Check that the kubeconfig file exists
-      if (!existsSync(kubeconfigPath)) {
-        throw new Error(`The environment variable KUBECONFIG points to a file '${kubeconfigPath}' that doesn't exist`)
-      }
-
-      // Create Kubernetes API instance (with default kubeconfig)
-      const kubeconfig = new KubeConfig()
-      // Load kubeconfig from file and throw error if validation fails.
-      try {
-        kubeconfig.loadFromFile(kubeconfigPath)
-      } catch (error) {
-        const errMessage = error instanceof Error ? error.message : String(error)
-        throw new Error(`Failed to load or validate kubeconfig: ${errMessage}`)
-      }
-
-      // Run the checks and exit with success/failure exitCode depending on result
-      console.log(`Validating game server deployment in namespace ${namespace}`)
-      // \todo Get requiredImageTag from the Helm chart
-      const exitCode = await checkGameServerDeployment(namespace, kubeconfig, /* requiredImageTag: */ null)
-      exit(exitCode)
-    } catch (error: any) {
-      console.error(`Failed to check deployment status: ${error.message}`)
-      exit(1)
-    }
-  })
-
 program
   .command('debug-server')
   .description('run an ephemeral debug container against a game server pod running in the cloud')

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@metaplay/metaplay-auth",
   "description": "Utility CLI for authenticating with the Metaplay Auth and making authenticated calls to infrastructure endpoints.",
-  "version": "1.6.1",
+  "version": "1.7.0",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://metaplay.io",
@@ -17,28 +17,28 @@
   },
   "devDependencies": {
     "@metaplay/eslint-config": "workspace:*",
-    "@types/dockerode": "^3.3.31",
-    "@types/express": "^4.17.21",
-    "@types/js-yaml": "^4.0.9",
-    "@types/jsonwebtoken": "^9.0.6",
-    "@types/jwk-to-pem": "^2.0.3",
-    "@types/node": "^20.16.1",
-    "@types/semver": "^7.5.8",
-    "esbuild": "^0.23.1",
-    "tsx": "^4.19.0",
-    "typescript": "5.5.4",
-    "vitest": "^2.0.5",
-    "@aws-sdk/client-ecr": "^3.645.0",
-    "@kubernetes/client-node": "^1.0.0-rc6",
-    "@ory/client": "^1.14.5",
-    "commander": "^12.1.0",
-    "dockerode": "^4.0.2",
-    "h3": "^1.12.0",
-    "js-yaml": "^4.1.0",
-    "jsonwebtoken": "^9.0.2",
-    "jwk-to-pem": "^2.0.6",
-    "open": "^8.4.2",
-    "semver": "^7.6.3",
-    "tslog": "^4.9.3"
+    "@types/dockerode": "3.3.31",
+    "@types/express": "4.17.21",
+    "@types/js-yaml": "4.0.9",
+    "@types/jsonwebtoken": "9.0.7",
+    "@types/jwk-to-pem": "2.0.3",
+    "@types/node": "20.16.1",
+    "@types/semver": "7.5.8",
+    "esbuild": "0.24.0",
+    "tsx": "4.19.1",
+    "typescript": "5.6.2",
+    "vitest": "2.1.1",
+    "@aws-sdk/client-ecr": "3.654.0",
+    "@kubernetes/client-node": "1.0.0-rc6",
+    "@ory/client": "1.15.4",
+    "commander": "12.1.0",
+    "dockerode": "4.0.2",
+    "h3": "1.12.0",
+    "js-yaml": "4.1.0",
+    "jsonwebtoken": "9.0.2",
+    "jwk-to-pem": "2.0.6",
+    "open": "8.4.2",
+    "semver": "7.6.3",
+    "tslog": "4.9.3"
   }
 }

package/src/buildCommand.ts

@@ -226,8 +226,8 @@ export function registerBuildCommand(program: Command): void {
           .concat(['-t', imageTag])
           .concat(['-f', dockerFilePath])
           .concat(['--platform', platform]) // target platform(s)
-          .concat(options.buildNumber ? ['--build-arg', `BUILD_NUMBER=${options.buildNumber}`] : [])
-          .concat(options.commitId ? ['--build-arg', `COMMIT_ID=${options.commitId}`] : [])
+          .concat(buildNumber ? ['--build-arg', `BUILD_NUMBER=${buildNumber}`] : [])
+          .concat(commitId ? ['--build-arg', `COMMIT_ID=${commitId}`] : [])
           .concat(['--build-arg', `SDK_ROOT=${sdkRootPath}`])
           .concat(['--build-arg', `PROJECT_ROOT=${projectRootPath}`])
           .concat(['--build-arg', `SHARED_CODE_DIR=${options.sharedCodeDir.replaceAll('\\', '/')}`]) // pass relative-to-project-root dir

package/src/deployment.ts

@@ -2,7 +2,8 @@ import { unlink, writeFile } from 'fs/promises'
 import os from 'os'
 import path from 'path'
 import { exit } from 'process'
-import { TargetEnvironment } from 'targetenvironment.js'
+import { EnvironmentDetails, TargetEnvironment } from 'targetenvironment.js'
+import * as net from 'net'
 
 import {
   KubeConfig,
@@ -273,8 +274,8 @@ function resolvePodStatus(pod: V1Pod, requiredImageTag: string | null): GameServ
     const podImageTag = resolvePodGameServerImageTag(pod)
     if (podImageTag !== requiredImageTag) {
       return {
-        phase: GameServerPodPhase.Unknown,
-        message: `Image tag is not (yet?) updated. Pod image is ${podImageTag ?? 'unknown'}, expecting ${requiredImageTag}.`,
+        phase: GameServerPodPhase.Pending,
+        message: `Pod has old image tag ${podImageTag ?? 'unknown'}, expecting ${requiredImageTag}.`,
       }
     }
   }
@@ -372,17 +373,24 @@ function allPodsInPhase(podStatuses: GameServerPodStatus[], phase: GameServerPod
   return podStatuses.every((status) => status.phase === phase)
 }
 
-export async function checkGameServerDeployment(
+/**
+ * Wait for the game server Kubernetes pods to reach their ready state,
+ * or throw an error on timeout.
+ * @param namespace Kubernetes namespace where the pods are deployed.
+ * @param kubeconfig Kubeconfig to use to connect to the cluster.
+ * @param requiredImageTag Image tag the the pods should be using (or null if any is accepted).
+ */
+export async function waitForGameServerPodsToBeReady(
   namespace: string,
   kubeconfig: KubeConfig,
   requiredImageTag: string | null
-): Promise<number> {
-  const k8sApi = kubeconfig.makeApiClient(CoreV1Api)
+): Promise<void> {
+  // Try for 3 min before giving up
+  const timeoutAt = Date.now() + 3 * 60 * 1000
 
-  // Figure out when to stop
-  const startTime = Date.now()
-  const timeoutAt = startTime + 1 * 60 * 1000 // 5min
+  const k8sApi = kubeconfig.makeApiClient(CoreV1Api)
 
+  // Wait for the Kubernetes pods to be ready (with the desired image).
   while (true) {
     // Check pod states
     const pods = await fetchGameServerPods(k8sApi, namespace)
@@ -403,7 +411,7 @@ export async function checkGameServerDeployment(
           const suffix = status.phase !== GameServerPodPhase.Ready ? ` -- ${status.message}` : ''
           console.log(`  ${pods[ndx].metadata?.name}: ${status.phase}${suffix}`)
         }
-        return 1
+        return
       } else if (
         anyPodsInPhase(podStatuses, GameServerPodPhase.Unknown) ||
         anyPodsInPhase(podStatuses, GameServerPodPhase.Pending) ||
@@ -417,8 +425,7 @@ export async function checkGameServerDeployment(
         }
       } else if (allPodsInPhase(podStatuses, GameServerPodPhase.Ready)) {
         console.log('Gameserver is up and ready to serve!')
-        // \todo add further readiness checks -- ping endpoint, ping dashboard, other checks?
-        return 0
+        return
       } else {
         console.log('Deployment in inconsistent state, waiting...')
         for (let ndx = 0; ndx < pods.length; ndx += 1) {
@@ -430,8 +437,7 @@ export async function checkGameServerDeployment(
     }
 
     if (Date.now() >= timeoutAt) {
-      console.log('Deployment failed! Timeout while waiting for gameserver to initialize.')
-      return 124 // timeout
+      throw new Error('Timeout while waiting for the server pods be get ready')
     }
 
     // Sleep a bit to avoid spamming the log
@@ -439,6 +445,86 @@ export async function checkGameServerDeployment(
   }
 }
 
+/**
+ * Wait until we can establish a client-simulating connection to the target
+ * game server, or a timeout happens.
+ * @param hostname Hostname of the target server to connect to.
+ * @param port Port to use for the connections (usually 9339).
+ */
+async function waitForGameServerClientEndpointToBeReady(
+  hostname: string,
+  port: number
+): Promise<void> {
+  const checkConnection = async (): Promise<boolean> => {
+      return await new Promise((resolve) => {
+          const socket = new net.Socket()
+          // Set a short timeout for each attempt
+          // Note: This does not include the DNS resolve time which can take a minute or so.
+          // \todo Consider adding a DNS resolve step before trying to connect.
+          socket.setTimeout(2000)
+
+          socket.on('connect', () => {
+              socket.destroy() // Clean up after success
+              resolve(true)
+          })
+
+          socket.on('error', () => {
+              socket.destroy() // Clean up after error
+              resolve(false)
+          })
+
+          socket.on('timeout', () => {
+              socket.destroy() // Clean up after timeout
+              resolve(false)
+          })
+
+          socket.connect(port, hostname)
+      })
+  }
+
+  // Try for 2 min before giving up
+  const timeoutAt = Date.now() + 2 * 60 * 1000
+
+  while (Date.now() < timeoutAt) {
+    const connected = await checkConnection()
+    if (connected) {
+      console.log(`Successfully connected to ${hostname}:${port}`)
+      return
+    }
+    console.log(`Retrying connection to ${hostname}:${port}...`)
+    await new Promise((resolve) => setTimeout(resolve, 1000))
+  }
+
+  throw new Error(`Timeout while trying to connect to ${hostname}:${port}.`)
+}
+
+/**
+ * Check for the status of a game server deployment:
+ * - Check that the Kubernetes resources (pods) are up and running.
+ * - Check that the server accepts connections on its client-facing port.
+ * @param envInfo Environment info of the target.
+ * @param kubeconfig Kubeconfig to use for checking the Kubernetes resources.
+ * @param requiredImageTag Expected image tag that is being deployed (or null if any is acceptable).
+ */
+export async function checkGameServerDeployment(
+  envInfo: EnvironmentDetails,
+  kubeconfig: KubeConfig,
+  requiredImageTag: string | null
+): Promise<void> {
+  // Wait for Kubernetes pods to be in ready state
+  console.log('Waiting for game server pods to be ready...')
+  await waitForGameServerPodsToBeReady(envInfo.deployment.kubernetes_namespace, kubeconfig, requiredImageTag)
+
+  // \todo Add a separate step for a DNS check on the game server
+
+  // Check that the game server accepts traffic on its client-facing endpoint
+  const clientTrafficPort = 9339 // \todo check for other ports, too?
+  console.log(`Connecting to the server at ${envInfo.deployment.server_hostname}:${clientTrafficPort}...`)
+  await waitForGameServerClientEndpointToBeReady(envInfo.deployment.server_hostname, clientTrafficPort)
+
+  // \todo add more readiness checks: dashboard, others?
+}
+
 export async function debugGameServer(targetEnv: TargetEnvironment, targetPodName?: string): Promise<void> {
   // Initialize kubeconfig for target environment
   logger.debug('Get kubeconfig')

package/src/version.ts

@@ -1 +1 @@
-export const PACKAGE_VERSION = "1.6.1"
+export const PACKAGE_VERSION = "1.7.0"