64 lines
34 KiB
Plaintext
64 lines
34 KiB
Plaintext
|
rust
|
|||
|
|
¡† #rustc 1.93.0 (254b59607 2026-01-19)Á“õ…·fÊvŠ ¦%g- -c48c539199cbc88bÁ ³VOÐêùÿ²?ÑL¼�§Ì± -a7a40eb546f9e2b0Á á\ƒ¦è3$|]åŒ[IÚ tæ -14b12edc9f8cd90bÁ ë&Gf·Ã ¬ëñq:¤»b -bb76018b1173caf6Áà 9m Ù„«ÐÒþá•c‘B; -030c5b0bba47cc8fÁ rustc_std_workspace_coreÁÛ¹þÓ7>H%¸ÚÉ’› -4b81d37a5530864dÁ üÃùs<Uß7VyóHr#QÏ -c66cc7807550ce25Á miniz_oxideÁõFÖˆÚ™ª‹"ÞXzLVª -62cbc7af83058505Á adler2Á—wÉD‘嵯�|6¨%Œ
|
|||
|
|
+ -2f171dd2394b4b62Á hashbrownÁ,ïcV¼¨ø¢:Ê\'È߈ -9571ba9e0f6c7a90Á rustc_std_workspace_allocÁ%¥Èxµù·¼5Ä3Bœ -aac566ad65903fa4Á
|
|||
|
|
std_detectÁMmáýZ^9õ Îà§e˜÷e -2edb296e590136d8Á rustc_demangleÁ@¼§VÉNb˜æ¨fHÌ+V3 -53b132e4a2fa6e26Á cfg_ifÁfÝv�.Å"ÒÜuPp¹ˆ¶ -f76b385d7d4d7f3eÁ addr2lineÁÕú-WiúQVÓ¬
|
|||
|
|
µT§�5 -fe25100bd73e48e4Á gimliÁ¹xLáÇí÷‘o ±Ñ8£Å -265ba9e6e4f70b3fÁ objectÁÔ³ÝzÓÿ¶ò°öM›¼òü` -9ae0d1f8ea52a318Á memchrÁRÎ÷׎™te~QÓ¿ØC\Ò -0bff3c8e8f4e489eÁ –©H�tGNÏ ·ˆ!á -d69228d077d46f36Á tower_layerÁŸR1Ä‘ç.¥÷Y
|
|||
|
|
qP\õ -bf470bb9a123643cÁ
|
|||
|
|
tower_serviceÁ'²4"´V \OZEBó -4cdd26a04149612eÁ
|
|||
|
|
opaque_futureÁl| ¶< utilÁ4 „ ¶<% spawn-readyÁl/ ¼% ¶<B filterÁDL ”B ¶<Z makeÁ4d „Z ü c balanceÁ<»9¶<�9¨ L§9œ�9 bufferÁ4ç9¶<Ê9Í DÔ9”Ê9 discoverÁD”:¶<õ9ñ Tÿ9¤õ9 ý4Á:¶<¤:ýD®:”¤: hedgeÁ,ë:¶<Ï:µ
|
|||
|
|
<Ù:ŒÏ: limitÁ,”;¶<ø:Ø
|
|||
|
|
<‚;Œø: Ù $¼;¶<¡;Ù 4«;„¡; load_shedÁLè;¶<È; load-shedÁ\Ò;¬È; ” $•<¶<ú;” 4„<„ú; ready_cacheÁ\Ã<¶<¡< ready-cacheÁl«<¼¡< reconnectÁLö<¶<Ö<› \à<¬Ö< retryÁ,£=¶<‡= <‘=Œ‡= spawn_readyÁ\Ò=¶<°=álº=¼°= steerÁ,�>¶<å=Ž
|
|||
|
|
<ï=Œå= timeoutÁ<¬>¶<Ž>±
|
|||
|
|
L˜>œŽ> Ì$Ö>¶<»>Ì4Å>„»>
|
|||
|
|
service_fnÁTë?¶<„?Ì4Ž?„„?
|
|||
|
|
ServiceExtÁT÷?¶(Ì&$& MakeServiceÁ\ªA¶<Ã@” 4Í@„Ã@ sealedÁ4ûB¶<¸B¨ LÂBœ¸B¶<ÍBñ T×B¤ÍB¶<ãB” 4íB„ãBü·B= “ macrosÁ builderÁ >
|
|||
|
|
• LÁ layerÁ ™ layer_fnÁ FÁ
|
|||
|
|
into_innerÁ serviceÁ SÁ check_cloneÁ check_service_cloneÁ ç
|
|||
|
|
check_serviceÁ ç ™ UÁ EÁ – Í #ç #– # ServiceÁ #ž ž ( ((((Ì - -- BoxErrorÁ ServiceBuilderÁ 5– 5ž 8– 8È
|
|||
|
|
"
|
|||
|
|
"
|
|||
|
|
"
|
|||
|
|
'
|
|||
|
|
:
|
|||
|
|
Þ 5 5 Ò 7ž æûγ¿ ë¸ – Ä 5 5 Ò 7ž æûγ¿ ë¸ää IdentityÁ å _pÁ ÇIå;Ñ( º à` Ú 5 5 Ò 7ž æûγ¿ 븖 ç 8 5 5 5# 5ÞÄà`Ú@ä É
|
|||
|
|
ßÉ , 4 (¹
|
|||
|
|
5 É ¾ : + 6 @ É É ‰ Z d Ç¥ |ë
|
|||
|
|
lë
|
|||
|
|
& üÇ >
|
|||
|
|
5 ÿ „ ‹ ü¢ i Ö $¸ ÿ s T²! É ì ! T !
|
|||
|
|
"™É ,«! : / üü L
|
|||
|
|
5 òò StackÁ õ innerÁ ö outerÁ :ÖᎠ@$…É Î! ü³ › 5 5 Ò 7ž æûγ¿ 븴 ÜÖ $à … ,É ´ ù É # ž' { €* $Î*
|
|||
|
|
& ÌÙ* ´Ù*
|
|||
|
|
À ð* ' üÎ*% ,Ó*
|
|||
|
|
Éêê LayerFnÁ ìþ ð£$Ä׋]í  ” üÓ* ò*
|
|||
|
|
ù* üï)Š , < 1 5 5 Ò 7ž æûγ¿ ë¸òò ¾ õÌ öÜ :ÖᎠ@$° É ü‘*2 $‚* í ˆ* ² ° ‡ ê * þ. ê è· ¨ ’ T’ƒ É ¢ƒ üë‚7 É †ƒ $ý‚ / TÝ… É ÌÝ… ,è…
|
|||
|
|
ÝÉç 8 <î… tè… ü… üý„ ɺ Ü T¥… ™ ,�… º <–… ª ˜ Ù W ± « $¦™ °™ üؘX $ô˜ $ë˜ / $²¢ ¼¢ ü¾¡~ $å¡ $Ü¡ / $ª± ´± ü•°Ÿ $¿° $¶° 0 „Øß üÊß \Ìß
|
|||
|
|
¦a Êß = ìÌß 3 \ðß É à` üÊß2 ,êß
|
|||
|
|
‘^ Ž S ”êß üÊß; 4ýß
|
|||
|
|
˜^ R Dýß ‹à " ü‡ß„ ê³í³ î³Ò ï³ì ð³ ñ³“ò³ì äs{ ©¶‘ ѼѼҼ” štÀ. \´ß ™ ,Žß Á`Á` œ Ã`è Á] Ä` bufÁÁ] Ê\É:• •ß „^„^
|
|||
|
|
DebugTupleÁ ‡^ÍÖ] ˆ^Û
|
|||
|
|
Ö] ‰^ fieldsÁÖ] Š^
|
|||
|
|
empty_nameÁÖ] JžÛœŽ÷³Õ Ä Í' < Ï' D „$ e ì$ ª ó þ¸ š œ$‡ªì$O Œ%% À%÷ T«á ï ¼«á ,¶á
|
|||
|
|
Ýïõ 5 ,¼á d¶á Èá ' üöàR ïõÜ l“á Æ ,ÿà õ ,†á ï › Ì# ] Ø)® (4“ Òt¬@ 5 1 LayerÁ,ÜA Ú 2ø<ŠB 3ü ‡D üÌ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.Á …Ë ü‰P M Generic components, like [`timeout`], [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.Á üÝ%5 2 * [`tower-lsp`]: implementations of the [LanguageÁ ü“&+ ( Server Protocol][lsp] based on Tower.Á ¿&Ë üÃ&- * [`hyper`]:
|
|||
|
|
ü6%[]MO?A´a4D~(üñ) Ö Å ¤¡ <¤ Ö
|
|||
|
|
ìÕ Ö Ô¢ üù $ ! 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.Á ‹ Ë Ü“ Ëd,º …£ ™ ©â… À
|
|||
|
|
É…Ø žá üï)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ö) í× À ©âí ÿ)
|
|||
|
|
ÉíÇþÐ äë‚ ü´‚2 / Returns the underlying `Layer` implementation.ÁTò‚ É
|
|||
|
|
Éfüý„Q ü¨ƒ= : Wrap the service `S` with the middleware provided by thisÁ üêƒB ? [`ServiceBuilder`]'s [`Layer`]'s, returning a new [`Service`].Á ±„Ë Ü¹„Ëd üÙ„ ¤d<„… ; ; º ø ç �… ©âº Œ… Úɺ DÅ…
|
|||
|
|
ɺ $�…Ù13 üؘ? ü‚’. + 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Á \®˜ });Á <¾˜Ì^\ߘ Þ ,‘™
|
|||
|
|
É�ü¾¡e ü¶™^ [ Check that the builder when given a service of type `S` produces a service that implementsÁ d™š `Clone`.Á ªšË ü²š[÷w ’›Ë üš›Cèx â›Ë lê›Ày ü›Ë \„œây ô”œöy ·œË ´¿œ # #[derive(Clone)]Á ¼Úœ # struct MyService;Á ,öœ #Á ü€�'ªz ü¬�5Ûz üæ�(š{ ü“ž%Ì{ œ½žú{ TÕž–| üäžO L // Ensure that the service produced when given a `MyService` implementsÁ ü¸Ÿ+ ( .check_service_clone::<MyService>()Á üèŸ4‡} ü¡ *Å} üÐ &ù} ¤û ¨~ \”¡Å~ <¤¡Ì^œÅ¡ ç Ùw Ù¡ êwDÿ¡ Þø ,�¢
|
|||
|
|
ɺ î-/ ü•°† ü¢] Z Check that the builder when given a service of type `S` produces a service with the givenÁ ü¤£' $ request, response, and error types.Á Ð£Ë üØ£[÷w ¸¤Ë üÀ¤Cèx ˆ¥Ë l�¥Ày ¢¥Ë \ª¥ây ôº¥öy üÝ¥# 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;Á üç§@ = type Future = std::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 {Á „’ªŽ‹ œ§ª§‹ <¿ªÃ‹ ,˪ }Á ÕªË œÝª struct Request;Á ¤õª struct Response;Á ŒŽ« struct Error;Á ¤«Ë ü¬«% " struct WrappedResponse(Response);Á Ö«Ë üÞ«'ªz üŠ¬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, _>();Á <û¯Ì^lœ° ç ™ Ä Ì Ùw ª° ©â™ ° ©âÄ °° ©âÌ ³° êwDÙ° ø š” ü÷°# ø š” ®”d‚± ø š”
|