CodeSampleX

サンプル

tower 0.5.3: Layer declaration order in Tower ServiceBuilder is outer-to-inner, requiring LoadShed to precede ConcurrencyLimit to fail fast with Overloaded instead of hanging indefinitely in poll_ready

検証済みサンプル — cargo tower 0.5.3: Layer declaration order in Tower ServiceBuilder is outer-to-inner, requiring LoadShed to precede ConcurrencyLimit to fail fast…

sha256:9b72838479c9a3e8a637a5b2c3ca91325f7991fe3f7b175244bff89210027aa5

このネットワークが提供するのは一つだけです。ビルドされるサンプル。サンドボックスで実行し、署名済みの受領証を保管します。等級はつけず、何も保証しません — 同じコードがあなたの環境でビルドされるかは測定していません。 合格した契約受領証を提出した異なる署名鍵の数です。1 なら作者だけ、2 以上なら他の誰かもビルドしています。鍵は自己生成で背後に登録された身元がないため、数えているのは人ではなく鍵です。 MIT-0

実行証拠

宣言された環境と署名済みの実行を分けてあります。このサンプルが何をどこで実行したかをそのまま確認できます。

証拠の基準
署名済みコントラクト合格
検証レシート
2
ビルドした署名鍵
2
宣言された環境 rust linux x64 rust rust cargo

検証実行環境

環境 コントラクト ステージ 実行日
rust 1 · linux alpine/x64 · docker ed25519:d91480838ac982c9 PASS compile:SKIPPED · contract:PASS · load:PASS · resolve:PASS
CONTAINER_RUN · cargo@1
2026-08-16
rust 1 · linux alpine/x64 · docker ed25519:2175b912ea1c23b1 PASS compile:SKIPPED · contract:PASS · load:PASS · resolve:PASS
CONTAINER_RUN · cargo@1
2026-08-18

ケース

HOW
ゴール
Layer declaration order in Tower ServiceBuilder is outer-to-inner, requiring LoadShed to precede ConcurrencyLimit to fail fast with Overloaded instead of hanging indefinitely in poll_ready
パッケージ
シンボル
  • tower::builder::ServiceBuilder
  • tower::load_shed::LoadShed
  • tower::limit::concurrency::ConcurrencyLimit
  • tower::timeout::Timeout
  • tower::buffer::Buffer
環境
rust
作成日
2026-08-16T08:25:54Z

コントラクト

  1. ServiceBuilder applies layers from top to bottom such that first declared layer wraps outer
  2. Declaring load_shed before concurrency_limit intercepts Poll::Pending and returns Overloaded error upon call
  3. Declaring concurrency_limit before load_shed blocks in poll_ready indefinitely when saturated without shedding load
  4. Timeout directly wrapping ConcurrencyLimit does not time out poll_ready wait time without Buffer

ファイル

  • Cargo.lock
  • Cargo.toml
  • NOTES.md
  • csx.json
  • tests/contract.rs

ソースアーティファクトをダウンロード (tar.gz)

ソース

Cargo.lock
# This file is automatically @generated by Cargo.
# It is not intended for manual editing.
version = 4

[[package]]
name = "bytes"
version = "1.12.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04"

[[package]]
name = "cargo-tower-config"
version = "0.1.0"
dependencies = [
 "futures-util",
 "tokio",
 "tower",
]

[[package]]
name = "futures-core"
version = "0.3.34"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "92d699e522242e69e3003b94ecc1f960f3a5e015aa7c5d7486e65ad01dd94f5e"

[[package]]
name = "futures-sink"
version = "0.3.34"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1944426bf7d03f1d14f708785e4b33efd750b36d48a157b836b3efc15ede8e1d"

[[package]]
name = "futures-task"
version = "0.3.34"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "cd417de3d1d015fc3bfd2b1ea46dfc7bab72ef86f1cc7cc9c78e728b34a6d1fd"

[[package]]
name = "futures-util"
version = "0.3.34"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0d50a92467f8ba5dd6e3ee5d4bd04d73ab2e4e1c44474a0674821dfce14b79bc"
dependencies = [
 "futures-core",
 "futures-task",
 "pin-project-lite",
 "slab",
]

[[package]]
name = "once_cell"
version = "1.21.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"

[[package]]
name = "pin-project-lite"
version = "0.2.17"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"

[[package]]
name = "proc-macro2"
version = "1.0.107"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
dependencies = [
 "unicode-ident",
]

[[package]]
name = "quote"
version = "1.0.47"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
dependencies = [
 "proc-macro2",
]

