51 lines
33 KiB
Plaintext
51 lines
33 KiB
Plaintext
|
rust
|
|||
|
|
Tƒ #rustc 1.96.0 (ac68faa20 2026-05-25)ÁÀ뉊 ]!ÜÛê(¹Þ—šên -5be7b69c3ff7b5b8Á íàÄTËŸ ÜJîÄ)'ß\¥! -3d1337db07d0b3aeÁ ¤²XctÔ'ÐÓ©z¨É½Ó -a4945860e1c53b00Á ¤°ð ¾ä-±($²ï=©Ã -7e98a21bfd32b0edÁ–�òÖÀH•‘P IÓHã#£ -055f30b747f859b6Á rustc_std_workspace_coreÁCçß^ò½èÝ$Çÿ+Cé -c4878ee60b2242c9Á ŸÃï+Ñ]ŠqB<ÏïW# -8dd1dd90e70d0b6aÁ miniz_oxideÁ€š»J(P>àö÷g\K -1eb618da2918ab7fÁ adler2ÁÆ;+Þ®5¥ÌýÝ°¦ÛLˆ -f7919172d268e069Á hashbrownÁPäV9ÒÆèÜ�"ÊÖVŽ\ -0fc2184a5da6723aÁ rustc_std_workspace_allocÁs&ØòØy¯s•bæ!‰ýŠ -97e4bf30be240674Á
|
|||
|
|
std_detectÁhŠBîÙºÌI®Ë�Å�š -9dbbf8346ba7ac8bÁ rustc_demangleÁûë9´Ç×@Œ�’ùXFº -f33013f239bf9f14Á cfg_ifÁÜLh�ž§Œaã¯>� -0a71c8f33a838301Á addr2lineÁ׎Þ!]8V$É@@T· -e618e6be60e87ba2Á gimliÁ¸
|
|||
|
|
°µ~Î1‹Ñt ðÁ€w -1f7768a68858f670Á objectÁ
|
|||
|
|
áPÃ?À¶¼QHJ¥� -914cd6a4dbe590d1Á memchrÁ›º«8Ór2Ù $¨ûib‚ -cf21ca6f2bb15dcdÁë
|
|||
|
|
‹ás «LÖ€îâƒ×ɯŒ -ee6f3747e38367f0Á tower_layerÁX*�ø6êWHNᕈf§ • -ee72e88a461fccddÁ
|
|||
|
|
tower_serviceÁ:`¡{¶aÛ¬í"aô -3b2010b03e380b78Á
|
|||
|
|
opaque_futureÁl| » utilÁ„ » spawn-readyÁ¼% » filterÁ”B » makeÁ„Z ü c balanceÁ<â:»� œ‘: bufferÁ4À;» ”ñ: discoverÁD¡<»É ¤Î; î4€=»î”±< hedgeÁ,Û=»ý ŒŽ= limitÁ,µ>»˜
|
|||
|
|
Œè= ¬$�?»¬„Â> load_shedÁLî?» load-shedÁ¬™? ÿ$Ë@»ÿ„€@ ready_cacheÁ\°A» ready-cacheÁ¼×@ reconnectÁL˜B»³ ¬ÃA retryÁ,öB»Ò Œ©B spawn_readyÁ\ÜC»Ø¼ƒC steerÁ,¼D»Ž ŒïC timeoutÁ<šE»© œÉD É$ôE»É„©E
|
|||
|
|
service_fnÁT‰G»É„¢F
|
|||
|
|
ServiceExtÁT•G»É " MakeServiceÁ\ÇH»ÿ„àG À macrosÁ builderÁ >
|
|||
|
|
æ � layerÁ ¥ layer_fnÁ —
|
|||
|
|
into_innerÁ serviceÁ ¤ check_cloneÁ check_service_cloneÁ ¤
|
|||
|
|
check_serviceÁ ¤ ¥ ¦ – � × #¤ #� # ServiceÁ #ž ž ( ((((É - -- sealedÁ 4 SealedÁ 5¥ BoxErrorÁ ServiceBuilderÁ 8� 8ž ;� ;ƒ
|
|||
|
|
"
|
|||
|
|
"
|
|||
|
|
"
|
|||
|
|
'
|
|||
|
|
=
|
|||
|
|
5Ø 8 8 ï :ž ›qA‚B´Êî � ³ 8 8 ï :ž ›qA‚B´Êîää IdentityÁ å _pÁ ÅÝüdõ«Ò ¿c¾ Ú 8 8 ï :ž ›qA‚B´Êî� ¤ ; 8 8 8# 8س ¿cÚ(47À ïtÊG 8 1 LayerÁ,øH Ú 2ô<¥I 3ü ÙJ üÌ2 / `async fn(Request) -> Result<Response, Error>`Á ÿú tƒ # OverviewÁ ’ú ü–F C Tower is a library of modular and reusable components for buildingÁ üÝ* ' robust networking clients and servers.Á ˆú üŒJ G Tower provides a simple core abstraction, the [`Service`] trait, whichÁ ü×O L represents an asynchronous function taking a request and returning either aÁ ü§P M response or an error. This abstraction can be used to model both clients andÁ dø servers.Á …ú ü‰O L Generic components, like [timeouts], [rate limiting], and [load balancing],Á üÙI F can be modeled as [`Service`]s that wrap some inner service and applyÁ ü£P M additional behavior before or after the inner service is called. This allowsÁ üôT Q implementing these components in a protocol-agnostic, composable way. Typically,Á üÉ2 / such services are referred to as _middleware_.Á üú ü€ F C An additional abstraction, the [`Layer`] trait, is used to composeÁ üÇ J G middleware with [`Service`]s. If a [`Service`] can be thought of as anÁ ü’
|
|||
|
|
P M asynchronous function from a request type to a response type, a [`Layer`] isÁ üã
|
|||
|
|
P M a function taking a [`Service`] of one type and returning a [`Service`] of aÁ ü´ N K different type. The [`ServiceBuilder`] type is used to add middleware to aÁ üƒ 5 2 service by composing it with multiple [`Layer`]s.Á ¹ ú Ô½ ## The Tower EcosystemÁ Ø ú üÜ - * Tower is made up of the following crates:Á Š
|
|||
|
|
ú äŽ
|
|||
|
|
* [`tower`] (this crate)Á ¼«
|
|||
|
|
* [`tower-service`]Á ¬Ã
|
|||
|
|
* [`tower-layer`]Á ¤Ù
|
|||
|
|
* [`tower-test`]Á î
|
|||
|
|
ú üò
|
|||
|
|
O L Since the [`Service`] and [`Layer`] traits are important integration pointsÁ üÂK H for all libraries using Tower, they are kept as stable as possible, andÁ üŽM J breaking changes are made rarely. Therefore, they are defined in separateÁ üÜF C crates, [`tower-service`] and [`tower-layer`]. This crate containsÁ ü£E B re-exports of those core traits, implementations of commonly-usedÁ üéM J middleware, and [utilities] for working with [`Service`]s and [`Layer`]s.Á ü·O L Finally, the [`tower-test`] crate provides tools for testing programs usingÁ T‡ Tower.Á ’ú \– # UsageÁ ¢ú ü¦O L Tower provides an abstraction layer, and generic implementations of variousÁ üöO L middleware. This means that the `tower` crate on its own does *not* provideÁ üÆL I a working implementation of a network client or server. Instead, Tower'sÁ ü“F C [`Service` trait][`Service`] provides an integration point betweenÁ üÚI F application code, libraries providing middleware implementations, andÁ ü¤G D libraries that implement servers and/or clients for various networkÁ tì protocols.Á ûú üÿO L Depending on your particular use case, you might use Tower in several ways:Á Ïú üÓK H * **Implementing application logic** for a networked program. You mightÁ üŸM J use the [`Service`] trait to model your application's behavior, and useÁ üíN K the middleware [provided by this crate](#modules) and by other librariesÁ ü¼I F to add functionality to clients and servers provided by one or moreÁ ü† protocol implementations.Á ü¦O L * **Implementing middleware** to add custom behavior to network clients andÁ üöL I servers in a reusable manner. This might be general-purpose middlewareÁ üÃO L (and if it is, please consider releasing your middleware as a library forÁ ü“K H other Tower users!) or application-specific behavior that needs to beÁ üß1 . shared between multiple clients or servers.Á ü‘ K H * **Implementing a network protocol**. Libraries that implement networkÁ üÝ G D protocols (such as HTTP) can depend on `tower-service` to use theÁ ü¥ M J [`Service`] trait as an integration point between the protocol and userÁ üó P M code. For example, a client for some protocol might implement [`Service`],Á üÄ H E allowing users to add arbitrary Tower middleware to those clients.Á ü� L I Similarly, a server might be created from a user-provided [`Service`].Á Ú ú üÞ J G Additionally, when a network protocol requires functionality alreadyÁ ü© P M provided by existing Tower middleware, a protocol implementation might useÁ üú F C Tower middleware internally, as well as as an integration point.Á Á!ú ´Å! ## Library SupportÁ Ü!ú üà!N K A number of third-party libraries support Tower and the [`Service`] trait.Á ü¯": 7 The following is an incomplete list of such libraries:Á ê"ú üî"B ? * [`hyper`]: A fast and correct low-level HTTP implementation.Á ü±#J G * [`tonic`]: A [gRPC-over-HTTP/2][grpc] implementation built on top ofÁ üü#P M [`hyper`]. See [here][tonic-examples] for examples of using [`tonic`] withÁ dÍ$ Tower.Á üÚ$< 9 * [`warp`]: A lightweight, composable web framework. SeeÁ ü—%D A [here][warp-service] for details on using [`warp`] with Tower.Á üÜ%O L * [`tower-lsp`] and its fork, [`lspower`]: implementations of the [La
|
|||
|
|
3Ï Ï Ï ¬ô9 4ƒ: |ûE ü 0 - Builder types to compose layers and servicesÁ <ƒF 8©DD ä í,N Ú StackÁ,U ò ô<p × ƒ ¤,
|
|||
|
|
\6_aQS>@´a3D~'üñ) õ ´ ¤¡ <¤ õ
|
|||
|
|
ìÕ õ ¤¢ üù $ ! Create a new [`ServiceBuilder`].Á © õ
|
|||
|
|
|
|||
|
|
|
|||
|
|
̉ � Íìè Ž ¾ ü > ü© 4 1 Add a new layer `T` into the [`ServiceBuilder`].Á â ú üê L I This wraps the inner service with the service provided by a user-definedÁ ü» E B [`Layer`]. The provided layer must implement the [`Layer`] trait.Á … ú Ü� üO,´ ¾¥ 8 8 ï :ž ›qA‚B´Êîòò ýV õ innerÁ ö outerÁ PÛÈù—…]è ¥ Íì…] º
|
|||
|
|
è…]$½ ž,à ü�*T ü½(] Z Add a [`Layer`] built from a function that accepts a service and returns another service.Á Ÿ)ú ü§)< 9 See the documentation for [`layer_fn`] for more details.Á è)ú üð)( % [`layer_fn`]: crate::layer::layer_fnÁD¤* ¾— 8 8 ï :ž ›qA‚B´Êîòò ýV õÇ\ ö×\ PÛÈù—êê LayerFnÁ ì± äƒ5ظ�³ç`è — Íìç` *
|
|||
|
|
èç`$°*± ¶* 䵉 üþˆ2 / Returns the underlying `Layer` implementation.ÁT¼‰ ¾è
|
|||
|
|
è$ljüÇ‹Q üò‰= : Wrap the service `S` with the middleware provided by thisÁ ü´ŠB ? [`ServiceBuilder`]'s [`Layer`]'s, returning a new [`Service`].Á ûŠú ܃‹üO ü£‹ ÔO<΋ > >¾ ¤èÈe Ü ¤ Ù‹ ÍìÈe Ö‹ ÚèÈe D�Œ
|
|||
|
|
èÈe$Ú‹Ø<à‹35 üÖŸ? ü€™. + Check that the builder implements `Clone`.Á ³™ú ü»™[ X This can be useful when debugging type errors in `ServiceBuilder`s with lots of layers.Á ›šú ü£šC @ Doesn't actually change the builder but serves as a type check.Á ëšú lóš
|
|||
|
|
# ExampleÁ …›ú \�› ```rustÁ ô�› use tower::ServiceBuilder;Á À›ú üÈ›' $ let builder = ServiceBuilder::new()Á üô›5 2 // Do something before processing the requestÁ ü®œ( % .map_request(|request: String| {Á üÛœ% " println!("got request!");Á œ…� requestÁ T�� })Á ü¬�4 1 // Ensure our `ServiceBuilder` can be clonedÁ ´å� .check_clone()Á ü€ž4 1 // Do something after processing the requestÁ ü¹ž* ' .map_response(|response: String| {Á üèž& # println!("got response!");Á ¤“Ÿ responseÁ \¬Ÿ });Á <¼ŸßI\ÝŸ ¾¾ ؾ ,�
|
|||
|
|
è$éŸü¼¨e ü´ ^ [ Check that the builder when given a service of type `S` produces a service that implementsÁ d—¡ `Clone`.Á ¨¡ú ü°¡[žf �¢ú ü˜¢C‘g à¢ú lè¢ëg ú¢ú \‚£�h ô’£¤h µ£ú ´½£ # #[derive(Clone)]Á ¼Ø£ # struct MyService;Á ,ô£ #Á üþ£'Úh üª¤5Œi üä¤(Ìi ü‘¥%ÿi œ»¥®j TÓ¥Ëj üâ¥O L // Ensure that the service produced when given a `MyService` implementsÁ ü¶¦+ ( .check_service_clone::<MyService>()Á üæ¦4¿k üŸ§*þk üΧ&³l ¤ù§ãl \’¨�m <¢¨ßIœÃ¨ ¾¾ ¤ ûe ר ŒfDý¨ ØÍe ,›©
|
|||
|
|
èÈe$Ú¨/1 üœ·† üÀ©] Z Check that the builder when given a service of type `S` produces a service with the givenÁ ü¢ª' $ request, response, and error types.Á Ϊú üÖª[žf ¶«ú ü¾«C‘g †¬ú lŽ¬ëg ¬ú \¨¬�h ô¸¬¤h üÛ¬# use std::task::{Poll, Context};Á üƒ% " use tower::{Service, ServiceExt};Á ú ̵ // An example serviceÁ ¬Ó struct MyService;Á íú üõ) & impl Service<Request> for MyService {Á ü£® type Response = Response;Á ÌÇ® type Error = Error;Á üå®I F type Future = futures_util::future::Ready<Result<Response, Error>>;Á ³¯ú ü»¯W T fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {Á „—°
|
|||
|
|
// ...Á œ¬° # todo!()Á <Ä° }Á аú üØ°< 9 fn call(&mut self, request: Request) -> Self::Future {Á „™±�z œ®±©z <ƱÆz ,Ò± }Á ܱú œä± struct Request;Á ¤ü± struct Response;Á Œ•² struct Error;Á «²ú ü³²% " struct WrappedResponse(Response);Á ݲú üå²'Úh ü‘³Y V // At this point in the builder if given a `MyService` it produces a service thatÁ üï³L I // accepts `Request`s, produces `Response`s, and fails with `Error`sÁ üÀ´? < .check_service::<MyService, Request, Response, Error>()Á ü„µ. + // Wrap responses in `WrappedResponse`Á ü·µE B .map_response(|response: Response| WrappedResponse(response))Á ü�¶: 7 // Now the response type will be `WrappedResponse`Á üÀ¶= : .check_service::<MyService, _, WrappedResponse, _>();Á <‚·ßIl£· ¾¾ ¤ ¥ ¦ – ûe ±· Íì¥ ´· Íì¦ ·· Íì– º· ŒfDà· Íe±ƒ üþ·# Íe±ƒ Ńd‰¸ Íe±ƒ
|
|||
|
|
ÙƒL—¸
|
|||
|
|
èÈe±ƒÅƒÙƒ$½·§© ¢ ™› ’” ü…Ö4 � ! ! ®Z ŠÖ ¿cè T�Ö¾" Àc " !# üÀÖ8 ÃÖ ? @ A ?¾ @ c c ˆ ¢cµ
|
|||
|
|
` £c bufÁ ` àB¤GS
|
|||
|
|
AÖ¿Ù¿ Ú¿« Û¿ˆ Ü¿ Ý¿Þ¿ˆ ‚†f|Â
|
|||
|
|
ŸÈŸÈ È ErrorÁ O˜éBL ÇÖ
|
|||
|
|
"è$ÈÖ± ÎÖüÈ×@ ¤ $ � % % $ Íì— Í× Íì‘ Ð× Ú‘— Dÿ×ç&' Ü Ý ' ;= 79 d�Ø<”Ø # # ‘— Üü¯Ø*,²Ø B Bç —ç— Ü # ¸Ø #
|
|||
|
|
'—‘$¹ØÇ\,¿ØlŒF ü 2 / A collection of [`Layer`] based tower servicesÁ 3ú Ü7üO ,”F -±Dj *í,t Ú +Ø`<{ ê ,\\/1$&d¡ ü†" Utilities for combining layersÁ ©ú ü. + [`Identity`]: crate::layer::util::IdentityÁ ÜÜüO üø( % [`Stack`]: crate::layer::util::StackÁ $© ©DÊ ä /ýV,Ô ò 0\¼#%ôºGß ”ëHô ´–I
|
|||
|
|
TÉI 4ÍI 5œÚI 4äI 5 ¥ 6 5 6 Îì ´ÚI ˜^ ëI 5 ê� ê�$ " ŒœJ üôI' $ Alias for a type-erased error type.ÁD¥J �� ž BoxÁ ¡ˆˆ ¢‰ˆ l }.xÏ ¾ � ÌìçEçEèE GlobalÁ ¿±‡§í# äÁ ü‰/ , Declaratively construct [`Service`] values.Á ¹ú ü½Q N [`ServiceBuilder`] provides a [builder-like interface][builder] for composingÁ ü�* ' layers to be applied to a [`Service`].Á ºú l¾
|