OMGeeky/google-apis-rs
1
0
Fork 0
mirror of https://github.com/OMGeeky/google-apis-rs.git synced 2026-01-30 22:03:40 +01:00
Code Issues Packages Projects Releases Wiki Activity
Files
f4bb79d2d629ee5166f17b80ca2aa0e621d1c837
google-apis-rs/tokio_rustls/index.html
Sebastian Thiel f4bb79d2d6 Update documentation
2024-03-05 21:06:01 +01:00

29 lines
9.5 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="generator" content="rustdoc"><meta name="description" content="Asynchronous TLS/SSL streams for Tokio using Rustls."><title>tokio_rustls - Rust</title><link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/SourceSerif4-Regular-46f98efaafac5295.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/FiraSans-Regular-018c141bf0843ffd.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/FiraSans-Medium-8f9a781e4970d388.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/SourceCodePro-Regular-562dcc5011b6de7d.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/SourceCodePro-Semibold-d899c5a5c4aeb14a.ttf.woff2"><link rel="stylesheet" href="../static.files/normalize-76eba96aa4d2e634.css"><link rel="stylesheet" href="../static.files/rustdoc-ac92e1bbe349e143.css"><meta name="rustdoc-vars" data-root-path="../" data-static-root-path="../static.files/" data-current-crate="tokio_rustls" data-themes="" data-resource-suffix="" data-rustdoc-version="1.76.0 (07dca489a 2024-02-04)" data-channel="1.76.0" data-search-js="search-2b6ce74ff89ae146.js" data-settings-js="settings-4313503d2e1961c2.js" ><script src="../static.files/storage-f2adc0d6ca4d09fb.js"></script><script defer src="../crates.js"></script><script defer src="../static.files/main-305769736d49e732.js"></script><noscript><link rel="stylesheet" href="../static.files/noscript-feafe1bb7466e4bd.css"></noscript><link rel="alternate icon" type="image/png" href="../static.files/favicon-16x16-8b506e7a72182f1c.png"><link rel="alternate icon" type="image/png" href="../static.files/favicon-32x32-422f7d1d52889060.png"><link rel="icon" type="image/svg+xml" href="../static.files/favicon-2c020d218678b618.svg"></head><body class="rustdoc mod crate"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="mobile-topbar"><button class="sidebar-menu-toggle">&#9776;</button></nav><nav class="sidebar"><div class="sidebar-crate"><h2><a href="../tokio_rustls/index.html">tokio_rustls</a><span class="version">0.24.1</span></h2></div><div class="sidebar-elems"><ul class="block">
<li><a id="all-types" href="all.html">All Items</a></li></ul><section><ul class="block"><li><a href="#reexports">Re-exports</a></li><li><a href="#modules">Modules</a></li><li><a href="#structs">Structs</a></li><li><a href="#enums">Enums</a></li></ul></section></div></nav><div class="sidebar-resizer"></div>
<main><div class="width-limiter"><nav class="sub"><form class="search-form"><span></span><div id="sidebar-button" tabindex="-1"><a href="../tokio_rustls/all.html" title="show sidebar"></a></div><input class="search-input" name="search" aria-label="Run search in the documentation" autocomplete="off" spellcheck="false" placeholder="Click or press ‘S’ to search, ‘?’ for more options…" type="search"><div id="help-button" tabindex="-1"><a href="../help.html" title="help">?</a></div><div id="settings-menu" tabindex="-1"><a href="../settings.html" title="settings"><img width="22" height="22" alt="Change settings" src="../static.files/wheel-7b819b6101059cd0.svg"></a></div></form></nav><section id="main-content" class="content"><div class="main-heading"><h1>Crate <a class="mod" href="#">tokio_rustls</a><button id="copy-path" title="Copy item path to clipboard"><img src="../static.files/clipboard-7571035ce49a181d.svg" width="19" height="18" alt="Copy item path"></button></h1><span class="out-of-band"><a class="src" href="../src/tokio_rustls/lib.rs.html#1-553">source</a> · <button id="toggle-all-docs" title="collapse all docs">[<span>&#x2212;</span>]</button></span></div><details class="toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p>Asynchronous TLS/SSL streams for Tokio using <a href="https://github.com/rustls/rustls">Rustls</a>.</p>
<h2 id="why-do-i-need-to-call-poll_flush"><a href="#why-do-i-need-to-call-poll_flush">Why do I need to call <code>poll_flush</code>?</a></h2>
<p>Most TLS implementations will have an internal buffer to improve throughput,
and rustls is no exception.</p>
<p>When we write data to <code>TlsStream</code>, we always write rustls buffer first,
then take out rustls encrypted data packet, and write it to data channel (like TcpStream).
When data channel is pending, some data may remain in rustls buffer.</p>
<p><code>tokio-rustls</code> To keep it simple and correct, <a href="enum.TlsStream.html" title="enum tokio_rustls::TlsStream">TlsStream</a> will behave like <code>BufWriter</code>.
For <code>TlsStream&lt;TcpStream&gt;</code>, this means that data written by <code>poll_write</code> is not guaranteed to be written to <code>TcpStream</code>.
You must call <code>poll_flush</code> to ensure that it is written to <code>TcpStream</code>.</p>
<p>You should call <code>poll_flush</code> at the appropriate time,
such as when a period of <code>poll_write</code> write is complete and there is no more data to write.</p>
<h3 id="why-dont-we-write-during-poll_read"><a href="#why-dont-we-write-during-poll_read">Why don’t we write during <code>poll_read</code>?</a></h3>
<p>We did this in the early days of <code>tokio-rustls</code>, but it caused some bugs.
We can solve these bugs through some solutions, but this will cause performance degradation (reverse false wakeup).</p>
<p>And reverse write will also prevent us implement full duplex in the future.</p>
<p>see <a href="https://github.com/tokio-rs/tls/issues/40">https://github.com/tokio-rs/tls/issues/40</a></p>
<h3 id="why-cant-we-handle-it-like-native-tls"><a href="#why-cant-we-handle-it-like-native-tls">Why can’t we handle it like <code>native-tls</code>?</a></h3>
<p>When data channel returns to pending, <code>native-tls</code> will falsely report the number of bytes it consumes.
This means that if data written by <code>poll_write</code> is not actually written to data channel, it will not return <code>Ready</code>.
Thus avoiding the call of <code>poll_flush</code>.</p>
<p>but which does not conform to convention of <code>AsyncWrite</code> trait.
This means that if you give inconsistent data in two <code>poll_write</code>, it may cause unexpected behavior.</p>
<p>see <a href="https://github.com/tokio-rs/tls/issues/41">https://github.com/tokio-rs/tls/issues/41</a></p>
</div></details><h2 id="reexports" class="section-header"><a href="#reexports">Re-exports</a></h2><ul class="item-table"><li><div class="item-name" id="reexport.rustls"><code>pub use <a class="mod" href="../rustls/index.html" title="mod rustls">rustls</a>;</code></div></li></ul><h2 id="modules" class="section-header"><a href="#modules">Modules</a></h2><ul class="item-table"><li><div class="item-name"><a class="mod" href="client/index.html" title="mod tokio_rustls::client">client</a></div></li><li><div class="item-name"><a class="mod" href="server/index.html" title="mod tokio_rustls::server">server</a></div></li></ul><h2 id="structs" class="section-header"><a href="#structs">Structs</a></h2><ul class="item-table"><li><div class="item-name"><a class="struct" href="struct.Accept.html" title="struct tokio_rustls::Accept">Accept</a></div><div class="desc docblock-short">Future returned from <code>TlsAcceptor::accept</code> which will resolve
once the accept handshake has finished.</div></li><li><div class="item-name"><a class="struct" href="struct.Connect.html" title="struct tokio_rustls::Connect">Connect</a></div><div class="desc docblock-short">Future returned from <code>TlsConnector::connect</code> which will resolve
once the connection handshake has finished.</div></li><li><div class="item-name"><a class="struct" href="struct.FallibleAccept.html" title="struct tokio_rustls::FallibleAccept">FallibleAccept</a></div><div class="desc docblock-short">Like <a href="struct.Accept.html" title="struct tokio_rustls::Accept">Accept</a>, but returns <code>IO</code> on failure.</div></li><li><div class="item-name"><a class="struct" href="struct.FallibleConnect.html" title="struct tokio_rustls::FallibleConnect">FallibleConnect</a></div><div class="desc docblock-short">Like <a href="struct.Connect.html" title="struct tokio_rustls::Connect">Connect</a>, but returns <code>IO</code> on failure.</div></li><li><div class="item-name"><a class="struct" href="struct.LazyConfigAcceptor.html" title="struct tokio_rustls::LazyConfigAcceptor">LazyConfigAcceptor</a></div></li><li><div class="item-name"><a class="struct" href="struct.StartHandshake.html" title="struct tokio_rustls::StartHandshake">StartHandshake</a></div></li><li><div class="item-name"><a class="struct" href="struct.TlsAcceptor.html" title="struct tokio_rustls::TlsAcceptor">TlsAcceptor</a></div><div class="desc docblock-short">A wrapper around a <code>rustls::ServerConfig</code>, providing an async <code>accept</code> method.</div></li><li><div class="item-name"><a class="struct" href="struct.TlsConnector.html" title="struct tokio_rustls::TlsConnector">TlsConnector</a></div><div class="desc docblock-short">A wrapper around a <code>rustls::ClientConfig</code>, providing an async <code>connect</code> method.</div></li></ul><h2 id="enums" class="section-header"><a href="#enums">Enums</a></h2><ul class="item-table"><li><div class="item-name"><a class="enum" href="enum.TlsStream.html" title="enum tokio_rustls::TlsStream">TlsStream</a></div><div class="desc docblock-short">Unified TLS stream type</div></li></ul></section></div></main></body></html>
Reference in New Issue View Git Blame Copy Permalink