Skip to content

Commit

Permalink
docs: update API documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@kikuomax
kikuomax committed Mar 25, 2024
1 parent 140d334 commit 2dfe61f
Show file tree
Hide file tree
Showing 75 changed files with 770 additions and 150 deletions.
2 changes: 1 addition & 1 deletion docs/api/search-index.js
View file

Large diffs are not rendered by default.

178 changes: 170 additions & 8 deletions docs/api/src/xray_lite/client.rs.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,87 @@
<a href="#80" id="80">80</a>
<a href="#81" id="81">81</a>
<a href="#82" id="82">82</a>
<a href="#83" id="83">83</a>
<a href="#84" id="84">84</a>
<a href="#85" id="85">85</a>
<a href="#86" id="86">86</a>
<a href="#87" id="87">87</a>
<a href="#88" id="88">88</a>
<a href="#89" id="89">89</a>
<a href="#90" id="90">90</a>
<a href="#91" id="91">91</a>
<a href="#92" id="92">92</a>
<a href="#93" id="93">93</a>
<a href="#94" id="94">94</a>
<a href="#95" id="95">95</a>
<a href="#96" id="96">96</a>
<a href="#97" id="97">97</a>
<a href="#98" id="98">98</a>
<a href="#99" id="99">99</a>
<a href="#100" id="100">100</a>
<a href="#101" id="101">101</a>
<a href="#102" id="102">102</a>
<a href="#103" id="103">103</a>
<a href="#104" id="104">104</a>
<a href="#105" id="105">105</a>
<a href="#106" id="106">106</a>
<a href="#107" id="107">107</a>
<a href="#108" id="108">108</a>
<a href="#109" id="109">109</a>
<a href="#110" id="110">110</a>
<a href="#111" id="111">111</a>
<a href="#112" id="112">112</a>
<a href="#113" id="113">113</a>
<a href="#114" id="114">114</a>
<a href="#115" id="115">115</a>
<a href="#116" id="116">116</a>
<a href="#117" id="117">117</a>
<a href="#118" id="118">118</a>
<a href="#119" id="119">119</a>
<a href="#120" id="120">120</a>
<a href="#121" id="121">121</a>
<a href="#122" id="122">122</a>
<a href="#123" id="123">123</a>
<a href="#124" id="124">124</a>
<a href="#125" id="125">125</a>
<a href="#126" id="126">126</a>
<a href="#127" id="127">127</a>
<a href="#128" id="128">128</a>
<a href="#129" id="129">129</a>
<a href="#130" id="130">130</a>
<a href="#131" id="131">131</a>
<a href="#132" id="132">132</a>
<a href="#133" id="133">133</a>
<a href="#134" id="134">134</a>
<a href="#135" id="135">135</a>
<a href="#136" id="136">136</a>
<a href="#137" id="137">137</a>
<a href="#138" id="138">138</a>
<a href="#139" id="139">139</a>
<a href="#140" id="140">140</a>
<a href="#141" id="141">141</a>
<a href="#142" id="142">142</a>
<a href="#143" id="143">143</a>
<a href="#144" id="144">144</a>
<a href="#145" id="145">145</a>
<a href="#146" id="146">146</a>
<a href="#147" id="147">147</a>
<a href="#148" id="148">148</a>
<a href="#149" id="149">149</a>
<a href="#150" id="150">150</a>
<a href="#151" id="151">151</a>
<a href="#152" id="152">152</a>
<a href="#153" id="153">153</a>
<a href="#154" id="154">154</a>
<a href="#155" id="155">155</a>
<a href="#156" id="156">156</a>
<a href="#157" id="157">157</a>
<a href="#158" id="158">158</a>
<a href="#159" id="159">159</a>
<a href="#160" id="160">160</a>
<a href="#161" id="161">161</a>
<a href="#162" id="162">162</a>
<a href="#163" id="163">163</a>
</pre></div><pre class="rust"><code><span class="doccomment">//! X-Ray daemon client.

</span><span class="kw">use </span>std::env;
Expand All @@ -91,13 +172,21 @@

