Skip to content

thrift.md

Latest commit

History

History
170 lines (120 loc) · 4.84 KB

thrift.md

File metadata and controls

170 lines (120 loc) · 4.84 KB
Raw

Thrift Code Generation

This directory contains Thrift definition files (.thrift) and the generated Node.js client code.

Overview

The IoTDB client uses Apache Thrift for RPC communication. The Thrift definitions are sourced from Apache IoTDB and are automatically synchronized weekly via GitHub Actions.

Structure

thrift/
├── client.thrift # IoTDB client RPC interface definitions
├── common.thrift # Common types shared across services
└── README.md # This file
src/thrift/generated/
├── IClientRPCService.js # Generated RPC client (JavaScript)
├── IClientRPCService.d.ts # TypeScript definitions for RPC client
├── client_types.js # Generated client types (JavaScript)
├── client_types.d.ts # TypeScript definitions for client types
├── common_types.js # Generated common types (JavaScript)
└── common_types.d.ts # TypeScript definitions for common types

TypeScript Support

As of this update, the Thrift code generator produces both:

  • JavaScript files (.js): Used at runtime
  • TypeScript declaration files (.d.ts): Provide type safety and IDE autocomplete

This dual-generation approach ensures:

  • Full TypeScript support with proper types and interfaces
  • Compatibility with the existing JavaScript runtime
  • Better developer experience with IntelliSense and type checking
  • No runtime overhead

Regenerating Thrift Code

Prerequisites

You need the Apache Thrift compiler installed:

# Ubuntu/Debian
sudo apt-get install thrift-compiler
# macOS
brew install thrift
# Verify installation
thrift --version

Manual Generation

To regenerate the Thrift client code:

npm run generate:thrift

This command:

  1. Removes existing generated .js and .d.ts files
  2. Generates new JavaScript files from thrift/client.thrift
  3. Generates TypeScript definition files (.d.ts) alongside the JavaScript

The generated files include proper TypeScript types for:

  • All Thrift structs and enums
  • RPC service methods
  • Request and response types
  • Common types from common.thrift

Automatic Updates

The GitHub Actions workflow .github/workflows/check-thrift.yml automatically:

  1. Checks for updates to Thrift definitions in Apache IoTDB master branch (weekly)
  2. Regenerates the client code with TypeScript definitions if changes are detected
  3. Creates a pull request with the updates

Usage in TypeScript

With the TypeScript definitions, you get full type safety:

import{Session}from'./client/Session';import*asttypesfrom'./thrift/generated/client_types';constsession=newSession({host: 'localhost',port: 6667});// TypeScript knows the exact types of request fieldsconstreq=newttypes.TSOpenSessionReq({client_protocol: ttypes.TSProtocolVersion.IOTDB_SERVICE_PROTOCOL_V3,username: 'root',password: 'root',zoneId: 'UTC+8',});// Full IntelliSense supportsession.executeQueryStatement('SELECT * FROM root.test');

Technical Details

Generation Command

The generator uses the official Apache Thrift compiler with the js:node,ts target:

thrift --gen js:node,ts -out src/thrift/generated thrift/client.thrift

Options:

  • js:node - Generate Node.js compatible JavaScript
  • ts - Generate TypeScript definition files
  • -out - Output directory for generated files

Dependencies

The generated code depends on:

  • thrift - Apache Thrift Node.js library
  • node-int64 - For 64-bit integer support
  • @types/thrift - TypeScript definitions for Thrift library (dev dependency)

Troubleshooting

Missing TypeScript Definitions

If you see TypeScript errors about missing types, ensure:

  1. You've run npm install to install dependencies
  2. The .d.ts files exist in src/thrift/generated/
  3. Your tsconfig.json includes the src directory

Thrift Compiler Version

The code generation requires Thrift compiler 0.14.0 or later for TypeScript support. Check your version:

thrift --version

Stale Generated Code

If you encounter issues after updating Thrift definitions:

# Clean and regenerate
rm -rf src/thrift/generated/*.js src/thrift/generated/*.d.ts
npm run generate:thrift
# Rebuild the project
npm run build

Contributing

When updating Thrift definitions:

  1. Update the .thrift files in the thrift/ directory
  2. Run npm run generate:thrift to regenerate code
  3. Run npm run build to ensure compilation succeeds
  4. Run npm test to verify tests pass
  5. Commit both the .thrift files and generated code

References