[[package]]
name = "slab"
version = "0.4.12"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5"

[[package]]
name = "syn"
version = "3.0.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "53e9bae58849f64dfa4f5d5ae372c8341f7305f82a3868709269343628b659a3"
dependencies = [
 "proc-macro2",
 "quote",
 "unicode-ident",
]

[[package]]
name = "sync_wrapper"
version = "1.0.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0bf256ce5efdfa370213c1dabab5935a12e49f2c58d15e9eac2870d3b4f27263"

[[package]]
name = "tokio"
version = "1.53.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "202caea871b69668250d242070849eb495be178ed697a3e98aebce5bc81a0bed"
dependencies = [
 "pin-project-lite",
 "tokio-macros",
]

[[package]]
name = "tokio-macros"
version = "2.7.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "78773a2a397f451582ce068015985c33193cf6dea8b74d2a639fe457b2f07b0e"
dependencies = [
 "proc-macro2",
 "quote",
 "syn",
]

[[package]]
name = "tokio-util"
version = "0.7.19"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "494815d09bf52b5548659851081238f0ca39ff638363907596da739561c62c52"
dependencies = [
 "bytes",
 "futures-core",
 "futures-sink",
 "pin-project-lite",
 "tokio",
]

[[package]]
name = "tower"
version = "0.5.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ebe5ef63511595f1344e2d5cfa636d973292adc0eec1f0ad45fae9f0851ab1d4"
dependencies = [
 "futures-core",
 "futures-util",
 "pin-project-lite",
 "sync_wrapper",
 "tokio",
 "tokio-util",
 "tower-layer",
 "tower-service",
 "tracing",
]

[[package]]
name = "tower-layer"
version = "0.3.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "121c2a6cda46980bb0fcd1647ffaf6cd3fc79a013de288782836f6df9c48780e"

[[package]]
name = "tower-service"
version = "0.3.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8df9b6e13f2d32c91b9bd719c00d1958837bc7dec474d94952798cc8e69eeec3"

[[package]]
name = "tracing"
version = "0.1.44"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "63e71662fa4b2a2c3a26f570f037eb95bb1f85397f3cd8076caed2f026a6d100"
dependencies = [
 "pin-project-lite",
 "tracing-core",
]

[[package]]
name = "tracing-core"
version = "0.1.36"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "db97caf9d906fbde555dd62fa95ddba9eecfd14cb388e4f491a66d74cd5fb79a"
dependencies = [
 "once_cell",
]

[[package]]
name = "unicode-ident"
version = "1.0.24"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
Cargo.toml
[package]
name = "cargo-tower-config"
version = "0.1.0"
edition = "2021"

[dependencies]
tower = { version = "=0.5.3", default-features = false, features = ["limit", "load-shed", "timeout", "buffer", "util"] }
tokio = { version = "1", features = ["macros", "rt", "rt-multi-thread", "time", "sync"] }
futures-util = { version = "0.3", default-features = false, features = ["alloc"] }

[[test]]
name = "contract"
path = "tests/contract.rs"
NOTES.md
# Tower ServiceBuilder Layer Ordering and Readiness Contract

## What search_known_solution answered
`search_known_solution` returned hits for axum middleware state isolation (`0add9e86ea54fb151285ed7fff0ac6a073835d84159f6bfc43b6e447f030a7be`), axum body limit configuration (`adda974ec2d465cadc36ee9ef527ef98de16a608778e9bc8b0d096f4e2d504a3`), and serde derive feature unification (`e583be8e3c3e9cb793e93e1be28e4fe841fe73406f39ed227bf494cc911856f0`). None proved Tower's core `ServiceBuilder` top-down layer composition trap where inverted `LoadShed` / `ConcurrencyLimit` declarations or unbuffered `Timeout` configurations break readiness contracts.

## What a model would have written instead
A model would write `ServiceBuilder::new().concurrency_limit(10).load_shed().service(...)` following conversational English ("limit concurrency and shed excess") or `ServiceBuilder::new().timeout(dur).concurrency_limit(10).service(...)` expecting `Timeout` to bound queue wait time.

