refactor(sdk)!: cross-language parity, @iii-dev/helpers, and submodule reorg#1848
Open
guibeira wants to merge 30 commits into
Open
refactor(sdk)!: cross-language parity, @iii-dev/helpers, and submodule reorg#1848guibeira wants to merge 30 commits into
guibeira wants to merge 30 commits into
Conversation
Contributor
|
Important Review skippedToo many files! This PR contains 499 files, which is 349 over the limit of 150. To get a review, narrow the scope: Upgrade to a paid plan to raise the limit. ⚙️ Run configurationConfiguration used: Repository UI Review profile: CHILL Plan: Pro Run ID: ⛔ Files ignored due to path filters (7)
📒 Files selected for processing (499)
You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Contributor
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
Contributor
skill-check — docs536 verified, 0 skipped. 11 warnings across the verified workers.
|
guibeira
changed the title
- iii.rs: use Error (IIIError alias dropped from module scope) - engine: import UpdateOp/UpdateOpError/MergePath from iii_helpers::stream - regenerate Cargo.lock
main bumped the workspace to 0.19.5-next.1 but the helpers packages (added on this branch) were still on their pre-rebase versions. Align @iii-dev/helpers (node) and iii-helpers (python) to 0.19.5-next.1 / 0.19.5.dev1 to match the rest of the workspace and regenerate the uv locks. (The rust iii-helpers crate was already bumped during conflict resolution.)
Co-authored-by: Guilherme de S. Vieira Beira <guilherme.vieira.beira@gmail.com> Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…isc fixes (#1861) Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
… and Rust pages The Python (griffe) and Rust (rustdoc) parsers dropped any type defined in the helpers package, even when the core SDK re-exports it. The Node (typedoc) parser inlines such re-exports, so EnqueueResult and the re-exported stream/state types appeared only on the Node SDK page. - parse-griffe: index iii_helpers from the dump and widen the package filter to accept both iii and iii_helpers, so re-exported aliases resolve. - parse-rustdoc: read the helpers crate JSON and document types the SDK re-exports via `pub use iii_helpers::...` (e.g. EnqueueResult). - generate-api-docs: pass the helpers crate JSON to the Rust parser. - generate-api-docs.yml: dump iii_helpers alongside iii for griffe. - Regenerate sdk-python and sdk-rust pages (+ skill artifacts).
…state delete Node and Python state modules each defined both StateDeleteResult and a redundant DeleteResult alias with identical shape. IState.delete now returns StateDeleteResult, matching the StateSetResult/StateUpdateResult naming. Regenerated api-reference mdx and skill artifacts.
…ample The catch-invocation_stopped example still imported the pre-0.20 IIIInvocationError from the package root. 0.20 renamed it to InvocationError (no deprecated alias) and moved it to the errors subpath. Update the Node and Python snippets to import InvocationError from iii-sdk/errors and iii.errors.
quickstart and troubleshooting skill artifacts pointed at docs/next/*.mdx sources but the files live at docs/*.mdx. Re-rendered with iii-skill-render 0.4.28 so the generated header matches the actual source path. Unblocks the skill-check drift gate.
Rust 1.96's clippy promoted doc_nested_refdefs to deny-by-default. Doc-list items of the form `- [`Type::method`]: desc` parse as link reference definitions. Add `[]` between each label and colon so they render as intra-doc links instead. Unblocks the SDK Rust Tests clippy gate.
The exclude list only covered the 0-10-0 and 0-11-0 archives. When skill-check falls back to a full scan (PR diff unavailable), it lints the 0-12-0..0-18-0 frozen archives too, failing on pre-existing Vale errors (em dashes, negation-contrast) in content that must stay frozen. Exclude those archives, matching the existing treatment of 0-10-0/0-11-0.
The register_trigger_type, register_trigger, and trigger doc examples bind the client as iii in their hidden setup but called worker.method(), so the doctests failed to compile (E0425). These were masked until the clippy fix let the doc build proceed. Use iii.method() to match the binding. All 37 doctests pass.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
A large, intentionally breaking reorganization of the three SDKs (Node, Python, Rust) to give them a consistent, well-factored public surface. Upgrading from 0.19.x to 0.20.x requires code changes — see Breaking changes below. It lands the staged refactor plus a final clean break:
@iii-dev/helpers(crateiii-helpers, PyPIiii-helpers), organized into submodules.@iii-dev/helpersas anobservabilitysubmodule; the standaloneiii-observabilitypackages become deprecated shims.EnqueueResult(all SDKs) andTriggerActionVoid(Python) from the root as companions toTriggerAction.Why
The root SDK had grown a wide, inconsistent surface: names diverged across languages, low-level/internal types sat next to the worker API, and several types were duplicated. This refactor gives a single source of truth for the shared contract (
@iii-dev/helpers), groups the rest of the surface by concern, and aligns the three SDKs so the same import means the same thing everywhere.New import surface
Shared types move into the
@iii-dev/helperspackage, by submodule:queue@iii-dev/helpers/queue/iii_helpers.queue/iii_helpers::queueEnqueueResult(also re-exported from the SDK root)http.../httpHttpAuthConfig,HttpInvocationConfig,HttpMethod, thehttphelper, bufferedHttpRequest/HttpResponseworker-connection-manager.../worker-connection-managerAuthInput,AuthResult, the sixOn{Function,Trigger,TriggerType}Registration{Input,Result}stream.../streamUpdateOp,UpdateOpError,MergePath,Update*)observability.../observabilityLogger,initOtel/init_otel,withSpan/with_span,executeTracedRequest/execute_traced_request, and the rest of the observability APIThe rest of the root surface is grouped into in-package submodules (
iii-sdk/<name>/iii.<name>/iii_sdk::<name>):runtime,channel,trigger,errors,engine,protocol,internal, and (Python)utils.Breaking changes / migration
This is a clean break: there are no deprecated re-export or alias shims for the renamed/relocated SDK symbols. 0.19.x imports of these symbols will not resolve on 0.20.x — update to the canonical path / new name.
Moved symbols are removed from the SDK root. Import them from their submodule or from
@iii-dev/helpers:Relocated to in-package submodules and removed from the root in all three SDKs (no shim): the
channel,trigger, andruntimetype groups. Import fromiii-sdk/channel/iii.channel/iii_sdk::channel(and…/trigger,…/runtime).Cross-language renames — the old names are removed (no deprecated alias):
IIIClient(was NodeISdk, RustIII).IIIprefix and move to theerrorssubmodule:IIIInvocationError→InvocationError, RustIIIError→Error.TelemetryOptions(was RustWorkerTelemetryMeta).ApiRequest/ApiResponse→HttpRequest/HttpResponse; streaming keepsStreamRequest/StreamResponse. RustStreamCallRequest/StreamJoinLeaveCallRequest→StreamChangeEvent/StreamJoinLeaveEvent.StreamChangeEventDetail, the result types areStreamSetResult/StreamUpdateResult/StreamDeleteResult, andMergePathis a named export everywhere.UpdateBuilder, the RustValuere-export,IIIForbiddenError/IIITimeoutError(Python),TriggerActionTypealias, the RustFieldPathpath helper, and the rootLogger/OTel re-exports.Observability (deprecated, not yet removed)
The observability surface moves into
@iii-dev/helpers/observability(#1874). The standalone packages —@iii-dev/observability(npm),iii-observability(PyPI),iii-observability(crate) — remain published as deprecated shims that re-export the helpers submodule and emit a deprecation signal, so observability consumers are not broken in 0.20. Their removal is deferred to a later release. Prefer@iii-dev/helpers/observability/iii_helpers.observability/iii_helpers::observabilityfor new code.What stays at the SDK root
Symbols that reference core-only types stay at the root in all three languages (moving them would create a
helpers → coredependency cycle):MiddlewareFunctionInput,IStream,StreamRequest/StreamResponse,TriggerActionEnqueue, plus the worker entry points (register_worker,InitOptions,TriggerAction, builders). Additionally,EnqueueResult(all SDKs) andTriggerActionVoid(Python) are re-exported at the root as companions toTriggerActioneven though their canonical home is thequeue/triggersubmodule.Notes
@iii-dev/helperspublishing is wired into the tag-driven release pipeline (helpers-npm/helpers-py/helpers-rust); nothing publishes until the nextiii/vX.Y.Ztag.iii-helpershas no dependency on the root SDK in any language (no cycle). The root SDK and the engine import moved types from the submodules internally where their own code needs them.crates/iii-worker,console) were repointed to the new submodule/helpers paths and to the renamed symbols.tsc --noEmit; Python pytest + mypy + ruff; Rust build + lib/doc tests (includingcompile_failguards asserting the moved/renamed symbols are unreachable from the crate root) + clippy-D warnings+ fmt;cargo build --workspace+ engine test compile.docs/next/sdk-reference/helpers-lib.mdxand the per-language*-sdk.mdxpages; the 0.20.0 changelog entries underdocs/changelog/0-20-0/.