Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Reorganize the src folder and add API documentation #3

Merged
merged 10 commits into from
Mar 7, 2024
Merged

Reorganize the src folder and add API documentation #3

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
f0b0e7e
refactor(xray-lite): move Result to error
kikuomax Mar 6, 2024
67b9e21
refactor(xray-lite): move Client to client submodule
kikuomax Mar 6, 2024
42d540d
refactor(xray-lite): move Namespace to namespace
kikuomax Mar 6, 2024
dcc6ae9
refactor(xray-lite): move SubsegmentSession to session
kikuomax Mar 7, 2024
7c3549a
refactor(xray-lite): move Context to context
kikuomax Mar 7, 2024
51e1c64
chore(xray-lite): solve ambiguous links in doc comments
kikuomax Mar 7, 2024
0125a35
chore(xray-lite): bump version to 0.0.5
kikuomax Mar 7, 2024
8b2ba45
docs: update README
kikuomax Mar 7, 2024
a43c180
docs: add API documentation
kikuomax Mar 7, 2024
559aa01
docs: include API doc link in README
kikuomax Mar 7, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ Add the following to your `Cargo.toml` file:

```toml
[dependencies]
xray-lite = { git = "https://github.com/codemonger-io/xray-lite.git", tag = "v0.0.4" }
xray-lite = { git = "https://github.com/codemonger-io/xray-lite.git", tag = "v0.0.5" }
```