<span class="kw">use </span><span class="kw">crate</span>::error::{Error, <span class="prelude-ty">Result</span>};

<span class="doccomment">/// X-Ray daemon client interface
<span class="doccomment">/// X-Ray client interface.
</span><span class="kw">pub trait </span>Client: Clone + std::fmt::Debug + Send + Sync {
<span class="doccomment">/// Sends a segment to the xray daemon this client is connected to.
</span><span class="kw">fn </span>send&lt;S&gt;(<span class="kw-2">&amp;</span><span class="self">self</span>, data: <span class="kw-2">&amp;</span>S) -&gt; <span class="prelude-ty">Result</span>&lt;()&gt;
<span class="kw">where
</span>S: Serialize;
}

<span class="doccomment">/// X-Ray daemon client.
</span><span class="attr">#[derive(Clone, Debug)]
</span><span class="kw">pub struct </span>Client {
</span><span class="kw">pub struct </span>DaemonClient {
socket: Arc&lt;UdpSocket&gt;,
}

<span class="kw">impl </span>Client {
<span class="kw">impl </span>DaemonClient {
<span class="kw">const </span>HEADER: <span class="kw-2">&amp;</span><span class="lifetime">'static </span>[u8] = <span class="string">br#"{"format": "json", "version": 1}"#</span>;
<span class="kw">const </span>DELIMITER: <span class="kw-2">&amp;</span><span class="lifetime">'static </span>[u8] = <span class="kw-2">&amp;</span>[<span class="string">b'\n'</span>];

Expand All @@ -107,7 +196,7 @@
<span class="kw">let </span>socket = Arc::new(UdpSocket::bind(<span class="kw-2">&amp;</span>[([<span class="number">0</span>, <span class="number">0</span>, <span class="number">0</span>, <span class="number">0</span>], <span class="number">0</span>).into()][..])<span class="question-mark">?</span>);
socket.set_nonblocking(<span class="bool-val">true</span>)<span class="question-mark">?</span>;
socket.connect(addr)<span class="question-mark">?</span>;
<span class="prelude-val">Ok</span>(Client { socket })
<span class="prelude-val">Ok</span>(DaemonClient { socket })
}

<span class="doccomment">/// Creates a new X-Ray client from the Lambda environment variable.
Expand All @@ -122,7 +211,7 @@
.map_err(|<span class="kw">_</span>| Error::MissingEnvVar(<span class="string">"AWS_XRAY_DAEMON_ADDRESS"</span>))<span class="question-mark">?
</span>.parse::&lt;SocketAddr&gt;()
.map_err(|e| Error::BadConfig(<span class="macro">format!</span>(<span class="string">"invalid X-Ray daemon address: {e}"</span>)))<span class="question-mark">?</span>;
Client::new(addr)
DaemonClient::new(addr)
}

<span class="attr">#[inline]
Expand All @@ -133,9 +222,10 @@
<span class="kw">let </span>bytes = serde_json::to_vec(<span class="kw-2">&amp;</span>data)<span class="question-mark">?</span>;
<span class="prelude-val">Ok</span>([<span class="self">Self</span>::HEADER, <span class="self">Self</span>::DELIMITER, <span class="kw-2">&amp;</span>bytes].concat())
}
}

<span class="doccomment">/// send a segment to the xray daemon this client is connected to
</span><span class="kw">pub fn </span>send&lt;S&gt;(<span class="kw-2">&amp;</span><span class="self">self</span>, data: <span class="kw-2">&amp;</span>S) -&gt; <span class="prelude-ty">Result</span>&lt;()&gt;
<span class="kw">impl </span>Client <span class="kw">for </span>DaemonClient {
<span class="kw">fn </span>send&lt;S&gt;(<span class="kw-2">&amp;</span><span class="self">self</span>, data: <span class="kw-2">&amp;</span>S) -&gt; <span class="prelude-ty">Result</span>&lt;()&gt;
<span class="kw">where
</span>S: Serialize,
{
Expand All @@ -144,13 +234,85 @@
}
}

