Hitokoto API

To run the Hitokoto API on your local machine, ensure you have Node.js (>=16.x) and yarn installed.

Important Requirements:

• This project uses Yarn v2. You must update your Yarn version to v1.22.4 or higher before proceeding.
• The project does not support npm, cnpm, or pnpm for dependency management.
• Redis must be installed and running as an external dependency.

Setup Steps:

1. Clone the repository: git clone https://github.com/hitokoto-osc/hitokoto-api.git your_workdir
2. Enter the directory: cd your_workdir
3. Install production dependencies: yarn workspaces focus --production
4. Initialize configuration: Copy config.example.yml to ./data/config.yml and modify it as needed.
5. Start the application: yarn start

git clone https://github.com/hitokoto-osc/hitokoto-api.git your_workdir
cd your_workdir
yarn workspaces focus --production
cp config.example.yml ./data/config.yml
yarn start

The Hitokoto API service implements graceful shutdown mechanisms to ensure child processes and HTTP workers are terminated correctly when the main process receives exit signals.

Supported Signals:

• SIGINT (Ctrl + C)
• SIGTERM (Termination request)
• uncaughtException (Unhandled errors)
• exit (Process exit event)

Shutdown Procedure:

1. The service catches the signal.
2. notifyChildProcessesExit() is called, which sends SIGTERM to all registered child processes and kills all workers in the WorkersBridge.
3. The service logs the shutdown status.
4. The process exits (with code 0 for graceful shutdowns or 1 for errors/uncaught exceptions).

Error Telemetry: If telemetry:error is enabled in the configuration and the service is not in dev mode, uncaught exceptions are captured via CaptureUncaughtException(err) and sent to Sentry before the service shuts down.

When the service starts, it follows a specific sequence of asynchronous steps within the start() function. If any step fails, the service logs the error and exits with code 1.

1. Environment Check: preStart.check() validates the environment.
2. Program Updates: preStart.checkProgramUpdates() checks for available updates.
3. Sentence Updates: updateSentencesTask() runs a task to refresh sentence data.
4. Process Registration: registerProcesses() spawns child processes based on the environment (Dev vs Prod).
5. Worker Pool: startWorkersPool() initializes the HTTP server workers.

Process Management:

• In Development mode (opts.dev), only processes marked as isDev are spawned.
• In Production mode, only processes marked as isProd are spawned.
• The service uses staticProcess().spawnProcess() to manage child processes and ProcessInteract to handle communication via receivers.

The project uses an ecosystem.config.js file (compatible with PM2/Alinode) to manage the deployment and runtime environment of the @hitokoto/api.v1 application. You can define the entry point, execution mode, and environment-specific variables such as PORT and NODE_ENV within the apps array.

module.exports = {
  apps: [
    {
      name: '@hitokoto/api.v1',
      script: './core.js',
      watch: false,
      ignore_watch: ['./data/logs'],
      interpreter: 'yarn', // absolute path to yarn ; default is node
      interpreter_args: 'start',
      exec_mode: 'fork',
      cwd: '', // the directory from which your app will be launched
      args: '', // string containing all arguments passed via CLI to script
      env_production: {
        PORT: 8000,
        NODE_ENV: 'production',
        ENABLE_NODE_LOG: 'YES',
        NODE_LOG_DIR: '~/alinode_logs',
      },
    },
  ],
}

The project uses an ecosystem.config.js file for managing application instances via PM2. This configuration defines how the @hitokoto/api.v1 service is launched, watched, and environment-configured.

Key configuration options for the application instance include:

• name: The identifier for the process (set to @hitokoto/api.v1).
• script: The entry point file (set to ./core.js).
• watch: Boolean to enable/disable file watching for restarts (set to false).
• ignore_watch: An array of paths to exclude from the watch process (e.g., ./data/logs).
• interpreter: The command used to run the script (set to yarn).
• interpreter_args: Arguments passed to the interpreter (set to start).
• exec_mode: The execution mode (e.g., fork).
• cwd: The current working directory from which the app is launched.
• args: A string of arguments passed directly to the script via CLI.
• env_production: An object containing environment variables used when running in production mode, such as PORT and NODE_ENV.

module.exports = {
  apps: [
    {
      name: '@hitokoto/api.v1',
      script: './core.js',
      watch: false,
      ignore_watch: ['./data/logs'],
      interpreter: 'yarn',
      interpreter_args: 'start',
      exec_mode: 'fork',
      cwd: '',
      args: '',
      env_production: {
        PORT: 8000,
        NODE_ENV: 'production',
      },
    },
  ],
}