doc(aya): document tcx link pinning for atomic program replacement #1396

svencowart · 2025-11-15T04:16:08Z

Add documentation and integration test for SchedClassifier link pinning, which enables zero-downtime program updates in production environments.

Add link pinning example to SchedClassifier::attach_with_options() showing atomic replacement workflow for TCX mode (kernel >= 6.6).
Add pin_tcx_link() integration test verifying link persistence across program unload and atomic replacement capability.

Closes #1395

This change is

netlify · 2025-11-15T04:16:14Z

✅ Deploy Preview for aya-rs-docs ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`d1a2f5d`
🔍 Latest deploy log	https://app.netlify.com/projects/aya-rs-docs/deploys/6948d1caa7d51e00087db3af
😎 Deploy Preview	https://deploy-preview-1396--aya-rs-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

tamird · 2025-11-17T19:55:51Z

Could you address the CI failures?

svencowart · 2025-11-20T19:40:34Z

Could you address the CI failures?

Yup, all done.

tamird

Thanks! A few comments.

@tamird reviewed 2 of 2 files at r1, all commit messages.
Reviewable status: all files reviewed, 6 unresolved discussions (waiting on @svencowart)

-- commits line 10 at r1:
please add periods at the end s of these list items

Code quote:

  - Add link pinning example to SchedClassifier::attach_with_options()
    showing atomic replacement workflow for TCX mode (kernel >= 6.6)
  - Add pin_tcx_link() integration test verifying link persistence
    across program unload and atomic replacement capability

aya/src/programs/tc.rs line 220 at r1 (raw file):

    /// let pin_path = "/sys/fs/bpf/my_link";
    ///
    /// let link_id = if Path::new(pin_path).exists() {

This is a classic TOCTOU race. Can we instead write as handling the error from from_pin?

aya/src/programs/tc.rs line 222 at r1 (raw file):

    /// let link_id = if Path::new(pin_path).exists() {
    ///     let old = PinnedLink::from_pin(pin_path)?;
    ///     prog.attach_to_link(FdLink::from(old).try_into()?)?  // atomic replacement

could you please extract a local variable for the result of the intermediate fallible operation?

aya/src/programs/tc.rs line 225 at r1 (raw file):

    /// } else {
    ///     prog.attach_with_options("eth0", TcAttachType::Ingress,
    ///                               TcAttachOptions::TcxOrder(LinkOrder::default()))?

would you mind double checking that this formatting is what rustfmt would do?

Code quote:

    ///     prog.attach_with_options("eth0", TcAttachType::Ingress,
    ///                               TcAttachOptions::TcxOrder(LinkOrder::default()))?

aya/src/programs/tc.rs line 238 at r1 (raw file):

    /// [`TcError::NetlinkError`] is returned if attaching fails. A common cause
    /// of failure is not having added the `clsact` qdisc to the given
    /// interface, see [`qdisc_add_clsact`]

mind adding a period?

test/integration-test/src/tests/load.rs line 400 at r1 (raw file):

