Skip to content

Refactor: Extract FFI code to dedicated crate#226

Merged
DorianZheng merged 1 commit intoboxlite-ai:mainfrom
qidi1:feature/extract-ffi-code
Feb 14, 2026
Merged

Refactor: Extract FFI code to dedicated crate#226
DorianZheng merged 1 commit intoboxlite-ai:mainfrom
qidi1:feature/extract-ffi-code

Conversation

@qidi1
Copy link
Copy Markdown
Contributor

@qidi1 qidi1 commented Feb 10, 2026

Close #225
This PR extracts the FFI logic from the C SDK into a dedicated boxlite-ffi crate.

Changes

  • Moved core FFI operations from sdks/c/src/ffi.rs to sdks/boxlite-ffi/src/ops.rs.
  • Created shared utility modules error.rs, json.rs, and string.rs in boxlite-ffi.
  • Updated sdks/c to depend on the new shared crate.

Motivation

This refactoring allows reusing the core FFI implementation across multiple language bindings (C, Go, Node.js, Python), significantly reducing code duplication and simplifying maintenance. It is a necessary step for cleaner SDK architecture.

This work also prepares the codebase for the Go SDK implementation. As noted in #202, the Go SDK development will be completed after this PR is merged.

@qidi1 qidi1 force-pushed the feature/extract-ffi-code branch 6 times, most recently from 4b47ede to 53aa766 Compare February 11, 2026 08:41
@qidi1 qidi1 force-pushed the feature/extract-ffi-code branch from 53aa766 to 52ae09b Compare February 11, 2026 08:59
@qidi1
Copy link
Copy Markdown
Contributor Author

qidi1 commented Feb 11, 2026

@DorianZheng Please have a look.
I tried to add the FFI tests (boxlite-ffi) to the GitHub Actions workflow, but the job failed.

Reason:
The GitHub runners don’t have the required native dependencies (e.g., libkrun, and KVM support) needed to link and/or run these tests.

What I tried:
I attempted to use BOXLITE_DEPS_STUB=1 to mock the underlying native libraries and bypass the native linking requirements. However, this
approach turned out to be complex and unstable in the CI environment (getting stub libraries/symbols wired correctly across crates).

Question:
Is running the FFI unit tests in CI a blocking requirement for this PR? If so, we’ll likely need a more robust mocking strategy for the
core runtime components. For now, I verified the FFI bindings locally.

state.set_status(BoxStatus::Stopped);
state.set_pid(None);

// Only transition to Stopped if we were Running (or other active state).
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch!

@DorianZheng
Copy link
Copy Markdown
Member

@qidi1 Thank you very much

@DorianZheng Please have a look. I tried to add the FFI tests (boxlite-ffi) to the GitHub Actions workflow, but the job failed.

Reason: The GitHub runners don’t have the required native dependencies (e.g., libkrun, and KVM support) needed to link and/or run these tests.

What I tried: I attempted to use BOXLITE_DEPS_STUB=1 to mock the underlying native libraries and bypass the native linking requirements. However, this approach turned out to be complex and unstable in the CI environment (getting stub libraries/symbols wired correctly across crates).

Question: Is running the FFI unit tests in CI a blocking requirement for this PR? If so, we’ll likely need a more robust mocking strategy for the core runtime components. For now, I verified the FFI bindings locally.

Hi @qidi1. I will review and merge this PR after review, and it's better to have a Mock method to run the UT in a separate PR. What do you think?

@DorianZheng
Copy link
Copy Markdown
Member

Regenerate C header when shared FFI sources change — /Users/zhengzhiquan/Workspace/boxlite/sdks/c/build.rs:24-25

After this refactor, cbindgen pulls public types from boxlite-ffi (parse_deps = true), but the build script only reruns when sdks/c/src or cbindgen.toml change. If only sdks/boxlite-ffi changes, cargo build -p boxlite-c can leave sdks/c/include/boxlite.h stale, causing the published C header to drift from the actual exported FFI surface.

@qidi1
Copy link
Copy Markdown
Contributor Author

qidi1 commented Feb 14, 2026

@qidi1 Thank you very much

@DorianZheng Please have a look. I tried to add the FFI tests (boxlite-ffi) to the GitHub Actions workflow, but the job failed.
Reason: The GitHub runners don’t have the required native dependencies (e.g., libkrun, and KVM support) needed to link and/or run these tests.
What I tried: I attempted to use BOXLITE_DEPS_STUB=1 to mock the underlying native libraries and bypass the native linking requirements. However, this approach turned out to be complex and unstable in the CI environment (getting stub libraries/symbols wired correctly across crates).
Question: Is running the FFI unit tests in CI a blocking requirement for this PR? If so, we’ll likely need a more robust mocking strategy for the core runtime components. For now, I verified the FFI bindings locally.

Hi @qidi1. I will review and merge this PR after review, and it's better to have a Mock method to run the UT in a separate PR. What do you think?

I will add in other PR

@DorianZheng
Copy link
Copy Markdown
Member

@qidi1 Thank you very much

@DorianZheng Please have a look. I tried to add the FFI tests (boxlite-ffi) to the GitHub Actions workflow, but the job failed.
Reason: The GitHub runners don’t have the required native dependencies (e.g., libkrun, and KVM support) needed to link and/or run these tests.
What I tried: I attempted to use BOXLITE_DEPS_STUB=1 to mock the underlying native libraries and bypass the native linking requirements. However, this approach turned out to be complex and unstable in the CI environment (getting stub libraries/symbols wired correctly across crates).
Question: Is running the FFI unit tests in CI a blocking requirement for this PR? If so, we’ll likely need a more robust mocking strategy for the core runtime components. For now, I verified the FFI bindings locally.

Hi @qidi1. I will review and merge this PR after review, and it's better to have a Mock method to run the UT in a separate PR. What do you think?

I will add in other PR

Great! I will just merge this PR and please file another PR for mock for UT

Copy link
Copy Markdown
Member

@DorianZheng DorianZheng left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@DorianZheng DorianZheng merged commit 0f5b390 into boxlite-ai:main Feb 14, 2026
14 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Refactor: Extract C ABI exports into a dedicated boxlite-c-abi crate

2 participants