influxdb3-plugin-sdk

Author-side packaging library for InfluxDB 3 plugins.

Provides the library functions that influxdb3-plugin-cli wraps in user-facing subcommands.

Public modules

• scaffold — generate a single-file plugin directory or index directory from a built-in template (process_writes, process_scheduled_call, process_request, index). Plugin templates write <name>.py as their entry point.
• validate — the filesystem + Python-parser mechanism for validating a plugin directory. plugin_dir walks the directory, reads the entry point, and feeds the results into the pure contract in influxdb3_plugin_schemas::plugin_format, returning a ValidatedPluginDefinition (parsed manifest + classified EntryPoint) on success or a ValidationFailure on error. Supports multi-file plugins (with __init__.py) and single-file plugins (a sole .py file at the top level). The reference tree-sitter-python extractor extract_top_level_defs is exposed publicly so other consumers (e.g. the runtime) can reuse it; it is drift-checked against schemas::plugin_format::TOP_LEVEL_DEF_CONFORMANCE_CASES.
• archive — canonical tar.gz construction per Spec 2 Reproducibility. Byte-deterministic across machines given identical inputs.
• hash — SHA-256 of archive bytes in the canonical sha256:<64 lowercase hex chars> form.
• mutate_index — add, yank, and unyank entries in an existing index. Enforces Spec 1 S1-4 / Spec 2 S2-2 immutability on add and preserves original publication timestamps when yanking or unyanking.
• package — composes validate → archive → hash → mutate_index into a single pipeline, assigning current UTC published_at to newly packaged plugin versions.

Stability

Internal crate. Per the plugin SDK's Spec 2 Stability policy, this crate has no semver commitment — consumers go through influxdb3-plugin-cli's public API. Refactoring freedom in the sdk crate is the goal; the stable boundary is cli.

Dependencies

• influxdb3-plugin-schemas — canonical schema types (re-exported via function signatures).
• tree-sitter + tree-sitter-python — static Python analysis at author time. Linked as C code inside the binary; no runtime python3 dependency.
• tar + flate2 (with rust_backend / miniz_oxide for deterministic gzip bytes) — archive construction.
• sha2 — artifact hashing.
• walkdir — plugin directory traversal.