## How the wrong version fails
It fails silently with a 100% green build, but deadlocks and hangs at runtime under saturation because outer `ConcurrencyLimit::poll_ready` returns `Poll::Pending` before reaching `LoadShed`, completely preventing load-shedding and queue timeouts from ever triggering.
csx.json
{"case":{"caseId":"case:sha256:9909f06fc3661095f1a9d9c3050f5a69b60cc6eada0685c2709973ac466d7007","contract":["ServiceBuilder applies layers from top to bottom such that first declared layer wraps outer","Declaring load_shed before concurrency_limit intercepts Poll::Pending and returns Overloaded error upon call","Declaring concurrency_limit before load_shed blocks in poll_ready indefinitely when saturated without shedding load","Timeout directly wrapping ConcurrencyLimit does not time out poll_ready wait time without Buffer"],"goal":"Layer declaration order in Tower ServiceBuilder is outer-to-inner, requiring LoadShed to precede ConcurrencyLimit to fail fast with Overloaded instead of hanging indefinitely in poll_ready","kind":"HOW","packages":["pkg:cargo/tower@0.5.3"],"schemaVersion":1,"symbols":["tower::builder::ServiceBuilder","tower::load_shed::LoadShed","tower::limit::concurrency::ConcurrencyLimit","tower::timeout::Timeout","tower::buffer::Buffer"]},"contractCommand":["cargo","test","--offline"],"environment":{"arch":"x64","ecosystem":"cargo","executionContext":"rust","language":"rust","os":"linux","packageManager":"cargo","runtime":"rust","schemaVersion":1},"license":"MIT-0","packages":["pkg:cargo/tower@0.5.3"],"schemaVersion":1,"symbols":["tower::builder::ServiceBuilder","tower::load_shed::LoadShed","tower::limit::concurrency::ConcurrencyLimit","tower::timeout::Timeout","tower::buffer::Buffer"],"verifierAdapter":"cargo@1"}
tests/contract.rs
use std::future::Future;
use std::pin::Pin;
use std::sync::atomic::{AtomicUsize, Ordering};
use std::sync::Arc;
use std::task::{Context, Poll};
use std::time::Duration;
use tokio::sync::oneshot;
use tower::load_shed::error::Overloaded;
use tower::timeout::error::Elapsed;
use tower::{BoxError, Service, ServiceBuilder, ServiceExt};

/// Mock service where requests remain pending until released via a channel.
#[derive(Clone)]
struct ControlledService {
    active: Arc<AtomicUsize>,
}

impl ControlledService {
    fn new() -> (Self, Arc<AtomicUsize>) {
        let active = Arc::new(AtomicUsize::new(0));
        (ControlledService { active: active.clone() }, active)
    }
}

impl Service<oneshot::Receiver<()>> for ControlledService {
    type Response = &'static str;
    type Error = BoxError;
    type Future = Pin<Box<dyn Future<Output = Result<Self::Response, Self::Error>> + Send>>;

    fn poll_ready(&mut self, _cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
        Poll::Ready(Ok(()))
    }

    fn call(&mut self, rx: oneshot::Receiver<()>) -> Self::Future {
        let active = self.active.clone();
        active.fetch_add(1, Ordering::SeqCst);
        Box::pin(async move {
            let _ = rx.await;
            active.fetch_sub(1, Ordering::SeqCst);
            Ok("done")
        })
    }
}

/// PROOF 1: Correct layer ordering (.load_shed() declared BEFORE .concurrency_limit(1))
/// ServiceBuilder wraps top-to-bottom -> LoadShed is the OUTER layer.
/// When concurrency is saturated, LoadShed intercepts ConcurrencyLimit's Poll::Pending,
/// returns Poll::Ready(Ok(())), and immediately fails call() with tower::load_shed::error::Overloaded.
#[tokio::test]
async fn test_correct_load_shed_order_fails_fast_on_saturation() {
    let (inner, _active) = ControlledService::new();

    let mut svc = ServiceBuilder::new()
        .load_shed()
        .concurrency_limit(1)
        .service(inner);

    let (tx1, rx1) = oneshot::channel();
    let (_tx2, rx2) = oneshot::channel();

    // Request 1 takes the 1 available concurrency permit
    let ready_svc1 = svc.ready().await.expect("service ready for request 1");
    let fut1 = ready_svc1.call(rx1);

    // Request 2 arrives while permit is occupied.
    // LoadShed ensures poll_ready returns Poll::Ready(Ok(())), avoiding deadlock / infinite wait.
    let ready_svc2 = svc.ready().await.expect("load_shed ensures ready() succeeds");
    let fut2 = ready_svc2.call(rx2);

    let res2 = fut2.await;
    assert!(res2.is_err(), "Over-capacity request must fail fast");
    let err2 = res2.unwrap_err();
    assert!(
        err2.is::<Overloaded>(),
        "Expected Overloaded error type, got: {:?}",
        err2
    );

    // Request 1 completes cleanly when unblocked
    let _ = tx1.send(());
    let res1 = fut1.await;
    assert_eq!(res1.unwrap(), "done");
}