#[test_log::test]
fn pin_tcx_link() {

did you want to use attach_to_link here? I thought that was the main thing you wanted to demonstrate here.

svencowart

I've addressed your comments. Let me know if you want to see anything else changed.

Reviewable status: 0 of 2 files reviewed, 6 unresolved discussions (waiting on @tamird)

-- commits line 10 at r1:

Previously, tamird (Tamir Duberstein) wrote…

please add periods at the end s of these list items

Done.

aya/src/programs/tc.rs line 220 at r1 (raw file):

Previously, tamird (Tamir Duberstein) wrote…

This is a classic TOCTOU race. Can we instead write as handling the error from from_pin?

Done.

aya/src/programs/tc.rs line 222 at r1 (raw file):

Previously, tamird (Tamir Duberstein) wrote…

could you please extract a local variable for the result of the intermediate fallible operation?

Done.

aya/src/programs/tc.rs line 225 at r1 (raw file):

Previously, tamird (Tamir Duberstein) wrote…

would you mind double checking that this formatting is what rustfmt would do?

Done.

aya/src/programs/tc.rs line 238 at r1 (raw file):

Previously, tamird (Tamir Duberstein) wrote…

mind adding a period?

Done.

test/integration-test/src/tests/load.rs line 400 at r1 (raw file):

Previously, tamird (Tamir Duberstein) wrote…

did you want to use attach_to_link here? I thought that was the main thing you wanted to demonstrate here.

Fair enough. I've changed it to use attach_to_link. Originally, I was trying to keep the test close to pin_link, but actually using attach_to_link is a better approach.

svencowart · 2025-12-09T02:39:06Z

@tamird it seems to me the failing CI jobs have nothing to do with my changes. Am I right about that?

tamird · 2025-12-09T02:51:29Z

Yep #1409 should fix it

tamird

Thanks! Just a few comments (please squash when you address them)

@tamird reviewed 1 of 2 files at r2, 1 of 1 files at r3, all commit messages.
Reviewable status: all files reviewed, 2 unresolved discussions (waiting on @svencowart)

-- commits line 10 at r1:

Previously, svencowart (Sven Cowart) wrote…

Done.

looks not done

aya/src/programs/tc.rs line 225 at r3 (raw file):

    ///         prog.attach_to_link(link)?
    ///     }
    ///     Err(_) => {

I think this needs to be a more precise check - only ENOENT (or whatever the higher-level representation is) should be swallowed in this way

tamird · 2025-12-09T14:02:40Z

@codex review

Copilot

Pull request overview

This PR adds documentation and testing for TCX link pinning functionality, enabling atomic program replacement for SchedClassifier programs without downtime.

Adds comprehensive documentation example to SchedClassifier::attach_with_options() demonstrating the link pinning workflow for TCX mode
Implements pin_tcx_link() integration test validating link persistence and atomic replacement
Adds necessary imports to support the new test

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
test/integration-test/src/tests/load.rs	Adds `pin_tcx_link()` integration test demonstrating link pinning and atomic program replacement for TCX mode
aya/src/programs/tc.rs	Adds documentation section with code example showing how to use link pinning for atomic program replacement in TCX mode

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

test/integration-test/src/tests/load.rs

chatgpt-codex-connector · 2025-12-09T14:15:02Z

Codex Review: Didn't find any major issues. Keep them coming!

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

svencowart

Reviewable status: 0 of 2 files reviewed, 2 unresolved discussions (waiting on @tamird)

-- commits line 10 at r1:

Previously, tamird (Tamir Duberstein) wrote…

looks not done

Right, I apologize — I didn't realize you were talking about the commit message itself. I've addressed this.

aya/src/programs/tc.rs line 225 at r3 (raw file):

Previously, tamird (Tamir Duberstein) wrote…

I think this needs to be a more precise check - only ENOENT (or whatever the higher-level representation is) should be swallowed in this way

Done.

tamird

@tamird reviewed 2 of 2 files at r5, all commit messages.
Reviewable status: all files reviewed, 1 unresolved discussion (waiting on @svencowart)

aya/src/programs/tc.rs line 214 at r5 (raw file):

    /// ```no_run
    /// # use std::{io, path::Path};
    /// # use aya::programs::{tc, SchedClassifier, TcAttachType, tc::TcAttachOptions, LinkOrder, links::{FdLink, PinnedLink}, LinkError};

Can you please pass this (whole example) through rustfmt?

Add documentation and integration test for SchedClassifier link pinning, which enables zero-downtime program updates in production environments. - Add link pinning example to SchedClassifier::attach_with_options() showing atomic replacement workflow for TCX mode (kernel >= 6.6). - Add pin_tcx_link() integration test verifying link persistence across program unload and atomic replacement capability.

svencowart

@svencowart made 1 comment.
Reviewable status: 1 of 2 files reviewed, 1 unresolved discussion (waiting on @tamird).

aya/src/programs/tc.rs line 214 at r5 (raw file):

Previously, tamird (Tamir Duberstein) wrote…

Can you please pass this (whole example) through rustfmt?

Applied rustfmt to this code section. Getting rustfmt to sort imports in comment strings was not straightforward. I learned something new. Thanks!

tamird

Could you rebase away the merge commit? I can also do it merge

@tamird reviewed 1 file and all commit messages, made 2 comments, and resolved 1 discussion.
Reviewable status: complete! all files reviewed, all discussions resolved (waiting on @svencowart).

aya/src/programs/tc.rs line 214 at r5 (raw file):

Previously, svencowart (Sven Cowart) wrote…

Applied rustfmt to this code section. Getting rustfmt to sort imports in comment strings was not straightforward. I learned something new. Thanks!

Out of curiosity, how did you do it?

tamird

@tamird made 1 comment.
Reviewable status: all files reviewed, 1 unresolved discussion (waiting on @svencowart).

aya/src/programs/tc.rs line 218 at r6 (raw file):

    /// #     programs::{
    /// #         LinkError, LinkOrder, SchedClassifier, TcAttachType,
    /// #         links::{FdLink, PinnedLink},

looks like LinkError should be on this line rather than above

svencowart force-pushed the tcx-pin branch 2 times, most recently from cde4af1 to 8af3b75 Compare November 20, 2025 06:00

tamird reviewed Nov 20, 2025

View reviewed changes

svencowart commented Dec 4, 2025

View reviewed changes

svencowart force-pushed the tcx-pin branch 3 times, most recently from 4708d8c to e8acd35 Compare December 4, 2025 05:13

vadorovsky force-pushed the tcx-pin branch from e8acd35 to d9136a6 Compare December 9, 2025 12:35

tamird requested changes Dec 9, 2025

View reviewed changes

tamird requested a review from Copilot December 9, 2025 14:02

Copilot AI reviewed Dec 9, 2025

View reviewed changes

test/integration-test/src/tests/load.rs Outdated Show resolved Hide resolved

svencowart force-pushed the tcx-pin branch 2 times, most recently from d101941 to 6e800b2 Compare December 10, 2025 20:41

svencowart commented Dec 10, 2025

View reviewed changes

tamird approved these changes Dec 10, 2025

View reviewed changes

svencowart force-pushed the tcx-pin branch from 6e800b2 to 263c025 Compare December 22, 2025 05:04

svencowart commented Dec 22, 2025

View reviewed changes

Merge branch 'main' into tcx-pin

d1a2f5d

tamird approved these changes Dec 22, 2025

View reviewed changes

tamird reviewed Dec 23, 2025

View reviewed changes

doc(aya): document tcx link pinning for atomic program replacement #1396

Are you sure you want to change the base?

doc(aya): document tcx link pinning for atomic program replacement #1396

Conversation

svencowart commented Nov 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify bot commented Nov 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for aya-rs-docs ready!

Uh oh!

tamird commented Nov 17, 2025

Uh oh!

svencowart commented Nov 20, 2025

Uh oh!

tamird left a comment

Choose a reason for hiding this comment

Uh oh!

svencowart left a comment

Choose a reason for hiding this comment

Uh oh!

svencowart commented Dec 9, 2025

Uh oh!

tamird commented Dec 9, 2025

Uh oh!

tamird left a comment

Choose a reason for hiding this comment

Uh oh!

tamird commented Dec 9, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

chatgpt-codex-connector bot commented Dec 9, 2025

Uh oh!

svencowart left a comment

Choose a reason for hiding this comment

Uh oh!

tamird left a comment

Choose a reason for hiding this comment

Uh oh!

svencowart left a comment

Choose a reason for hiding this comment

Uh oh!

tamird left a comment

Choose a reason for hiding this comment

Uh oh!

tamird left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

svencowart commented Nov 15, 2025 •

edited

Loading

netlify bot commented Nov 15, 2025 •

edited

Loading