<span class="doccomment">/// Infallible client.
</span><span class="attr">#[derive(Clone, Debug)]
</span><span class="kw">pub enum </span>InfallibleClient&lt;C&gt; {
<span class="doccomment">/// Operational client.
</span>Op(C),
<span class="doccomment">/// Non-operational client.
</span>Noop,
}

<span class="kw">impl</span>&lt;C&gt; InfallibleClient&lt;C&gt; {
<span class="doccomment">/// Creates a new infallible client from a result of client creation.
</span><span class="kw">pub fn </span>new&lt;E&gt;(result: std::result::Result&lt;C, E&gt;) -&gt; <span class="self">Self </span>{
<span class="kw">match </span>result {
<span class="prelude-val">Ok</span>(client) =&gt; <span class="self">Self</span>::Op(client),
<span class="prelude-val">Err</span>(<span class="kw">_</span>) =&gt; <span class="self">Self</span>::Noop,
}
}
}

<span class="kw">impl</span>&lt;C&gt; Client <span class="kw">for </span>InfallibleClient&lt;C&gt;
<span class="kw">where
</span>C: Client,
{
<span class="kw">fn </span>send&lt;S&gt;(<span class="kw-2">&amp;</span><span class="self">self</span>, data: <span class="kw-2">&amp;</span>S) -&gt; <span class="prelude-ty">Result</span>&lt;()&gt;
<span class="kw">where
</span>S: Serialize,
{
<span class="kw">match </span><span class="self">self </span>{
<span class="self">Self</span>::Op(client) =&gt; client.send(data),
<span class="self">Self</span>::Noop =&gt; <span class="prelude-val">Ok</span>(()),
}
}
}

<span class="doccomment">/// Conversion into an [`InfallibleClient`].
///
/// This is useful if you want to fall back to a "no-op" client if the creation
/// of a client fails.
///
/// ```
/// use xray_lite::{
/// Context as _,
/// CustomNamespace,
/// DaemonClient,
/// IntoInfallibleClient as _,
/// SubsegmentContext,
/// };
///
/// let client = DaemonClient::from_lambda_env().into_infallible();
/// # std::env::set_var("_X_AMZN_TRACE_ID", "Root=1-5759e988-bd862e3fe1be46a994272793;Parent=53995c3f42cd8ad8;Sampled=1");
/// let context = SubsegmentContext::from_lambda_env(client).unwrap();
/// let _session = context.enter_subsegment(CustomNamespace::new("readme.example"));
/// ```
</span><span class="kw">pub trait </span>IntoInfallibleClient {
<span class="doccomment">/// Client type.
</span><span class="kw">type </span>Client: Client;

<span class="doccomment">/// Converts a value into an [`InfallibleClient`].
</span><span class="kw">fn </span>into_infallible(<span class="self">self</span>) -&gt; InfallibleClient&lt;<span class="self">Self</span>::Client&gt;;
}

<span class="kw">impl</span>&lt;C&gt; IntoInfallibleClient <span class="kw">for </span>std::result::Result&lt;C, Error&gt;
<span class="kw">where
</span>C: Client,
{
<span class="kw">type </span>Client = C;

<span class="kw">fn </span>into_infallible(<span class="self">self</span>) -&gt; InfallibleClient&lt;C&gt; {
InfallibleClient::new(<span class="self">self</span>)
}
}

<span class="attr">#[cfg(test)]
</span><span class="kw">mod </span>tests {
<span class="kw">use super</span>::<span class="kw-2">*</span>;
<span class="attr">#[test]
</span><span class="kw">fn </span>client_prefixes_packets_with_header() {
<span class="macro">assert_eq!</span>(
Client::packet(<span class="macro">serde_json::json!</span>({
DaemonClient::packet(<span class="macro">serde_json::json!</span>({
<span class="string">"foo"</span>: <span class="string">"bar"
</span>}))
.unwrap(),
Expand Down
Loading

0 comments on commit 2dfe61f

Please sign in to comment.