fix: process env usage with doc (#715)

README.md

@@ -39,9 +39,7 @@ An example is available at [acalanetwork.github.io/chopsticks](https://acalanetw
 
 ## Environment Variables
 
-- `PORT`: Set port for Chopsticks to listen on, default is `8000`
-- `LOG_LEVEL`: Set log level, default is `info`. Available options: `trace`, `debug`, `info`, `warn`, `error`
-- `VERBOSE_LOG`: If set, do not truncating log messages
+For chopsticks CLI, you can find the full list of available environment variables [here](https://acalanetwork.github.io/chopsticks/docs/core/README.html#environment).
 
 ## Install
 

packages/chopsticks/src/cli.ts

@@ -4,7 +4,7 @@ import _ from 'lodash'
 import yargs from 'yargs'
 import type { MiddlewareFunction } from 'yargs'
 
-import { Blockchain, connectParachains, connectVertical } from '@acala-network/chopsticks-core'
+import { Blockchain, connectParachains, connectVertical, environment } from '@acala-network/chopsticks-core'
 import { configSchema, fetchConfig, getYargsOptions } from './schema/index.js'
 import { pluginExtendCli } from './plugins/index.js'
 import { setupWithServer } from './index.js'
@@ -15,8 +15,8 @@ const processArgv: MiddlewareFunction<{ config?: string; port?: number }> = asyn
   if (argv.config) {
     Object.assign(argv, _.defaults(argv, await fetchConfig(argv.config)))
   }
-  if (process.env.PORT) {
-    argv.port = Number(process.env.PORT)
+  if (environment.PORT) {
+    argv.port = Number(environment.PORT)
   }
 }
 
@@ -65,7 +65,7 @@ const commands = yargs(hideBin(process.argv))
       }
 
       if (parachains.length > 1) {
-        await connectParachains(parachains)
+        await connectParachains(parachains, environment.DISABLE_AUTO_HRMP)
       }
 
       if (argv.relaychain) {
@@ -89,7 +89,7 @@ const commands = yargs(hideBin(process.argv))
   .usage('Usage: $0 <command> [options]')
   .example('$0', '-c acala')
 
-if (!process.env.DISABLE_PLUGINS) {
+if (!environment.DISABLE_PLUGINS) {
   pluginExtendCli(
     commands.config(
       'config',

packages/chopsticks/src/plugins/index.ts

@@ -1,4 +1,4 @@
-import { Handlers } from '@acala-network/chopsticks-core'
+import { Handlers, environment } from '@acala-network/chopsticks-core'
 import { lstatSync, readdirSync } from 'fs'
 import _ from 'lodash'
 import type { Argv } from 'yargs'
@@ -20,7 +20,7 @@ export const rpcPluginMethods = plugins
   .map((name) => `dev_${_.camelCase(name)}`)
 
 export const loadRpcPlugin = async (method: string) => {
-  if (process.env.DISABLE_PLUGINS) {
+  if (environment.DISABLE_PLUGINS) {
     return undefined
   }
   if (rpcPluginHandlers[method]) return rpcPluginHandlers[method]

packages/chopsticks/src/utils/tunnel.ts

@@ -1,14 +1,15 @@
 import { bootstrap } from 'global-agent'
 bootstrap()
+import { environment } from '@acala-network/chopsticks-core'
 import npmConf from '@pnpm/npm-conf'
 
 const npmConfig = npmConf().config
 
 global.GLOBAL_AGENT.HTTP_PROXY =
-  process.env.HTTP_PROXY ||
-  process.env.http_proxy ||
-  process.env.HTTPS_PROXY ||
-  process.env.https_proxy ||
+  environment.HTTP_PROXY ||
+  environment.http_proxy ||
+  environment.HTTPS_PROXY ||
+  environment.https_proxy ||
   npmConfig.get('proxy') ||
   npmConfig.get('https-proxy') ||
   global.GLOBAL_AGENT.HTTP_PROXY

packages/core/src/env.ts

@@ -0,0 +1,50 @@
+import * as z from 'zod'
+
+export const environmentSchema = z.object({
+  /**
+   * Disable auto HRMP on setup. Default is `false`.
+   */
+  DISABLE_AUTO_HRMP: z
+    .enum(['true', 'false'])
+    .default('false')
+    .transform((v) => v === 'true'),
+  /**
+   * Set port for Chopsticks to listen on, default is `8000`.
+   */
+  PORT: z.string().optional(),
+  /**
+   * Disable plugins for faster startup. Default is `false`.
+   */
+  DISABLE_PLUGINS: z
+    .enum(['true', 'false'])
+    .default('false')
+    .transform((v) => v === 'true'),
+  HTTP_PROXY: z.string().optional(),
+  http_proxy: z.string().optional(),
+  HTTPS_PROXY: z.string().optional(),
+  https_proxy: z.string().optional(),
+  /**
+   * Chopsticks log level, "fatal" | "error" | "warn" | "info" | "debug" | "trace".
+   * Default is "info".
+   */
+  LOG_LEVEL: z.enum(['fatal', 'error', 'warn', 'info', 'debug', 'trace']).default('info'),
+  /**
+   * Don't truncate log messages, show full log output. Default is `false`.
+   */
+  VERBOSE_LOG: z
+    .enum(['true', 'false'])
+    .default('false')
+    .transform((v) => v === 'true'),
+  /**
+   * Don't log objects. Default is `false`.
+   */
+  LOG_COMPACT: z
+    .enum(['true', 'false'])
+    .default('false')
+    .transform((v) => v === 'true'),
+})
+
+/**
+ * Environment variables available for users
+ */
+export const environment = environmentSchema.parse(typeof process === 'object' ? process.env : {})

packages/core/src/index.ts

@@ -41,6 +41,7 @@ export * from './blockchain/block-builder.js'
 export * from './blockchain/txpool.js'
 export * from './blockchain/storage-layer.js'
 export * from './blockchain/head-state.js'
+export * from './env.js'
 export * from './utils/index.js'
 export * from './wasm-executor/index.js'
 export * from './schema/index.js'

packages/core/src/logger.ts

@@ -1,15 +1,14 @@
 import { pino } from 'pino'
 
-const level = (typeof process === 'object' && process.env.LOG_LEVEL) || 'info'
-const hideObject = (typeof process === 'object' && !!process.env.LOG_COMPACT) || false
+import { environment } from './env.js'
 
 export const pinoLogger = pino({
-  level,
+  level: environment.LOG_LEVEL,
   transport: {
     target: 'pino-pretty',
     options: {
       ignore: 'pid,hostname',
-      hideObject,
+      hideObject: environment.LOG_COMPACT,
     },
   },
 })
@@ -19,7 +18,7 @@ export const defaultLogger = pinoLogger.child({ app: 'chopsticks' })
 const innerTruncate =
   (level = 0) =>
   (val: any) => {
-    const verboseLog = typeof process === 'object' ? !!process.env.VERBOSE_LOG : false
+    const verboseLog = environment.VERBOSE_LOG
     const levelLimit = verboseLog ? 10 : 5
     if (val == null) {
       return val

packages/core/src/xcm/horizontal.ts

@@ -5,7 +5,7 @@ import { Blockchain } from '../blockchain/index.js'
 import { compactHex } from '../utils/index.js'
 import { xcmLogger } from './index.js'
 
-export const connectHorizontal = async (parachains: Record<number, Blockchain>) => {
+export const connectHorizontal = async (parachains: Record<number, Blockchain>, disableAutoHrmp = false) => {
   for (const [id, chain] of Object.entries(parachains)) {
     const meta = await chain.head.meta
 
@@ -32,7 +32,7 @@ export const connectHorizontal = async (parachains: Record<number, Blockchain>)
     })
 
     const hrmpHeads = await chain.head.read('BTreeMap<u32, H256>', meta.query.parachainSystem.lastHrmpMqcHeads)
-    if (hrmpHeads && !process.env.DISABLE_AUTO_HRMP) {
+    if (hrmpHeads && !disableAutoHrmp) {
       const existingChannels = Array.from(hrmpHeads.keys()).map((x) => x.toNumber())
       for (const paraId of Object.keys(parachains).filter((x) => x !== id)) {
         if (!existingChannels.includes(Number(paraId))) {

packages/core/src/xcm/index.ts

@@ -15,15 +15,15 @@ export const connectVertical = async (relaychain: Blockchain, parachain: Blockch
   )
 }
 
-export const connectParachains = async (parachains: Blockchain[]) => {
+export const connectParachains = async (parachains: Blockchain[], disableAutoHrmp = false) => {
   const list: Record<number, Blockchain> = {}
 
   for (const chain of parachains) {
     const paraId = await getParaId(chain)
     list[paraId.toNumber()] = chain
   }
 
-  await connectHorizontal(list)
+  await connectHorizontal(list, disableAutoHrmp)
 
   xcmLogger.info(`Connected parachains [${Object.keys(list)}]`)
 }

packages/e2e/src/environment.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'vitest'
+import { environment, environmentSchema } from '@acala-network/chopsticks-core'
+
+describe('environment', () => {
+  it('defaults are correct', async () => {
+    expect(environment).toMatchObject({
+      DISABLE_AUTO_HRMP: false,
+      DISABLE_PLUGINS: false,
+      VERBOSE_LOG: false,
+      LOG_COMPACT: false,
+    })
+  })
+
+  it('parsing is correct', async () => {
+    process.env = {
+      DISABLE_AUTO_HRMP: 'true',
+      PORT: '8001',
+      DISABLE_PLUGINS: 'false',
+      HTTP_PROXY: 'http://localhost:8080',
+      HTTPS_PROXY: 'https://localhost:8080',
+      LOG_LEVEL: 'info',
+      VERBOSE_LOG: 'false',
+      LOG_COMPACT: 'true',
+    }
+    expect(environmentSchema.parse(process.env)).toMatchObject({
+      DISABLE_AUTO_HRMP: true,
+      PORT: '8001',
+      DISABLE_PLUGINS: false,
+      HTTP_PROXY: 'http://localhost:8080',
+      HTTPS_PROXY: 'https://localhost:8080',
+      LOG_LEVEL: 'info',
+      VERBOSE_LOG: false,
+      LOG_COMPACT: true,
+    })
+  })
+})

packages/utils/src/index.ts

@@ -5,6 +5,7 @@ import {
   connectParachains,
   connectVertical,
   defaultLogger,
+  environment,
   fetchConfig,
   setupWithServer,
 } from '@acala-network/chopsticks'
@@ -143,7 +144,7 @@ export const setupNetworks = async (networkOptions: Partial<Record<string, Confi
 
   const parachainList = Object.values(parachains).map((i) => i.chain)
   if (parachainList.length > 0) {
-    await connectParachains(parachainList)
+    await connectParachains(parachainList, environment.DISABLE_AUTO_HRMP)
   }
 
   if (wasmOverriden) {