Skip to content

CODE-STRUCTURE.md

Latest commit

 

History

History
201 lines (160 loc) · 5.87 KB

CODE-STRUCTURE.md

File metadata and controls

201 lines (160 loc) · 5.87 KB

tn-cli Refactoring Summary

The code is organized into following focused modules:

New Structure

1. tn-cli.py (Entry Point - ~120 lines)

  • Command-line argument parsing
  • Application initialization
  • Version handling
  • Authentication setup (token, basic, cookie)
  • Macro loading
  • Entry point that calls run() from client module

Key functions:

  • exception_hook() - Crash handler
  • if __name__ == '__main__' - Main entry point

2. utils.py (Utility Functions - ~200 lines)

  • Helper functions and data structures
  • File/image processing utilities
  • Encoding and parsing functions

Key functions:

  • dotdict - Dictionary with dot notation access
  • makeTheCard() - Pack user profile data
  • inline_image() - Create drafty image messages
  • attachment() - Create drafty attachment messages
  • encode_to_bytes() - Convert objects to bytes
  • parse_cred() - Parse credentials
  • parse_trusted() - Parse trusted values

Constants:

  • MAX_INBAND_ATTACHMENT_SIZE
  • MAX_EXTERN_ATTACHMENT_SIZE
  • MAX_IMAGE_DIM
  • DELETE_MARKER
  • TINODE_DEL

3. commands.py (Command Parsing & Message Building - ~850 lines)

  • Command-line parsing for all commands
  • Protobuf message construction
  • Variable dereferencing
  • Command serialization

Key functions:

  • parse_input() - Parse command line input
  • parse_cmd() - Create argument parsers
  • serialize_cmd() - Convert commands to protobuf
  • derefVals() / getVar() - Variable dereferencing
  • Message builders: hiMsg(), accMsg(), loginMsg(), subMsg(), leaveMsg(), pubMsg(), getMsg(), setMsg(), delMsg(), noteMsg()
  • File operations: upload(), fileUpload(), fileDownload()
  • print_server_params() - Log server info

4. client.py (gRPC Client & Communication - ~260 lines)

  • gRPC connection management
  • Message generation and streaming
  • Server response handling
  • Login/authentication handling
  • Cookie management

Key functions:

  • run() - Main client loop
  • gen_message() - Generate outgoing messages
  • handle_ctrl() - Handle server control responses
  • handle_login() - Process login response
  • save_cookie() / read_cookie() - Cookie persistence
  • pop_from_output_queue() - Output queue management

5. input_handler.py (User Input - ~70 lines)

  • Terminal input reading
  • Multi-line input support
  • Interactive and non-interactive modes

Key functions:

  • stdin() - Main input loop
  • readLinesFromStdin() - Read with prompt support

6. tn_globals.py (Shared Global State - ~104 lines)

  • Global variables shared across all modules
  • Asynchronous I/O queue management
  • Utility functions for logging and output
  • Protobuf to JSON conversion

Key variables:

  • OnCompletion - Dictionary of callbacks for server responses
  • WaitingFor - Outstanding synchronous command request
  • AuthToken - Current authentication token
  • InputQueue / OutputQueue - Async I/O queues
  • InputThread - Background input thread
  • IsInteractive - Detect if running in interactive mode
  • Prompt - PromptSession for interactive input
  • DefaultUser / DefaultTopic - Default context values
  • Variables - Store command execution results
  • Connection - gRPC connection to server
  • Verbose - Extended logging flag

Key functions:

  • printout() - Print in interactive mode only
  • printerr() - Write to stderr
  • stdout() / stdoutln() - Async output to stdout
  • clip_long_string() - Shorten long strings for logging
  • to_json() - Convert protobuf messages to JSON

7. macros.py (Command Macros - ~341 lines)

  • High-level command macros that expand into basic commands
  • Simplifies complex multi-step operations
  • Requires root privileges for most operations

Macro base class:

  • Macro - Base class for all macros with parsing and execution

Available macros:

  • usermod - Modify user account (suspend/unsuspend, update theCard, trusted values)
  • resolve - Resolve login name to user ID
  • passwd - Set user's password
  • useradd - Create new user account with credentials
  • chacs - Change default permissions/acs for a user
  • userdel - Delete user account (soft or hard delete)
  • chcred - Add/delete/validate user credentials
  • thecard - Print user's public/private data or credentials

Key functions:

  • parse_macro() - Find parser for macro command
  • Macro.expand() - Expand macro to list of basic commands
  • Macro.run() - Execute macro or explain expansion

Macro dictionary:

  • Macros - Dictionary mapping macro names to instances

Module Dependencies

tn-cli.py
├── tn_globals
├── client (run, read_cookie)
└── commands (set_macros_module)

client.py
├── tn_globals
├── tinode_grpc (pb, pbx)
├── utils (dotdict)
├── input_handler (stdin)
└── commands (hiMsg, loginMsg, serialize_cmd)

commands.py
├── tn_globals
├── tinode_grpc (pb, pbx)
├── utils (makeTheCard, inline_image, attachment, etc.)
└── client (handle_ctrl, handle_login, save_cookie) [for specific commands]

utils.py
├── tn_globals
└── tinode_grpc (pb)

input_handler.py
└── tn_globals

macros.py
└── tn_globals

tn_globals.py
└── (no dependencies - provides shared state)

Why

  1. Separation of Concerns: Each module has a clear, focused responsibility
  2. Maintainability: Easier to find and modify specific functionality
  3. Testability: Individual modules can be tested independently
  4. Readability: Smaller files are easier to understand
  5. Reusability: Utilities and client code can be reused
  6. Extensibility: Easy to add new macros or commands without modifying core logic
  7. Shared State Management: tn_globals.py provides centralized state accessible to all modules

Usage

Run the application using:

python3 tn-cli.py [arguments]

Or make it executable:

chmod +x tn-cli.py
./tn-cli.py [arguments]