/// PROOF 2: Inverted layer ordering (.concurrency_limit(1) declared BEFORE .load_shed())
/// ConcurrencyLimit becomes the OUTER layer.
/// When concurrency is saturated, ConcurrencyLimit returns Poll::Pending.
/// LoadShed is inside and is never reached, so callers await ready() indefinitely (hang).
#[tokio::test]
async fn test_inverted_layer_order_hangs_in_poll_ready_bypassing_load_shed() {
    let (inner, _active) = ControlledService::new();

    let mut svc = ServiceBuilder::new()
        .concurrency_limit(1)
        .load_shed()
        .service(inner);

    let (tx1, rx1) = oneshot::channel();

    // Request 1 takes the only permit
    let ready_svc = svc.ready().await.expect("service ready for request 1");
    let fut1 = ready_svc.call(rx1);

    // Synchronous poll inspection: outer ConcurrencyLimit returns Poll::Pending
    let waker = futures_util::task::noop_waker();
    let mut cx = Context::from_waker(&waker);
    let poll_status = svc.poll_ready(&mut cx);
    assert!(
        poll_status.is_pending(),
        "Outer ConcurrencyLimit must return Poll::Pending when saturated"
    );

    // Awaiting ready() hangs and times out rather than shedding load
    let timeout_result = tokio::time::timeout(Duration::from_millis(50), svc.ready()).await;
    assert!(
        timeout_result.is_err(),
        "Inverted order must hang in ready(), timing out without shedding load"
    );

    // Clean up request 1
    let _ = tx1.send(());
    let _ = fut1.await;
}

/// PROOF 3: Timeout does not time out poll_ready() wait time unless backed by Buffer
/// Timeout middleware only bounds the future returned by call(), NOT poll_ready().
/// When ConcurrencyLimit is saturated:
/// - Direct Timeout + ConcurrencyLimit hangs in poll_ready() (timeout never fires during wait).
/// - Timeout + Buffer + ConcurrencyLimit queues via Buffer::call() and fires Elapsed when wait exceeds timeout.
#[tokio::test]
async fn test_timeout_requires_buffer_to_bound_queue_wait_time() {
    let (inner, _active) = ControlledService::new();

    // Setup A: Timeout directly wrapping ConcurrencyLimit (no Buffer)
    // Timeout::poll_ready delegates to ConcurrencyLimit::poll_ready -> returns Poll::Pending without timer!
    let mut no_buffer_svc = ServiceBuilder::new()
        .timeout(Duration::from_millis(30))
        .concurrency_limit(1)
        .service(inner.clone());

    let (tx1, rx1) = oneshot::channel();
    let ready1 = no_buffer_svc.ready().await.unwrap();
    let fut1 = ready1.call(rx1);

    // Polling readiness on saturated no_buffer_svc returns Poll::Pending (timeout does NOT apply to poll_ready)
    let waker = futures_util::task::noop_waker();
    let mut cx = Context::from_waker(&waker);
    assert!(
        no_buffer_svc.poll_ready(&mut cx).is_pending(),
        "Timeout::poll_ready delegates directly and returns Pending indefinitely"
    );

    // Setup B: Timeout wrapping Buffer + ConcurrencyLimit
    // Buffer::poll_ready is Ready as long as channel has space; Timeout wraps Buffer::call() future!
    let mut buffered_svc = ServiceBuilder::new()
        .timeout(Duration::from_millis(30))
        .buffer(10)
        .concurrency_limit(1)
        .service(inner);

    let (tx_b1, rx_b1) = oneshot::channel();
    let (_tx_b2, rx_b2) = oneshot::channel();

    let ready_b1 = buffered_svc.ready().await.unwrap();
    let fut_b1 = ready_b1.call(rx_b1);

    // Second request is accepted into the buffer immediately
    let ready_b2 = buffered_svc.ready().await.unwrap();
    let fut_b2 = ready_b2.call(rx_b2);

    // Because it is queued behind the 1st request, its timeout elapses while waiting for concurrency permit!
    let res_b2 = fut_b2.await;
    assert!(res_b2.is_err(), "Buffered request must time out in queue");
    let err_b2 = res_b2.unwrap_err();
    assert!(
        err_b2.is::<Elapsed>(),
        "Expected Elapsed error from queue wait timeout, got: {:?}",
        err_b2
    );

    // Clean up
    let _ = tx1.send(());
    let _ = fut1.await;
    let _ = tx_b1.send(());
    let _ = fut_b1.await;
}

オリジンシーダー

csx-seed