## Usage
Expand Down Expand Up @@ -106,6 +106,10 @@ fn do_something(context: &impl Context) {
}
```

## API Documentation

<https://codemonger-io.github.io/xray-lite/api/xray_lite/>

## Acknowledgements

This project is built on top of the [great work](https://github.com/softprops/xray) of [Doug Tangren (softprops)](https://github.com/softprops).
Empty file added docs/api/.lock
View file
Open in desktop
Empty file.
1 change: 1 addition & 0 deletions docs/api/crates.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
window.ALL_CRATES = ["xray_lite"];
2 changes: 2 additions & 0 deletions docs/api/help.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
<!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="Documentation for Rustdoc"><title>Help</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="xray_lite" 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="./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 sys"><!--[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><a class="logo-container" href="./index.html"><img class="rust-logo" src="./static.files/rust-logo-151179464ae7ed46.svg" alt=""></a></nav><nav class="sidebar"><div class="sidebar-crate"><a class="logo-container" href="./index.html"><img class="rust-logo" src="./static.files/rust-logo-151179464ae7ed46.svg" alt="logo"></a><h2><a href="./index.html">Rustdoc</a><span class="version">1.76.0</span></h2></div><div class="version">(07dca489a 2024-02-04)</div><h2 class="location">Help</h2><div class="sidebar-elems"></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="./xray_lite/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>Rustdoc help</h1><span class="out-of-band"><a id="back" href="javascript:void(0)" onclick="history.back();">Back</a></span></div><noscript><section><p>You need to enable JavaScript to use keyboard commands or search.</p><p>For more information, browse the <a href="https://doc.rust-lang.org/rustdoc/">rustdoc handbook</a>.</p></section></noscript></section></div></main></body></html>
5 changes: 5 additions & 0 deletions docs/api/search-index.js
View file
Open in desktop

Large diffs are not rendered by default.

2 changes: 2 additions & 0 deletions docs/api/settings.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
<!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="Settings of Rustdoc"><title>Settings</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="xray_lite" 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="./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 sys"><!--[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><a class="logo-container" href="./index.html"><img class="rust-logo" src="./static.files/rust-logo-151179464ae7ed46.svg" alt=""></a></nav><nav class="sidebar"><div class="sidebar-crate"><a class="logo-container" href="./index.html"><img class="rust-logo" src="./static.files/rust-logo-151179464ae7ed46.svg" alt="logo"></a><h2><a href="./index.html">Rustdoc</a><span class="version">1.76.0</span></h2></div><div class="version">(07dca489a 2024-02-04)</div><h2 class="location">Settings</h2><div class="sidebar-elems"></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="./xray_lite/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>Rustdoc settings</h1><span class="out-of-band"><a id="back" href="javascript:void(0)" onclick="history.back();">Back</a></span></div><noscript><section>You need to enable JavaScript be able to update your settings.</section></noscript><script defer src="./static.files/settings-4313503d2e1961c2.js"></script></section></div></main></body></html>
4 changes: 4 additions & 0 deletions docs/api/src-files.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
var srcIndex = new Map(JSON.parse('[\
["xray_lite",["",[],["client.rs","context.rs","epoch.rs","error.rs","header.rs","hexbytes.rs","lambda.rs","lib.rs","namespace.rs","segment.rs","segment_id.rs","session.rs","trace_id.rs"]]]\
]'));
createSrcSidebar();
166 changes: 166 additions & 0 deletions docs/api/src/xray_lite/client.rs.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,166 @@
<!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="Source of the Rust file `xray-lite/src/client.rs`."><title>client.rs - source</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="xray_lite" 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="../../static.files/src-script-39ed315d46fb705f.js"></script><script defer src="../../src-files.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 src"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="sidebar"></nav><div class="sidebar-resizer"></div>
<main><nav class="sub"><form class="search-form"><span></span><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="example-wrap"><div data-nosnippet><pre class="src-line-numbers"><a href="#1" id="1">1</a>
<a href="#2" id="2">2</a>
<a href="#3" id="3">3</a>
<a href="#4" id="4">4</a>
<a href="#5" id="5">5</a>
<a href="#6" id="6">6</a>
<a href="#7" id="7">7</a>
<a href="#8" id="8">8</a>
<a href="#9" id="9">9</a>
<a href="#10" id="10">10</a>
<a href="#11" id="11">11</a>
<a href="#12" id="12">12</a>
<a href="#13" id="13">13</a>
<a href="#14" id="14">14</a>
<a href="#15" id="15">15</a>
<a href="#16" id="16">16</a>
<a href="#17" id="17">17</a>
<a href="#18" id="18">18</a>
<a href="#19" id="19">19</a>
<a href="#20" id="20">20</a>
<a href="#21" id="21">21</a>
<a href="#22" id="22">22</a>
<a href="#23" id="23">23</a>
<a href="#24" id="24">24</a>
<a href="#25" id="25">25</a>
<a href="#26" id="26">26</a>
<a href="#27" id="27">27</a>
<a href="#28" id="28">28</a>
<a href="#29" id="29">29</a>
<a href="#30" id="30">30</a>
<a href="#31" id="31">31</a>
<a href="#32" id="32">32</a>
<a href="#33" id="33">33</a>
<a href="#34" id="34">34</a>
<a href="#35" id="35">35</a>
<a href="#36" id="36">36</a>
<a href="#37" id="37">37</a>
<a href="#38" id="38">38</a>
<a href="#39" id="39">39</a>
<a href="#40" id="40">40</a>
<a href="#41" id="41">41</a>
<a href="#42" id="42">42</a>
<a href="#43" id="43">43</a>
<a href="#44" id="44">44</a>
<a href="#45" id="45">45</a>
<a href="#46" id="46">46</a>
<a href="#47" id="47">47</a>
<a href="#48" id="48">48</a>
<a href="#49" id="49">49</a>
<a href="#50" id="50">50</a>
<a href="#51" id="51">51</a>
<a href="#52" id="52">52</a>
<a href="#53" id="53">53</a>
<a href="#54" id="54">54</a>
<a href="#55" id="55">55</a>
<a href="#56" id="56">56</a>
<a href="#57" id="57">57</a>
<a href="#58" id="58">58</a>
<a href="#59" id="59">59</a>
<a href="#60" id="60">60</a>
<a href="#61" id="61">61</a>
<a href="#62" id="62">62</a>
<a href="#63" id="63">63</a>
<a href="#64" id="64">64</a>
<a href="#65" id="65">65</a>
<a href="#66" id="66">66</a>
<a href="#67" id="67">67</a>
<a href="#68" id="68">68</a>
<a href="#69" id="69">69</a>
<a href="#70" id="70">70</a>
<a href="#71" id="71">71</a>
<a href="#72" id="72">72</a>
<a href="#73" id="73">73</a>
<a href="#74" id="74">74</a>
<a href="#75" id="75">75</a>
<a href="#76" id="76">76</a>
<a href="#77" id="77">77</a>
<a href="#78" id="78">78</a>
<a href="#79" id="79">79</a>
<a href="#80" id="80">80</a>
<a href="#81" id="81">81</a>
<a href="#82" id="82">82</a>
</pre></div><pre class="rust"><code><span class="doccomment">//! X-Ray daemon client.

</span><span class="kw">use </span>std::env;
<span class="kw">use </span>std::net::{SocketAddr, UdpSocket};
<span class="kw">use </span>std::sync::Arc;

<span class="kw">use </span>serde::Serialize;

<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><span class="attr">#[derive(Clone, Debug)]
</span><span class="kw">pub struct </span>Client {
socket: Arc&lt;UdpSocket&gt;,
}

<span class="kw">impl </span>Client {
<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>];

<span class="doccomment">/// Return a new X-Ray client connected
/// to the provided `addr`
</span><span class="kw">pub fn </span>new(addr: SocketAddr) -&gt; <span class="prelude-ty">Result</span>&lt;<span class="self">Self</span>&gt; {
<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="doccomment">/// Creates a new X-Ray client from the Lambda environment variable.
///
/// The following environment variable must be set:
/// - `AWS_XRAY_DAEMON_ADDRESS`: X-Ray daemon address
///
/// Please refer to the [AWS documentation](https://docs.aws.amazon.com/lambda/latest/dg/configuration-envvars.html#configuration-envvars-runtime)
/// for more details.
</span><span class="kw">pub fn </span>from_lambda_env() -&gt; <span class="prelude-ty">Result</span>&lt;<span class="self">Self</span>&gt; {
<span class="kw">let </span>addr: SocketAddr = env::var(<span class="string">"AWS_XRAY_DAEMON_ADDRESS"</span>)
.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)
}

<span class="attr">#[inline]
</span><span class="kw">fn </span>packet&lt;S&gt;(data: S) -&gt; <span class="prelude-ty">Result</span>&lt;Vec&lt;u8&gt;&gt;
<span class="kw">where
</span>S: Serialize,
{
<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">where
</span>S: Serialize,
{
<span class="self">self</span>.socket.send(<span class="kw-2">&amp;</span><span class="self">Self</span>::packet(data)<span class="question-mark">?</span>)<span class="question-mark">?</span>;
<span class="prelude-val">Ok</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>({
<span class="string">"foo"</span>: <span class="string">"bar"
</span>}))
.unwrap(),
[
<span class="string">br#"{"format": "json", "version": 1}"# </span><span class="kw">as </span><span class="kw-2">&amp;</span>[u8],
<span class="kw-2">&amp;</span>[<span class="string">b'\n'</span>],
<span class="string">br#"{"foo":"bar"}"#</span>,
]
.concat()
)
}
}
</code></pre></div></section></main></body></html>
Loading