<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Francis Stephan on Medium]]></title>
        <description><![CDATA[Stories by Francis Stephan on Medium]]></description>
        <link>https://medium.com/@francis.stephan?source=rss-52a738199362------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*dmbNkD5D-u45r44go_cf0g.png</url>
            <title>Stories by Francis Stephan on Medium</title>
            <link>https://medium.com/@francis.stephan?source=rss-52a738199362------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Thu, 19 Nov 2026 15:41:15 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@francis.stephan/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Basic rust command line skills: arguments, files and strings]]></title>
            <link>https://medium.com/@francis.stephan/basic-rust-command-line-skills-arguments-files-and-strings-3a88cb2479c0?source=rss-52a738199362------2</link>
            <guid isPermaLink="false">https://medium.com/p/3a88cb2479c0</guid>
            <category><![CDATA[command-line]]></category>
            <category><![CDATA[rust-programming]]></category>
            <category><![CDATA[tutorial]]></category>
            <dc:creator><![CDATA[Francis Stephan]]></dc:creator>
            <pubDate>Tue, 19 Aug 2025 19:39:28 GMT</pubDate>
            <atom:updated>2025-08-20T07:35:54.911Z</atom:updated>
            <content:encoded><![CDATA[<p>After developing htmltable, a small command line program in rust, to convert a CSV table to an html table, I decided to write a small memo for my own use hoping it can also be useful for some other people. You can get the program on github (<a href="https://github.com/francisstephan/htmltable">https://github.com/francisstephan/htmltable</a>), where non members can also read the same text.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/671/1*_gwNOk6qnnitSNn4JCHMsg.png" /><figcaption>Two html tables …</figcaption></figure><p>After a brief description of what the program does, I shall present three basic skills for rust command line programming: parsing arguments, reading and writing files, and using strings.</p><h3>1. Program description</h3><p>If you download the program and run it with cargo run -- -h , you will get the following text:</p><p>Program to build an html table from a list of lines with optional separator and conversely to convert html table to CSV (using comma or any separator character)</p><p>Usage: htmltable [OPTIONS] — input &lt;INPUT&gt; --output &lt;OUTPUT&gt;</p><p>Options:</p><p>-i, — input &lt;INPUT&gt; : Path of input file, relative to current path</p><p>-o, — output &lt;OUTPUT&gt; : Path of output file, relative to current path</p><p>-s, — separator &lt;SEPARATOR&gt; : Character to be used as separator in lines of input file [default: &#39; &#39;]</p><p>-r, — reverse : Reverse mode (html to plain text with separator), default=false</p><p>-h, — help : Print help</p><p>-V, — version : Print version</p><p>Concerning the separator character (‘,’ for CSV), make sure that this separator is not present in the cell text…</p><h4>Example:</h4><p>One sample file romaji.txt is provided</p><p>To test the program, try:</p><p>cargo run — -i romaji.txt -o romaji.html</p><p>(using the default ‘ ‘, single space, as separator; in this case two adjacent spaces in a row mean one empty cell)</p><p>Then try to convert the resulting file to CSV:</p><p>cargo run — -i romaji.html -o romaji.csv -s , -r</p><p>I used romaji.html, together with some CSS, in my <a href="https://eludev.fr/hkana/">hkana program</a></p><h3>2. Parsing command line arguments: the clap crate</h3><p>There are many clap tutorials out there, but the following should be enough to get you started. First, include the crate in your Cargo.toml:</p><pre>cargo add clap</pre><p>Then define a name for each argument: in my case there were 4 : input (of type String), output (also a String), separator (a char) and reverse (a bool, meaning if -r or — reverse is in the argument list, reverse will be true, otherwise it will be false).</p><p>To define them as arguments with clap is very easy:</p><pre>use clap::Parser;<br><br>/// Program to build an html table from a list of lines with optional separator<br>/// and conversely to convert html table to CSV (using comma or any separator character)<br>#[derive(Parser, Debug)]<br>#[command(version)]<br>struct Args {<br>    /// Path of input file, relative to current path<br>    #[arg(short, long)]<br>    input: String,<br><br>    /// Path of output file, relative to current path<br>    #[arg(short, long)]<br>    output: String,<br><br>    /// Character to be used as separator inside lines of input file<br>    #[arg(short, long, default_value_t = &#39; &#39;)]<br>    separator: char,<br><br>    /// Reverse mode (html to plain text with separator), default=false<br>    #[arg(short, long, default_value_t = false)]<br>    reverse: bool,<br>}<br><br>fn main() {<br>    let args = Args::parse();</pre><p>Within the Args struct, the ìnput item for instance is a rust variable of type String, and is also the name of the corresponding argument in the argument list.</p><p>The comments with 3 / are called ‘doc comments’: when you call yourProgram -h or yourProgram --help you will get exactly the text given in section 1 herabove. In addition to the 4 arguments (-i or --input, -o or --output, -s or --separator and -r or --reverse) clap will give you as a bonus 2 arguments (-V or --version, for which you must provide the #[command(version)] line, -h or --help).</p><p>-V will take its data from Cargo.toml, while -h will use the doc comments you provided.</p><p>In main() you get the actual argument values with Args::parse.</p><h3>3. Basic file reading and writing</h3><h4>3.1 Read from a text file:</h4><p>There is an open instruction, but for simple cases you don&#39;t need it, just use read_to_stringto read from a file with path (absolute or relative) filename :</p><pre>use std::fs::read_to_string;<br>let readresult: Vec&lt;String&gt; = read_to_string(filename)<br>        .expect(&quot;Failed to read input file&quot;) // print message, then panic<br>        .lines() // split the string into an iterator of string slices Lines&lt;&#39;_&gt;<br>        .map(String::from) // make each slice into a string<br>        .collect() // transform Lines&lt;&#39;_&gt; into a Vec&lt;String&gt;</pre><p>There is no close instruction: a file gets closed when it gets out of scope - or when a panic occurs.</p><p>To check if a file named some_file_name exists, do:</p><pre>use std::path::Path;<br><br>if !Path::new(&quot;some_file_name&quot;).exists() {<br>    println!(&quot;Error: file some_file_name does not exist&quot;);<br>    return;<br>}</pre><h4>3.2 Write to a text file:</h4><p>To write to a text file, first open it with create :</p><pre>use std::fs::File;<br><br>let mut ofil = File::create(outfile).expect(&quot;Cannot create output file&quot;);</pre><p>outfile is an &amp;str with the path (relative or absolute) of the file.</p><p>If the file does not exist, it will be created; otherwise it will be truncated.</p><p>For other cases, use OpenOptions <a href="https://doc.rust-lang.org/std/fs/struct.OpenOptions.html">https://doc.rust-lang.org/std/fs/struct.OpenOptions.html</a></p><p>To write a string ending with a line feed, do:</p><pre>writeln!(ofil, &quot;&lt;table class=&#39;rustgen&#39;&gt;&quot;).expect(&quot;Cannot write to file&quot;);</pre><p>To write several elements followed by a line feed, do:</p><pre>for cell in cells {<br>    write!(ofil, &quot;&lt;td&gt;{}&lt;/td&gt;&quot;, cell).expect(&quot;Cannot write cell to file&quot;);<br>}<br>writeln!(ofil, &quot;&quot;).expect(&quot;Cannot write to file&quot;); // add line feed (writeln)</pre><p>write! and writeln! are two macros, with the same syntax as the print! and println! macros.</p><p>Again, no need to explictly close the file.</p><h3>4. Working with String</h3><p>String is a big subject in rust, I shall just explain what I use in the program. Please refer to the full listing of the <a href="https://github.com/francisstephan/htmltable">program </a>starting with line 80.</p><h4>4.1. find() and get()</h4><p>Look at the following code (line 82):</p><pre>// 1. read infile as a String:<br>let mut content = read_to_string(infile).expect(&quot;Failed to read input file&quot;);<br><br>// 2. eliminate anything before &lt;table..<br>if let Some(i) = content.find(&quot;&lt;table&quot;) {<br>    content = content.get(i..).unwrap().to_string();</pre><p>content is a mutable String, which we read from the infile file. It is supposed to contain the whole html table which we want to parse.</p><p>The find(t:&amp;str) function returns the index of the first ocurrence of t within the string, or None if t is not present.</p><p>The get(i..) function returns a reference (&amp;str) to the part of String starting with i until the end, or None if i is out of range. Here I can safely use unwrap() since I know that i is within the range (0&lt;= i &lt; content.len())</p><p>Similarly, the following code shows the use of get(..i) :</p><pre>// 3. eliminate anything after &lt;/table&gt; (including the &lt;/table&gt; tag)<br>if let Some(i) = content.find(&quot;&lt;/table&gt;&quot;) {<br>    content = content.get(..i).unwrap().to_string();</pre><h4>4.2. replace()</h4><p>The signature of the replace function is:</p><pre>pub fn replace&lt;P&gt;(&amp;self, from: P, to: &amp;str) -&gt; String</pre><p>P is a Pattern, which is a Trait which is satisfied by several types, including &amp;str, as in our code (line 104–105 of htmltable):</p><pre>content = content.replace(&quot;\n&quot;, &quot;&quot;); // remove any line feed chars<br>content = content.replace(&quot;&lt;/tr&gt;&quot;, &quot;\n&quot;); // replace any &lt;tr&gt; with a line feed.</pre><h4>4.3. split() and lines()</h4><p>See the following code for split():</p><pre>let cells: Vec&lt;&amp;str&gt; = tableline.split(&quot;&lt;/td&gt;&quot;).collect();</pre><p>The split(&quot;&lt;/td/&gt;&quot;) followed by collect() returns a Vec of &amp;str, representing all the cells of one row of the table, over which we will iterate:</p><pre>for cell in cells {<br>    ...</pre><p>lines() is a specialized version of split which splits a String with the &#39;\n&#39; linefeed char:</p><pre>let tablelines = content.lines();</pre><p>Here, we do not use collect(): tablelines is of type Lines&lt;&#39;_&gt;, which implements the Iterator trait, so we shall directly use this iterator:</p><pre>for tableline in tablelines {<br>   ...<br>}</pre><h4>4.4. Regular expressions</h4><p>I use a regular expression to parse the &lt;td&gt; tag, for the case when the tag contains attributes such as &lt;td class=&quot;xx&quot;&gt;:</p><pre>use regex::Regex;<br><br>let re = Regex::new(r&quot;&lt;td[^&gt;]*&gt;(.*)$&quot;).unwrap(); // line 110</pre><p>Remember, we eliminated the &lt;/td&gt; at the end of the html cell. Now we need to eliminate the &lt;td ...&gt; part at the beginning of the cell.</p><p>The regex reads as follows:</p><ul><li>after reading the initial part &lt;td, read any character that is not a ‘&gt;’ : [^&gt;]*</li><li>until you reach a ‘&gt;’ character,</li><li>then read all chars until the end $, and put them in one group (.*). This group will contain the content of the html cell.</li></ul><p>We can use unwrap() safely here because we are sure of our regex syntax.</p><p>Then we use this group (.*) with the Regex captures() function. The capture at index 0 represents the total string. The cell content is the capture at index 1:</p><pre>if let Some(caps) = re.captures(cell) { // destructuring the captures<br>    if caps.len() == 2 {<br>        line.push_str(&amp;caps[1]); // push cell text to line</pre><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=3a88cb2479c0" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Rust with axum, tera and htmx]]></title>
            <link>https://medium.com/@francis.stephan/rust-with-axum-tera-and-htmx-2ad8a7e2b0e4?source=rss-52a738199362------2</link>
            <guid isPermaLink="false">https://medium.com/p/2ad8a7e2b0e4</guid>
            <category><![CDATA[rust-programming-language]]></category>
            <category><![CDATA[tera]]></category>
            <category><![CDATA[htmx]]></category>
            <category><![CDATA[axum]]></category>
            <dc:creator><![CDATA[Francis Stephan]]></dc:creator>
            <pubDate>Wed, 02 Jul 2025 19:50:18 GMT</pubDate>
            <atom:updated>2025-07-02T19:50:18.222Z</atom:updated>
            <content:encoded><![CDATA[<p>This is a continuation of my <a href="https://medium.com/@francis.stephan/developing-a-web-app-with-rust-first-steps-11e86dfbce7e">Rust web app</a> series, featuring transition from actix-web to axum, combining htmx and tera, and improved Dockerfile.</p><p>Non-members can read this text on <a href="https://github.com/francisstephan/chinese-writer-rust">github</a>. This is also the place where you can get the full source code, as well as a link to the app on <a href="https://rust-chinesewriter.fly.dev/">fly.io</a>.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/819/1*k7WW1GNutZTb87I5dkl8DQ.png" /></figure><h3>1. axum vs actix-web ?</h3><p><strong>axum</strong> and <strong>actix-web </strong>are among the current web frameworks available for rust development. I transitioned from actix-web to axum when trying to work on the Shuttle platform. I gave up on <strong>Shuttle</strong> (which did not fit my needs) but not on <strong>axum</strong>.</p><p>There are a lot of comparisons available about these frameworks (see for example <a href="https://infobytes.guru/articles/rust-web-framework-comparison.html](https://infobytes.guru/articles/rust-web-framework-comparison.html)">https://infobytes.guru/articles/rust-web-framework-comparison.html</a> ). However, from a developer’s point of view both are quite similar. To the advantage of axum, I note that you need to distinguish between GET and POST handlers only in one place in axum (when binding the handler with the routing system) instead of two in actix-web, where you also have to add a macro #[get(“/handler”)] or #[post(“/handler”)] in the handler definition, which may be a nuisance when refactoring your code.</p><p>Both play very well with the <strong>tera</strong> templating system, and with the <strong>sqlx</strong> SQL crate, meaning I had little to modify in the dbase module.</p><h3>2. Combining axum, htmx and tera</h3><h4>2.1 Tera templating: subtemplates</h4><p>I wrote about using the tera templating system <a href="https://medium.com/@francis.stephan/developing-a-web-app-with-rust-part-3-tera-templating-system-and-htmx-531e49e28ca2">here</a>.</p><p>One interesting point, for which I could no longer find adequate documention, is the concept of <strong>subtemplates</strong>. Here is my template tree:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/398/1*vHAqMmbpfONvcGM5nsGX9g.png" /><figcaption>Tree of tera templates</figcaption></figure><p>The index.html file is as follows:</p><pre>{% extends &quot;base.html&quot; %}<br>{% block content %}<br>&lt;div id=&quot;content&quot;&gt;<br>  Select a menu item hereabove to get started<br>  &lt;p&gt;{{ contenu }}&lt;/p&gt;<br>&lt;/div&gt;<br>{% endblock content %}</pre><p>I have two subtemplates: parsed.html and zilist.html, which are in the ‘components’ folder. For instance, here is the code for `zilist.html` :</p><pre>&lt;div id=&quot;content&quot;&gt;<br>  {% if dico | length == 0 %}<br>     No results for query &#39;{{query}}&#39;<br>  {% else %}<br>    Results for query &#39;{{query}}&#39;:<br>    &lt;table&gt;&lt;tr&gt;&lt;td&gt;Strokes&lt;/td&gt;&lt;td&gt;Pinyin&lt;/td&gt;&lt;td&gt;Unicode&lt;/td&gt;&lt;td&gt;Character&lt;/td&gt;&lt;td&gt;Translation&lt;/td&gt;&lt;/tr&gt;<br><br>    {% for zi in dico %}<br>    &lt;tr&gt;&lt;td&gt;{{zi.strokes}}&lt;/td&gt;&lt;td&gt;{{zi.pinyin_ton}}&lt;/td&gt;&lt;td&gt;{{zi.unicode}}&lt;/td&gt;&lt;td&gt;{{zi.hanzi}}&lt;/td&gt;&lt;td&gt;{{zi.sens}}&lt;/td&gt;&lt;/tr&gt;<br>    {% endfor %}<br>    &lt;/table&gt;<br>  {% endif %}<br>&lt;/div&gt;</pre><p>When I ask <strong>tera</strong> to render components/zilist.html, the <strong>&lt;div id=”content”&gt;</strong> div is substituted for the corresponding div in index.html:</p><pre>pub async fn pylist(<br>    State(client): State&lt;Arc&lt;AppState&gt;&gt;,<br>    Form(chardata): Form&lt;dbase::PinyinData&gt;, // caution:the extractor should follow the state<br>) -&gt; impl IntoResponse {<br>    let chain = &amp;chardata.pinyin_ton; // extract chardata from the form, using serde::deserialize<br>    let mut ctx = tera::Context::new(); // the tera context will receive required data for the template: query and dico<br>    ctx.insert(&quot;query&quot;, &amp;chain);<br>    let disp = dbase::list_for_py(client, String::from(chain)).await; // query database<br>    ctx.insert(&quot;dico&quot;, &amp;disp);<br>    let output = TERA.render(&quot;components/zilist.html&quot;, &amp;ctx); // tera rendering<br>    Html(output.unwrap()) // page update as specified by htmx event<br>}</pre><p>The <strong>{{query}}</strong> field in the template is dealt with in <strong>ctx.insert(“query”, &amp;chain) </strong>and the <strong>dico</strong> field in <strong>ctx.insert(“dico”, &amp;disp)</strong> .</p><h4>2.2 tera rendering vs direct rendering</h4><p>The rendering mode we just saw I call “tera rendering”:</p><pre>let output = TERA.render(&quot;components/zilist.html&quot;, &amp;ctx);<br>Html(output.unwrap())</pre><p>Now there are other contents that do not need tera rendering. Take for instance in the program’s menu the `size` tab, which triggers an htmx call as follows :</p><pre>&lt;li hx-trigger=&quot;click&quot; hx-get=&quot;/size&quot; hx-target=&quot;#content&quot; hx-swap=&quot;innerHTML&quot;&gt;</pre><p>This reads that a click on the element triggers an htmx event, calling the /size route; the div with id = `content` will be overwritten by the anwser, will fill the div’s innerHTML. The /size handler reads as follows:</p><pre>pub async fn size(State(client): State&lt;Arc&lt;AppState&gt;&gt;) -&gt; impl IntoResponse {<br>    let size = dbase::getsize(client).await;  // query database to get size<br>    let metadata = fs::metadata(&quot;vol/zidian.db&quot;).expect(&quot;Failed to read file metadata&quot;);<br>    let time = metadata.modified().unwrap();<br>    use chrono::prelude::{DateTime, Utc};<br>    let dt: DateTime&lt;Utc&gt; = time.clone().into(); // sqlite.db&#39;s last update<br>    let content = format!(<br>        &quot;The dictionary presently contains {} entries. Last updated on {}&quot;,<br>        &amp;size, &amp;dt.format(&quot;%Y-%m-%d&quot;) );<br>    content.into_response() // directly render in the div with id = content<br>}</pre><p>The rendering of the `content` String is performed in the last line: `content.into_response()` : tera is not involved here, only htmx which provides for an ajax call, the div with id = `content` gets updated with a text such as “The dictionary presently contains 2634 entries. Last updated on 2025–06–30”. No page reload occurs. This I call direct rendering.</p><p>To sum up:</p><ul><li>tera has powerful rendering options (such as appear in the `zilist.html` file here above). Whenever you need these options, write adequate subtemplates and use tera rendering;</li><li>otherwise, if answering to an htmx request, just render the string directly using what I called direct rendering.</li></ul><h4>2.3 Programmatically trigger htmx form:</h4><p>I have the following htmx form:</p><pre>&lt;form id=&quot;postzi&quot; hx-post=&quot;/candidatelist&quot; hx-target=&quot;#zilist&quot; hx-swap=&quot;innerHTML&quot;&gt;<br>    &lt;label for=&quot;pinyin&quot;&gt;Enter pinyin+tone (press / or space after pinyin if tone unknown) :&lt;/label&gt;<br>    &lt;input type=&#39;text&#39; id=&#39;pinyin&#39; name=&#39;pinyin_ton&#39; size=&#39;10&#39; autofocus oninput=&#39;convertToZi()&#39;&gt;<br>&lt;/form&gt;</pre><p>I do not mention hx-trigger, since the dafault trigger for htmx forms is ‘submit’. But I do not want a submit button: the text input is listened to by the javascript `convertToZi()` function (in vol/assets/chwriter.js), which has its own criteria to decide when the form is submitted. So I tried several ways to trigger the `submit` event; the only one that worked looks like a hack, but it works:</p><p>. I include an invisible button in the form, as follows:</p><pre>&lt;form id=&quot;postzi&quot; hx-post=&quot;/candidatelist&quot; hx-target=&quot;#zilist&quot; hx-swap=&quot;innerHTML&quot;&gt;<br>    &lt;label for=&quot;pinyin&quot;&gt;Enter pinyin+tone (press / or space after pinyin if tone unknown) :&lt;/label&gt;<br>    &lt;input type=&#39;text&#39; id=&#39;pinyin&#39; name=&#39;pinyin_ton&#39; size=&#39;10&#39; autofocus oninput=&#39;convertToZi()&#39;&gt;<br>    &lt;button id=&quot;subpy&quot; style=&quot;display:none&quot; type=&quot;submit&quot;&gt;&lt;/button&gt;<br>&lt;/form&gt;</pre><p>. I trigger the form with the following line (from `convertToZi`):</p><pre>const button = document.getElementById(&quot;subpy&quot;);<br>button.click();</pre><h3>3. Better Dockerfile</h3><p>Many thanks to <a href="https://blog.semicolonsoftware.de/building-minimal-docker-containers-for-rust-applications/">Stefan Seemayer</a> for his indications on a better Dockerfile for rust.</p><p>With this Dockerfile my deploy time was reduced from minutes to seconds, which is a life changer. Here is the version I derived from it:</p><pre>FROM rust AS build-stage<br>WORKDIR /app<br>COPY Cargo.toml Cargo.lock ./<br>RUN mkdir src &amp;&amp; \<br>    echo &quot;fn main() {println!(\&quot;Preparing dependency cache...\&quot;)}&quot; &gt; src/main.rs &amp;&amp; \<br>    cargo build --locked --release<br>RUN rm -rf src/<br>COPY ./src ./src<br>RUN cargo build --locked --release<br><br>FROM gcr.io/distroless/cc<br>WORKDIR /<br>COPY --from=build-stage /app/target/release/chinesewriter /chinesewriter<br>COPY ./vol ./vol<br>EXPOSE 3001<br>ENTRYPOINT [&quot;/chinesewriter&quot;]</pre><p>The idea is to first copy the Cargo.toml and Cargo.lock files into the WORKDIR, and then to compile a dummy src/main.rs, so that all the dependencies in Cargo.toml get compiled and cached, available for later Docker builds. However, I did not follow Stefan’s recommendation to use the `scratch` distro for the build stage, since this implies using x86_64-unknown-linux-musl. The one I use, `gcr.io/distroless/cc`, is compatible with standard rust libraries and the resulting image is only 11 MB large after compression, which is quite acceptable.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=2ad8a7e2b0e4" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[SQLITE in the cloud with TURSO]]></title>
            <link>https://medium.com/@francis.stephan/sqlite-in-the-cloud-with-turso-b33bbf9fd5e7?source=rss-52a738199362------2</link>
            <guid isPermaLink="false">https://medium.com/p/b33bbf9fd5e7</guid>
            <category><![CDATA[libsql]]></category>
            <category><![CDATA[cloud-services]]></category>
            <category><![CDATA[turso]]></category>
            <category><![CDATA[rust]]></category>
            <dc:creator><![CDATA[Francis Stephan]]></dc:creator>
            <pubDate>Tue, 27 Aug 2024 16:17:54 GMT</pubDate>
            <atom:updated>2024-08-27T18:24:44.240Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*4dKQSbFmOKgrO5KvXsrk7w.jpeg" /><figcaption>Source of the Orontes river</figcaption></figure><p>This is a short tutorial on using Turso with Rust. <a href="https://docs.turso.tech/introduction"><strong>Turso</strong></a> is a database-as-a-service company offering to host <strong>libsql</strong>-based databases, and libsql is an open source fork of SQLite.</p><p>While this tutorial is based on Rust, Turso is also available for Javascript, Golang, Python, PHP or any language with HTTP request capacity.</p><p>The tutorial assumes you know some Rust (including pattern matching) and have Rust installed on your computer.</p><h3>1. Prepare the database</h3><p>Our database will include only one table: usersfor which we prepare the following SQL script, tuto.sql :</p><pre>DROP TABLE IF EXISTS users;<br>CREATE TABLE users ( &quot;id&quot; INTEGER PRIMARY KEY, <br>    &quot;name&quot; varchar(11) NOT NULL, &quot;email&quot; varchar(30) NOT NULL );<br>INSERT INTO users VALUES(1,&#39;John Doe&#39;, &#39;john.doe@somewhere.com&#39;);<br>INSERT INTO users VALUES(2,&#39;Mike Jones&#39;, &#39;mike.jones@elsewhere.com&#39;);</pre><h3>2. Create the database onTurso</h3><ul><li>Follow the <a href="https://docs.turso.tech/quickstart">Turso quickstart </a>to <strong><em>install the Turso CLI</em></strong><em> </em>and<em> </em><strong><em>sign up to Turso</em></strong>. Turso offers a ‘Starter’ plan which — at the time of writing this article — is free for individual developers, including up to 500 Databases, 9GB of total storage, 1 billion row reads, unlimited embedded replicas. From now on we assume that you have the Turso CLI installed and did sign up.</li><li>Create the my-tuto database on Turso:</li></ul><pre>$ turso db create my-tuto</pre><ul><li>Execute the tuto.sql script on the new database:</li></ul><pre>  $ turso db shell my-tuto &lt; tuto.sql</pre><ul><li>Check that your table has been created:</li></ul><pre>$ turso db shell my-tuto<br>Connected to my-tuto at libsql://my-tuto-&lt;your-turso-account&gt;.turso.io<br><br>Welcome to Turso SQL shell!<br><br>Type &quot;.quit&quot; to exit the shell and &quot;.help&quot; to list all available commands.<br><br>→  SELECT * FROM users;<br>ID     NAME           EMAIL                    <br>1      John Doe       john.doe@somewhere.com       <br>2      Mike Jones     mike.jones@elsewhere.com     <br>→  .quit</pre><ul><li>Get the database url and save a copy of it:</li></ul><pre>$ turso db show --url my-tuto</pre><ul><li>Get the database authentication token and save a copy of it:</li></ul><pre>$ turso db tokens create my-tuto</pre><h3>3. Prepare a rust program to read the database</h3><ul><li>Create a new rust project</li></ul><pre>$ cargo new tursotutorial<br>$ cd tursotutorial</pre><ul><li>Create a .env file with the two database properties you just saved (end of section 2 here above):</li></ul><pre>TURSO_DATABASE_URL=<br>TURSO_AUTH_TOKEN=</pre><ul><li>Add the necessary dependencies: libsql to access the database, dotenv to read the .env file, serde to deserialize the content of each database row, and tokio to provide the asynchronous runtime</li></ul><pre>$ cargo add libsql<br>$ cargo add dotenv<br>$ cargo add serde<br>$ cargo add tokio</pre><ul><li>and edit src/main.rs:</li></ul><pre>use dotenv::dotenv;<br>use libsql::{de, params, Builder};<br>use serde::Deserialize;<br>use std::env;<br><br>#[derive(Debug, Deserialize)]<br>pub struct User {<br>    id : i64,<br>    name : String,<br>    email : String,<br>}<br><br>#[tokio::main]<br>async fn main() {<br>    dotenv().ok();<br>    let url = env::var(&quot;TURSO_DATABASE_URL&quot;).expect(&quot;LIBSQL_URL must be set&quot;);<br>    let token = env::var(&quot;TURSO_AUTH_TOKEN&quot;).unwrap_or_default();<br><br>    let db = Builder::new_remote(url, token).build().await.unwrap();<br>    let conn = db.connect().unwrap();<br><br>    let mut rows = conn.query(&quot;SELECT * FROM users;&quot;, params![]).await.unwrap();<br><br>    loop {<br>        let row = rows.next().await.unwrap();<br>        match row {<br>            None =&gt; break,<br>            Some(row) =&gt; match de::from_row::&lt;User&gt;(&amp;row) {<br>                Ok(user) =&gt; {<br>                    println!(&quot;{:?}&quot;, user);<br>                }<br>                Err(_) =&gt; {}<br>            }<br>        }<br>    }<br>}</pre><p>The main aspects of this code are:</p><ul><li>The User struct, which implements Deserialize (see below) and Debug (for printing). The identifiers of this struct are the same as the columns of the users table, and their type matches the corresponding types in the table.</li><li>The dotenv line and following, where the database url and auth token are input (from the .env file)</li><li>The conn variable holds the database connection</li><li>The rows variable (of type <a href="https://docs.rs/libsql/latest/libsql/struct.Rows.html">Rows</a>) contains the rows after executing the query</li><li>We access the elements in each row through an open loop</li><li>The <a href="https://docs.rs/libsql/latest/libsql/struct.Rows.html">next</a> function has the following signature:</li></ul><pre>pub async fn next(&amp;mut self) -&gt; Result&lt;Option&lt;Row&gt;&gt;</pre><ul><li>After we unwrap the Result with unwrap(), we get an Option, which can be eithe Ok(row:Row) or None.</li><li>Through pattern matching, we destructure the row with Ok(row)</li><li>We then do a second pattern matching, based on the from_row function, which has the following signature (see <a href="https://docs.rs/libsql/latest/libsql/de/fn.from_row.html">here</a>) :</li></ul><pre>pub fn from_row&lt;&#39;de, T: Deserialize&lt;&#39;de&gt;&gt;(row: &amp;&#39;de Row) -&gt; Result&lt;T, Error&gt;</pre><ul><li>This deserves to be considered more closely: we do not need the ‘de lifetime annotation here, so we just forget it. The T type is the struct to which we want the data to be deserialized, which a struct of type User. It must implement Deserialize, this is why we specified Derive(Deserialize) for the User struct. This translates as follows in our code:</li></ul><pre>Some(row) =&gt; match de::from_row::&lt;User&gt;(&amp;row)</pre><ul><li>The result of de::from_row is of type Result(User, Error) in our case, with two branches in the match: the Ok branch, where we get a user (of type User) by destructuring the result Ok(user), and the Error branch, which we chose not to use.</li></ul><h3>4. Running the program</h3><p>We may run the program with cargo run, and it works:</p><pre>$ cargo run<br>   Compiling tursotutorial v0.1.0 (/Users/francisstephan/dev/rust/tursotutorial)<br>warning: fields `id`, `name`, and `email` are never read<br>  --&gt; src/main.rs:10:5<br>   |<br>9  | pub struct User {<br>   |            ---- fields in this struct<br>10 |     id: i64,<br>   |     ^^<br>11 |     name: String,<br>   |     ^^^^<br>12 |     email: String,<br>   |     ^^^^^<br>   |<br>   = note: `User` has a derived impl for the trait `Debug`, but this is intentionally ignored during dead code analysis<br>   = note: `#[warn(dead_code)]` on by default<br><br>warning: `tursotutorial` (bin &quot;tursotutorial&quot;) generated 1 warning<br>    Finished `dev` profile [unoptimized + debuginfo] target(s) in 2.97s<br>     Running `target/debug/tursotutorial`<br>User { id: 1, name: &quot;John Doe&quot;, email: &quot;john.doe@somewhere.com&quot; }<br>User { id: 2, name: &quot;Mike Jones&quot;, email: &quot;mike.jones@elsewhere.com&quot; }</pre><p>The warning is a minor nuisance here; we get it because we did not use the elements of the User struct. However, we need to provide these elements for the Deserialization to work. You may consider this as a (minor) compiler bug.</p><p>This is a local program using a cloud database. In a further article we shall discuss the case of a web based program using Turso. See a preliminary version of the program <a href="https://github.com/francisstephan/ChineseWriter_Shuttle_Turso">here</a>.</p><h3>5. Conclusion</h3><p>Our experience with the Turso platform was excellent from the start.</p><p>The libsql documentation is quite ok but a bit terse, as shown in the two examples given above (l<a href="https://docs.rs/libsql/latest/libsql/struct.Rows.html">ibsql::rows</a> and <a href="https://docs.rs/libsql/latest/libsql/de/fn.from_row.html">libsql::de::from_row</a>). Some examples would be useful for beginners.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=b33bbf9fd5e7" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Developing a web app with rust, part 4: SQLx, data validation, deployment, final remarks]]></title>
            <link>https://medium.com/@francis.stephan/developing-a-web-app-with-rust-part-4-sqlx-data-validation-deployment-final-remarks-303e78c2a546?source=rss-52a738199362------2</link>
            <guid isPermaLink="false">https://medium.com/p/303e78c2a546</guid>
            <category><![CDATA[rust]]></category>
            <category><![CDATA[docker]]></category>
            <category><![CDATA[deployment]]></category>
            <category><![CDATA[sqlx]]></category>
            <category><![CDATA[html5]]></category>
            <dc:creator><![CDATA[Francis Stephan]]></dc:creator>
            <pubDate>Mon, 10 Jun 2024 22:19:52 GMT</pubDate>
            <atom:updated>2024-06-10T22:19:52.564Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/596/1*nJ65v3fOnl-sbDvKh05oZQ.png" /></figure><h3>1. SQLx</h3><p>SQLx is “an async, pure Rust SQL crate featuring compile-time checked queries without a DSL.” SQLx is fully compatible with actix_web.</p><p>SQLx supports PostgreSQL, MySQL, MariaDB and SQLite. In my <a href="https://github.com/francisstephan/rust_character_dictionary">Rust character dictionary</a>, I use SQLite.</p><p>SQLx accepts queries written in SQL using each DB system’s indiosyncrasies — in my case SQLite’s SQL syntax.</p><p>For each query you may choose between unprepared queries and precompiled queries:</p><ul><li>the macros sqlx::query!() and sqlx::query_as!() perform compile-time validation of SQL,</li><li>while the functions sqlx::query() and sql::query_as() provide no SQL pre-compilation.</li></ul><p>I chose no to perform compile-time validation.</p><p>The <a href="https://github.com/launchbadge/sqlx">documentation</a> is good and I did not need any other resource.</p><p>Here are two examples from <a href="https://github.com/francisstephan/rust_character_dictionary/blob/main/src/dbase.rs">dbase.rs</a>:</p><pre>pub async fn getsize(data: Data&lt;AppState&gt;) -&gt; i64 {<br>    let result: (i64,) = sqlx::query_as(&quot;SELECT COUNT(*) FROM pyhz&quot;)<br>        .fetch_one(&amp;data.db)<br>        .await<br>        .unwrap();<br><br>    result.0<br>}</pre><p>The getsize function returns the size (row count) of the `pyhz` table. The SQL query “SELECT COUNT(*) FROM pyhz” is standard sql. It is not validated at compilation time since I use the function query_as() and not the macro query_as!().</p><p>Here is another example, which does not need any comment:</p><pre>pub async fn delete_db(id: i64, data: Data&lt;AppState&gt;) -&gt; String {<br>    let query = format!(&quot;DELETE FROM pyhz WHERE id= {} &quot;, id);<br><br>    let result = sqlx::query(&amp;query).execute(&amp;data.db).await;<br>    match result {<br>        Ok(_) =&gt; return format!(&quot;Successful deleted entry Id = {}&quot;, id),<br>        Err(_) =&gt; return String::from(&quot;Internal server error&quot;),<br>    }<br>}</pre><p>As a conclusion, SQLx is easy to use, implements SQL queries with no incidental complexity, and plays well with actix_web (and most other web frameworks, but I did not check on that).</p><h3>2. Data validation</h3><p>Data validation for any data introduced in the program is important :</p><ul><li>for security: avoiding XSS attacks,</li><li>and for data quality control: limiting the risk of introducing garbage into the database.</li></ul><p>In the <a href="https://github.com/francisstephan/rust_character_dictionary">Rust character dictionary</a>, I have essentially two types of data:</p><ul><li>data with a specific format, such as single chinese characters, their phonetic transcription (pinyin and tone), their unicode value; for these I use HTML5 validation;</li><li>data with no specific format, such as the range of meanings of each character; for these I use <a href="https://docs.rs/ammonia/latest/ammonia/">ammonia</a> sanitization.</li></ul><h4>HTML5 data validation:</h4><p>I use validation by string length, validation by data type and validation according to regex pattern. The following examples are from <a href="https://github.com/francisstephan/rust_character_dictionary/blob/main/src/forms.rs">forms.rs</a>:</p><p>Validation by length:</p><pre>&lt;input id=&quot;carac&quot; name=&quot;carac&quot; type=&quot;text&quot; required minlength=&quot;1&quot; maxlength=&quot;1&quot;&gt;</pre><p>In this example the string to be input must be exactly one character length.</p><p>Validation by data type:</p><pre>&lt;input id=&quot;id&quot; name=&quot;id&quot; required type=&quot;number&quot; autofocus&gt;</pre><p>In this example, you can input only a number (in decimal representation)</p><p>Validation by pattern:</p><pre>&lt;label for=&quot;unicode&quot;&gt;Unicode (hexa, using pattern ^[0-9,A-F]{4}):&lt;/label&gt;<br>&lt;input id=&quot;unicode&quot; name=&quot;unicode&quot; type=&quot;text&quot; required pattern=&quot;^[0-9,A-F]{4}&quot;&gt;</pre><p>The pattern “^[0–9,A-F]{4}” means that the input string must contain exactly 4 characters, either numerical or in the range A-F. If you enter incorrect data this is what you get after clicking ‘submit’:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/631/1*7jWoB9CSQgbGJ-CQtXv9oQ.png" /></figure><p>Try it using the ‘Add zi’ button in <a href="https://ruzdman.fly.dev/">https://ruzdman.fly.dev/</a> (no need to fear to damage the database, since it will automatically be reloaded when you leave the program for more than a few minutes).</p><h4>ammonia sanitization:</h4><p><a href="https://docs.rs/ammonia/latest/ammonia/">ammonia</a> is “a whitelist-based HTML sanitization library. It is designed to prevent cross-site scripting, layout breaking, and clickjacking caused by untrusted user-provided HTML being mixed into a larger web page”. I apply ammonia not in the forms themselves but when commiting the data to the database, as in the following (from <a href="https://github.com/francisstephan/rust_character_dictionary/blob/main/src/dbase.rs">dbase.rs</a>):</p><pre>let query = format!(<br>    &quot;INSERT INTO pyhz (pinyin_ton, unicode, sens) VALUES (&#39;{}&#39;, &#39;{}&#39;, &#39;{}&#39;)&quot;,<br>    zi.pinyin_ton,<br>    zi.unicode,<br>    ammonia::clean(&amp;zi.sens) // sanitize zi.sens, which has no specific format<br>);</pre><h3>3. Deployment</h3><p>I chose to deploy to <a href="https://fly.io/">fly.io</a>, which has a hobby plan that used to be free and is now billed at 5 $/month, which is still quite affordable. The deployment is based on a docker container. I prepared the following dockerfile, derived from the one I used for the <a href="https://github.com/francisstephan/character_dictionary_manager/blob/main/Dockerfile">golang version</a>, after reading <a href="https://kerkour.com/rust-small-docker-image">S.Kerkour’s post</a>:</p><pre># syntax=docker/dockerfile:1<br><br>##<br>## Build the application from source<br>##<br><br>FROM rust AS build-stage<br>WORKDIR /app<br>COPY . .<br>RUN cargo build --release<br><br>##<br>## Deploy the application binary into a lean image<br>##<br><br>FROM gcr.io/distroless/cc<br>ENV DATABASE_URL=sqlite://vol/zidian.db<br>ENV RUST_LOG=ruzdman=inf<br>WORKDIR /<br>COPY --from=build-stage /app/target/release/ruzdman /ruzdman<br>COPY ./vol ./vol<br>EXPOSE 8090<br>ENTRYPOINT [&quot;/ruzdman&quot;]</pre><p>Using this dockerfile, the size of the docker image I get on fly.io is 38 MB, more than for the image I get for the <a href="https://github.com/francisstephan/character_dictionary_manager">Golang version</a>, which is only 16MB. I understand I can further reduce the size by using the musl library.</p><p>The /vol directory contains all the files I need for execution: the templates, various assets, and the database. The database is reloaded from the docker image each time the program is launched, which is the reason why database changes are only effective during one fly.io session.</p><h3>4. Final remarks</h3><p>If I try to sum up my experience from starting a web app with <strong>golang</strong> and then porting it to <strong>rust</strong>, I find that:</p><ul><li>the <strong>golang</strong> version was really easy to develop (which was also thanks to the fact that I had built my own extensive tutorial for it in <a href="https://github.com/francisstephan/gin-html-tutorial">https://github.com/francisstephan/gin-html-tutorial</a>);</li><li>porting it to <strong>rust</strong> was initially quite demanding; but finally it obliged me to write a better program; for instance, since <strong>rust</strong> is much less tolerant than <strong>golang</strong>about string management, I had to make a much better use of the templating system than I did for the <strong>golang</strong> version, where I had used it only minimally; the same goes for logging.</li></ul><p>All I want to say in conclusion is: thank you to the brilliant developers in the <strong>golang</strong> and <strong>rust</strong> communities who make those great tools available!</p><p>For those who might wish to read the former instalments, here they are:</p><ul><li><a href="https://medium.com/@francis.stephan/developing-a-web-app-with-rust-first-steps-11e86dfbce7e">Developing a web app with rust: first steps</a></li><li><a href="https://medium.com/@francis.stephan/developing-a-web-app-with-rust-part2-actix-web-95cec37af52a">Developing a web app with rust: part2, Actix Web</a></li><li><a href="https://medium.com/@francis.stephan/developing-a-web-app-with-rust-part-3-tera-templating-system-and-htmx-531e49e28ca2">Developing a web app with rust: part 3, tera templating system and htmx</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=303e78c2a546" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Developing a web app with rust: part 3, tera templating system and htmx]]></title>
            <link>https://medium.com/@francis.stephan/developing-a-web-app-with-rust-part-3-tera-templating-system-and-htmx-531e49e28ca2?source=rss-52a738199362------2</link>
            <guid isPermaLink="false">https://medium.com/p/531e49e28ca2</guid>
            <category><![CDATA[htmx]]></category>
            <category><![CDATA[tera]]></category>
            <category><![CDATA[rust]]></category>
            <dc:creator><![CDATA[Francis Stephan]]></dc:creator>
            <pubDate>Fri, 07 Jun 2024 10:17:49 GMT</pubDate>
            <atom:updated>2024-06-10T22:31:41.735Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/530/1*DkUwY_f9FkINHhTfw6r_vw.png" /></figure><h3>1. Presentation</h3><p>Tera is “a powerful, fast and easy-to-use template engine for Rust”. The <a href="https://keats.github.io/tera/docs/">documentation</a> is OK but assumes you are already familiar with templating. I was not (my experience dates back to Drupal 6 …) so I found the <a href="https://docs.djangoproject.com/en/1.10/ref/templates/language/">Django documentation</a> very useful as a starting point.</p><p>In my <a href="https://github.com/francisstephan/rust_character_dictionary">Rust character dictionary</a>, I use <a href="https://htmx.org/"><strong>htmx</strong></a>in conjunction with <strong>tera</strong>, in the same way as I explained in a <a href="https://medium.com/@francis.stephan/htmx-for-go-gin-web-development-ba206b6e2e7b">previous story</a>. This allows me to only render a part of the html document, implicitly using Ajax (no need to know about Ajax, though). More precisely, for each form or result displayed in my browser page, I only render the content of the HTML div with id = “content”.<strong>tera</strong> and<strong>htmx</strong> play well together to achieve that, as we shall see in the next section.</p><p>The template files are organized as follows:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/224/1*6a8oLoQYS0R9dEFavjWMsA.png" /></figure><p>In this tree, <em>index.html</em> is the main html page, inheriting from <em>base.html , </em>while the four html files in the components subdirectory provide various templates to include within the “content” div.</p><p>This rendering is performed by the various handlers, through the tera.render function, where all data to be rendered are defined in the tera <a href="https://docs.rs/tera/latest/tera/struct.Context.html">Context</a> struct.</p><h3>2. index.html: main html page</h3><p>The index.htm page is very short:</p><pre>{% extends &quot;base.html&quot; %} <br>{% block content %}<br><br>&lt;div id=&quot;content&quot;&gt;<br>    Select a menu item hereabove to get started<br>    &lt;p&gt;{{ contenu }}&lt;/p&gt;<br>&lt;/div&gt;<br><br>{% endblock content %}</pre><p>This means:</p><ul><li>replace the text between {% block content %} and {% endblock content %} in the base.html file;</li><li>define a variable with name ‘contenu’, whose value will be assigned to the Tera Context struct</li></ul><p>The rendering will be performed within the handler corresponding to the “/” route:</p><pre>#[get(&quot;/&quot;)]<br>pub async fn index(req: HttpRequest, tera: Data&lt;Tera&gt;) -&gt; impl Responder {<br>    let ipaddr = actix_remote_ip::get_remote_ip(&amp;req);<br>    let mut ctx = Context::new();<br>    if ipaddr.is_loopback() {<br>        ctx.insert(&quot;contenu&quot;, &quot;Connected to local server&quot;);<br>    } else {<br>        ctx.insert(&quot;contenu&quot;, &quot;Caution: all modifications to the database will be discarded at the end of the fly.io session&quot;);<br>    }<br>    HttpResponse::Ok().body(tera.render(&quot;index.html&quot;, &amp;ctx).unwrap())<br>}</pre><p>If you read through the <a href="https://github.com/francisstephan/rust_character_dictionary/blob/main/src/handlers.rs">handlers.rs</a> file, you will see that t<em>his is the only place where we render index.html</em>. All other handlers render component files surch as components/content.html, components/zilist.html, components/updateform.html, components/deleteform.html, which all define the content of the “content” div. We will describe these in the following section.</p><h4>About base.html:</h4><p>The <a href="https://github.com/francisstephan/rust_character_dictionary/blob/main/vol/templates/base.html">base.html</a> file includes the main menu, consisting of an unordered list:</p><pre>&lt;ul id=&quot;menu&quot;&gt;<br>  &lt;li class=&quot;menuitem&quot; hx-trigger=&quot;click&quot; hx-get=&quot;/size&quot; <br>      hx-target=&quot;#content&quot; hx-swap=&quot;innerHTML&quot;&gt;<br>    Size<br>  &lt;/li&gt;<br>  &lt;li class=&quot;menuitem&quot; hx-trigger=&quot;click&quot; hx-get=&quot;/getziform&quot; <br>      hx-target=&quot;#content&quot; hx-swap=&quot;innerHTML&quot;&gt;<br>    Zi =&gt; Pinyin<br>  &lt;/li&gt;<br>  &lt;li class=&quot;menuitem&quot; hx-trigger=&quot;click&quot; hx-get=&quot;/getpyform&quot; <br>      hx-target=&quot;#content&quot; hx-swap=&quot;innerHTML&quot;&gt;<br>    Pinyin =&gt; Zi<br>  &lt;/li&gt;<br>  &lt;li class=&quot;menuitem&quot; hx-trigger=&quot;click&quot; hx-get=&quot;/getaddziform&quot; <br>      hx-target=&quot;#content&quot; hx-swap=&quot;innerHTML&quot;&gt;<br>    Add zi<br>  &lt;/li&gt;<br>  &lt;li class=&quot;menuitem&quot; hx-trigger=&quot;click&quot; hx-get=&quot;/getselupdate&quot; <br>      hx-target=&quot;#content&quot; hx-swap=&quot;innerHTML&quot;&gt;<br>    Update zi<br>  &lt;/li&gt;<br>  ...<br>&lt;/ul&gt;</pre><p>See the resulting menu <a href="https://ruzdman.fly.dev/">here</a>.</p><p>Through the use of htmx, and with adequate CSS, clicking a list element will generate an AJAX request to be sent. For the first element:</p><pre>&lt;li class=&quot;menuitem&quot; hx-trigger=&quot;click&quot; hx-get=&quot;/size&quot; <br>      hx-target=&quot;#content&quot; hx-swap=&quot;innerHTML&quot;&gt;<br>    Size<br>&lt;/li&gt;</pre><p>a GET request will be generated, with the /size route; the hx-target specifies where the response should go: hx-target=”#content&quot; means that the response will be included in the div with id “content”, and hx-swap=”innerHTML” means that the content swap will be performed on the div’s innerHTML. This GET request will be handled by the `size` handler (from handlers.rs, slightly edited version):</p><pre>#[get(&quot;/size&quot;)]<br>pub async fn size(tera: Data&lt;Tera&gt;, data: web::Data&lt;AppState&gt;) -&gt; impl Responder {<br>    // https://stackoverflow.com/questions/669092/sqlite-getting-number-of-rows-in-a-database<br>    let mut ctx = Context::new();<br>    let size = dbase::getsize(data).await;<br>    ctx.insert(<br>        &quot;content&quot;,<br>        format!(<br>            &quot;The dictionary presently contains {} entries. Last updated on {}&quot;,<br>            &amp;size)<br>        )<br>        .as_str(),<br>    );<br>    HttpResponse::Ok().body(tera.render(&quot;components/content.html&quot;, &amp;ctx).unwrap())<br>}</pre><p>and the result will be rendered to components/content.html (specified by <strong>tera</strong>) within the div with id “content” (specified by <strong>htmx</strong>). The template components/content.html is a very short file indeed:</p><pre>&lt;div id=&quot;content&quot;&gt;{{content | safe}}&lt;/div&gt; &lt;!-- safe prevents HTML escaping --&gt;</pre><p>We need the ‘safe’ filter to be able to render html forms in the {{content}} variable.</p><h3>3. Specific template components</h3><p>Beside components/content.html, which we use when there is just one data string to be rendered, we also mentioned three other templates:</p><ul><li>components/zilist.html, which displays table presentation of database consultation (SELECT) results</li><li>components/updateform.html, which displays the update form</li><li>components/deleteform.html, which displays data and asks for confirmation.</li></ul><p>We shall just describe one of them, together with the handlers that use it.</p><p>Here is a listing of components/zilist.html:</p><pre>&lt;div id=&quot;content&quot;&gt;<br>{% if dico | length == 0 %}<br>No results for query &#39;{{query}}&#39;<br><br>{% else %}<br>Results for query &#39;{{query}}&#39;:<br><br>  &lt;table&gt;<br>  &lt;tr&gt;&lt;td&gt;Id&lt;/td&gt;&lt;td&gt; Pinyin &lt;/td&gt;&lt;td&gt;Unicode&lt;/td&gt;&lt;td&gt; Character &lt;/td&gt;&lt;td&gt;Translation&lt;/td&gt;&lt;/tr&gt;<br><br>  {% for zi in dico %}<br>  &lt;tr&gt;&lt;td&gt;{{zi.id}}&lt;/td&gt;&lt;td&gt;{{zi.pinyin_ton}}&lt;/td&gt;&lt;td&gt;{{zi.unicode}}&lt;/td&gt;&lt;td&gt;{{zi.hanzi}}&lt;/td&gt;&lt;td&gt;{{zi.sens}}&lt;/td&gt;&lt;/tr&gt;<br>  {% endfor %}<br> <br>  &lt;/table&gt;<br><br>{% endif %}<br>&lt;/div&gt;</pre><p>This template (which is enclosed within a div with id= “content”) receives two data from tera:</p><ul><li>one array of dictionary elements retrieved from the database, named “dico” (which was actually a vector in the rust program)</li><li>one string summing up the query, named “query”.</li></ul><p>On ligne 2 we apply the `<a href="https://keats.github.io/tera/docs/#length">length</a>` filter to the dico array to get its length.</p><p>Further down, we have a `for` loop : {% for zi in dico %}. In the next line, you see that we access the various elements in the dico array : zi.id, zi.pinyin_ton, zi.unicode, … These names correspond to the following rust struct (in dbase.rs) :</p><pre>#[derive(Serialize)]<br>pub struct Zi {<br>    pub id: i64,<br>    pub pinyin_ton: String,<br>    pub unicode: String,<br>    pub hanzi: char,<br>    pub sens: String,<br>}</pre><p>Actually dico is an array of Zi struct elements, serialized by tera.</p><p>Several handlers (in <a href="https://github.com/francisstephan/rust_character_dictionary/blob/main/src/handlers.rs">handlers.rs</a>) use the components/zilist.html template. Let us just quote one:</p><pre>#[get(&quot;/showlast&quot;)]<br>pub async fn showlast(tera: Data&lt;Tera&gt;, data: web::Data&lt;AppState&gt;) -&gt; impl Responder {<br>    let mut ctx = Context::new();<br>    ctx.insert(&quot;query&quot;, &quot;last entry&quot;);<br>    let disp = dbase::list_last(data).await;<br><br>    ctx.insert(&quot;dico&quot;, &amp;disp);<br>    HttpResponse::Ok().body(tera.render(&quot;components/zilist.html&quot;, &amp;ctx).unwrap())<br>}</pre><p>In this handler, which shows the last row in the database, we consult the database and get a vector of Zi elements, called disp. A reference to disp is inserted with the “dico” variable name in the ctx Context: ctx.insert(“dico”, &amp;disp), as well as a reference to the query: ctx.insert(“query”, “last entry”). In the last line, the context is rendered by tera to the components/zilist.html template.</p><p>Thank you for reading. Our next instalment will deal with various issues: <a href="https://medium.com/@francis.stephan/developing-a-web-app-with-rust-part-4-sqlx-data-validation-deployment-final-remarks-303e78c2a546">sqlx, data filtering and deployment</a>.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=531e49e28ca2" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Developing a web app with rust: part2, Actix Web]]></title>
            <link>https://medium.com/@francis.stephan/developing-a-web-app-with-rust-part2-actix-web-95cec37af52a?source=rss-52a738199362------2</link>
            <guid isPermaLink="false">https://medium.com/p/95cec37af52a</guid>
            <category><![CDATA[rust]]></category>
            <category><![CDATA[actix-web]]></category>
            <category><![CDATA[htmx]]></category>
            <category><![CDATA[sqlx]]></category>
            <category><![CDATA[tera]]></category>
            <dc:creator><![CDATA[Francis Stephan]]></dc:creator>
            <pubDate>Mon, 03 Jun 2024 17:20:50 GMT</pubDate>
            <atom:updated>2024-06-07T11:05:06.907Z</atom:updated>
            <content:encoded><![CDATA[<p>This story is a continuation of my series on developing a web application with rust (see part 1 <a href="https://medium.com/@francis.stephan/developing-a-web-app-with-rust-first-steps-11e86dfbce7e">here</a>). We speak about Actix Web when we refer to the framework, and actix_web for the rust crate implementing the framework.</p><h3><strong>1. Introduction: Actix as a MVC implementation</strong></h3><p>I understood this after reading <a href="https://kojinglick.com/using-htmx-with-rust-quickstart">Using HTMX with Rust — A Quickstart Guide</a>. This tutorial shows how to implement a counter, using Actix Web with tera templates (and htmx, which not relevant at this stage).</p><p>The Model part (the counter) is represented by the application state through:</p><pre>struct AppStateCounter { counter: Mutex&lt;i32&gt; }</pre><p>The View part is implemented in the tera template as:</p><pre>&lt;p id=&quot;counter&quot;&gt;Counter: {{ counter_value }}&lt;/p&gt;</pre><p>And the Controller part is implemented through the actix_web App component:</p><pre>HttpServer::new( move || {<br>        App::new()<br>        .app_data(tera.clone())<br>        .app_data(counter.clone())<br>...</pre><p>In this excerpt, you see that the actix_web App takes control of both the tera templating system (the view) and the counter (the model).</p><p>At this stage, you should have a brief look at the <a href="https://actix.rs/docs/">Actix Web documentation</a> and get a general understanding of the main concepts:</p><ul><li>the <strong>application</strong> (App) gets wrapped within the HTTP <strong>server </strong>(HttpServer), which takes charge of incoming HTTP requests and delivers HTTP responses through <strong>handlers</strong>;</li><li>the handlers are async functions that take a variable number of parameters (up to 12) that are called data <strong>extractors</strong>: you do not need the formal definition of extractors (you can find it <a href="https://docs.rs/actix-web/latest/actix_web/trait.FromRequest.html#implementors">here</a>), all you need to know is that they provide type-safe access to the data contained in HTTP requests, using deserialization with `serde`. We shall see 5 types of extractors in the chinese character dictionary app.</li></ul><h3>2. The actix main function</h3><p>The following is a shortened version of the main function of the dictionary app (see the full version <a href="https://github.com/francisstephan/rust_character_dictionary/blob/main/src/main.rs">here</a>):</p><pre>pub struct AppState {<br>    db: SqlitePool,<br>}<br><br>#[actix_web::main]<br>async fn main() -&gt; std::io::Result&lt;()&gt; {<br>    ...<br>    env_logger::init_from_env(env_logger::Env::new().default_filter_or(&quot;debug&quot;));<br>    let database_url = std::env::var(&quot;DATABASE_URL&quot;).expect(&quot;DATABASE_URL must be set&quot;);<br>    let pool = SqlitePool::connect(&amp;database_url).await.unwrap();<br>    let tera = Data::new(Tera::new(&quot;./vol/templates/**/*.html&quot;).unwrap());<br><br>    HttpServer::new(move || {<br>        App::new()<br>            .app_data(tera.clone())<br>            .app_data(Data::new(AppState { db: pool.clone() }))<br>            .wrap(Logger::new(&quot;%U %r %s&quot;))<br>            .service(handlers::index)<br>            .service(handlers::size)<br>            .service(handlers::getziform)<br>            .service(handlers::zilist)<br>            ...<br>            .service(handlers::getaddziform)<br>            .service(handlers::addzi)<br>            ...<br>            .service(handlers::dodelete)<br>            .service(handlers::showlast)<br>            .service(handlers::cancel)<br>            .service(actix_files::Files::new(&quot;/assets&quot;, &quot;./vol/assets&quot;).show_files_listing())<br>    })<br>    .bind((&quot;0.0.0.0&quot;, 8090))?<br>    .run()<br>    .await<br>}</pre><p>Two types of data are created outside of HttpServer:</p><ul><li>pool: a connection pool to the sqlite database;</li><li>tera: an entry point to the tera templating engine, containing prsed templates.</li></ul><p>These data are cloned and included within the actix_web App via the <a href="https://docs.rs/actix-web/latest/actix_web/web/struct.Data.html">app_data</a> function.</p><p>The App wraps a Logger, which needs the env_logger crate for display, with the selected <a href="https://docs.rs/actix-web/latest/actix_web/middleware/struct.Logger.html">options</a> (%U = the request URL, %r shows the first line of request, %s shows the response status code).</p><p>Then follows a list of all the handlers to be serviced. The handlers are listed by their name, with no indication of the HTTP verb (get, post, put or delete) nor of the handler parameters (the extractors, see above). We shall explain more about the handlers in the next section.</p><p>The App’s last line allows for the availability of the files contained in the vol/assets directory: css files, logos, javascript files.</p><p>The server gets bound to port 8090 and starts waiting for incoming requests.</p><h3>3. Handlers and HTTP verbs</h3><p>Our 19 handlers will be presented according to the HTTP verbs they serve (this section) and to the extractors (nex section).</p><p>The handlers get their own module, handlers.rs, and you can see the whole code <a href="https://github.com/francisstephan/rust_character_dictionary/blob/main/src/handlers.rs">here</a>.</p><h4>HTTP get verb:</h4><pre>#[get(&quot;/getziform&quot;)]<br>pub async fn getziform(tera: Data&lt;Tera&gt;) -&gt; impl Responder {<br>    let mut ctx = Context::new();<br>    let insert = forms::ziform();<br>    ctx.insert(&quot;content&quot;, &amp;insert);<br>    HttpResponse::Ok().body(tera.render(&quot;components/content.html&quot;, &amp;ctx).unwrap())<br>}</pre><p>All handlers get an attribute such as `#[get(“/getziform”)]` showing the HTTP verb (get in this instance) and the path (“/getziform”) which may also include a variable part (such as in “/dodelete/{id}”). In this instance the path is identical with the handler’s name (getziform), but this need not be so. This handler only needs a reference to the templating engine, through which it inserts a form (provided as a String from the forms module) within the “content” div, resulting in the following screen:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*833UHBCFj2nolqUr5txzpg.png" /></figure><h4>HTTP post verb:</h4><p>If we click to submit in the previous form, this is handed over to the following handler:</p><pre>#[post(&quot;/zilist&quot;)]<br>pub async fn zilist(<br>    formdata: web::Form&lt;dbase::CharData&gt;,<br>    tera: Data&lt;Tera&gt;,<br>    data: web::Data&lt;AppState&gt;,<br>) -&gt; impl Responder {<br>    let chain = &amp;formdata.carac;<br>    let first: char = chain.chars().next().unwrap();<br>    let mut ctx = Context::new();<br>    ctx.insert(&quot;query&quot;, &amp;chain);<br>    let disp = dbase::list_for_zi(data, format!(&quot;{:X}&quot;, first as u32)).await;<br><br>    ctx.insert(&quot;dico&quot;, &amp;disp);<br>    ctx.insert(&quot;diclen&quot;, &amp;disp.len());<br>    HttpResponse::Ok().body(tera.render(&quot;components/zilist.html&quot;, &amp;ctx).unwrap())<br>}</pre><p>Here, the form data will be deserialized according to the CharData struct (defined in our dbase module, see <a href="https://github.com/francisstephan/rust_character_dictionary/blob/main/src/dbase.rs">here</a>), yielding a (hopefully) chinese character which will be looked up in the database through the dbase::list_for_zi function. The result will be fed into the tera context and rendered in the <a href="https://github.com/francisstephan/rust_character_dictionary/blob/main/vol/templates/components/zilist.html">components/zilist.html </a>template.</p><h4>HTTP put and delete verbs:</h4><p>Similarly, we have one handler for the `put` verb (doupdate) and one for the `delete` verb, which will not be discussed here.</p><h3>4. Handlers and extractors</h3><p>We shall briefly present the 5 types of extractors we use:</p><ul><li>tera extractor</li><li>application state extractor</li><li>path data extractor</li><li>form data extractor</li><li>HttpRequest extractor.</li></ul><p>The programmer has to decide which type of extractors he needs based on the handler’s objectives and actions. The order in which these extractors are declared within the parameter list does not matter.</p><h4>4.1 tera extractor:</h4><p>Let us again show our getziform handler:</p><pre>#[get(&quot;/getziform&quot;)]<br>pub async fn getziform(tera: Data&lt;Tera&gt;) -&gt; impl Responder {<br>    let mut ctx = Context::new();<br>    let insert:String = forms::ziform();<br>    ctx.insert(&quot;content&quot;, &amp;insert);<br>    HttpResponse::Ok().body(tera.render(&quot;components/content.html&quot;, &amp;ctx).unwrap())<br>}</pre><p>I need the tera extractor (of type Data&lt;Tera&gt;) each time I want to render anything in the client browser, meaning I need the tera extractor in each of my handlers.</p><p>This done through the tera render function, which takes 2 parameters:</p><ul><li>the html template file to be rendered, in this case:</li></ul><pre>&lt;div id=&quot;content&quot;&gt;{{content | safe}}&lt;/div&gt; &lt;!-- safe prevents HTML escaping --&gt;</pre><ul><li>the context: the context ctx contains all the variables to be supplied to the template: in this case there is just one, named “content” (marked with the ‘safe’ filter), and the value to be attributed to this variable, which is the “insert” String, containing the form we want to show:</li></ul><pre>ctx.insert(&quot;content&quot;, &amp;insert);</pre><h4>4.2 Application state extractor:</h4><p>The following handler, called in response to the /size path, has two extractors:</p><pre>#[get(&quot;/size&quot;)]<br>pub async fn size(tera: Data&lt;Tera&gt;, data: web::Data&lt;AppState&gt;) -&gt; impl Responder {<br>    // https://stackoverflow.com/questions/669092/sqlite-getting-number-of-rows-in-a-database<br>    let mut ctx = Context::new();<br><br>    let size = dbase::getsize(data).await;<br>    let metadata = fs::metadata(&quot;vol/zidian.db&quot;).expect(&quot;Failed to read file metadata&quot;);<br>    let time = metadata.modified().unwrap();<br>    use chrono::prelude::{DateTime, Utc};<br>    let dt: DateTime&lt;Utc&gt; = time.clone().into();<br>    ctx.insert( &quot;content&quot;,<br>        format!(<br>            &quot;The dictionary presently contains {} entries. Last updated on {}&quot;,<br>            &amp;size, &amp;dt.format(&quot;%Y-%m-%d&quot;)<br>        ).as_str(),<br>    );<br>    HttpResponse::Ok().body(tera.render(&quot;components/content.html&quot;, &amp;ctx).unwrap())<br>}</pre><p>These extractors are the tera extractor, which we just saw, and the application state extractor (of type web::Data&lt;AppState&gt;), since it needs data from the database. Remember that we defined AppState as a Struct in main.rs:</p><pre>pub struct AppState {<br>    db: SqlitePool,<br>}</pre><p>This size is obtained from the getsize function in our <a href="https://github.com/francisstephan/rust_character_dictionary/blob/main/src/dbase.rs">dbase</a> module:</p><pre>pub async fn getsize(data: Data&lt;AppState&gt;) -&gt; i64 {<br>    let result: (i64,) = sqlx::query_as(&quot;SELECT COUNT(*) FROM pyhz&quot;)<br>        .fetch_one(&amp;data.db)<br>        .await<br>        .unwrap();<br>    result.0<br>}</pre><h4>4.3 Path data extractor</h4><p>We have only one path extractor in this program:</p><pre>#[delete(&quot;/dodelete/{id}&quot;)]<br>pub async fn dodelete(<br>    iddata: web::Path&lt;dbase::IdData&gt;, // deserialization by serde of path info<br>    tera: Data&lt;Tera&gt;,<br>    data: web::Data&lt;AppState&gt;,<br>) -&gt; impl Responder {<br>    let id = iddata.id;<br>    let chaine = dbase::delete_db(id, data).await;<br>    let mut ctx = Context::new();<br>    ctx.insert(&quot;content&quot;, &amp;chaine);<br>    HttpResponse::Ok().body(tera.render(&quot;components/content.html&quot;, &amp;ctx).unwrap())<br>}</pre><p>This handler has 3 extractors, including one path extractor, of type <strong>web::Path&lt;dbase::IdData&gt;</strong>. The IdData struct is defined in the dbase module as:</p><pre>#[derive(Deserialize)]<br>pub struct IdData {<br>    pub id: i64,<br>}</pre><p>This means that the {id} component in the path will be deserialized, providing IdData.id of type i64.</p><h4>4.4 Form data extractor</h4><p>As an example, we shall consider the addzi handler:</p><pre>#[post(&quot;/addzi&quot;)]<br>pub async fn addzi(<br>    zidata: web::Form&lt;dbase::Idzi&gt;,<br>    tera: Data&lt;Tera&gt;,<br>    data: web::Data&lt;AppState&gt;,<br>) -&gt; impl Responder {<br>    let chaine = dbase::addzi_db(zidata, data).await;<br>    let mut ctx = Context::new();<br>    ctx.insert(&quot;content&quot;, &amp;chaine);<br>    HttpResponse::Ok().body(tera.render(&quot;components/content.html&quot;, &amp;ctx).unwrap())<br>}</pre><p>Our form data extractor, in this instance, is of type web::Form&lt;dbase::Idzi&gt;, with the Idzi struct being defined in the dbase module as:</p><pre>#[derive(Deserialize)]<br>pub struct Idzi {<br>    pub id: i64,<br>    pub pinyin_ton: String,<br>    pub unicode: String,<br>    pub sens: String,<br>}</pre><p>The data from the form will be deserialized, ready for inclusion in the databas of a new record.</p><h4>4.5. HttpRequest extractor:</h4><p>This extractor gives you access to some low level info about the request:</p><pre>#[get(&quot;/&quot;)]<br>pub async fn index(req: HttpRequest, tera: Data&lt;Tera&gt;) -&gt; impl Responder {<br>    let ipaddr = actix_remote_ip::get_remote_ip(&amp;req);<br>    let mut ctx = Context::new();<br>    if ipaddr.is_loopback() {<br>        ctx.insert(&quot;contenu&quot;, &quot;Connected to local server&quot;);<br>    } else {<br>        ctx.insert(&quot;contenu&quot;, &quot;Caution: all modifications to the database will be discarded at the end of the fly.io session&quot;);<br>    }<br>    HttpResponse::Ok().body(tera.render(&quot;index.html&quot;, &amp;ctx).unwrap())<br>}</pre><p>In our case, we wanted to know wether the server was called from a distant client or not, because for a distant client the database is in fact read only, since it gets reinitialized after a short period.</p><p>Our <a href="https://medium.com/@francis.stephan/developing-a-web-app-with-rust-part-3-tera-templating-system-and-htmx-531e49e28ca2">next instalment</a> will deal with the <strong>tera</strong> templating system and <strong>htmx</strong>.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=95cec37af52a" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Developing a web app with rust: first steps]]></title>
            <link>https://medium.com/@francis.stephan/developing-a-web-app-with-rust-first-steps-11e86dfbce7e?source=rss-52a738199362------2</link>
            <guid isPermaLink="false">https://medium.com/p/11e86dfbce7e</guid>
            <category><![CDATA[actix-web]]></category>
            <category><![CDATA[tera]]></category>
            <category><![CDATA[htmx]]></category>
            <category><![CDATA[sqlx]]></category>
            <category><![CDATA[rust]]></category>
            <dc:creator><![CDATA[Francis Stephan]]></dc:creator>
            <pubDate>Sat, 25 May 2024 21:38:53 GMT</pubDate>
            <atom:updated>2024-06-03T17:21:49.690Z</atom:updated>
            <content:encoded><![CDATA[<p>This the first instalment of a series dedicated to developing a basic CRUD web application with <strong>rust</strong>.<strong> </strong>In it I shall describe the motivation and general design decisions. Further instalments will deal with the web framework (actix_web), the database framework (sqlx) and the templating system (tera).</p><h3>1. Why rust ?</h3><p>While learning Go language 2 years ago, I discovered it included out of the box all that was needed for a web application on the server side. So I wrote a <a href="https://github.com/francisstephan/gin-html-tutorial">Go + Gin REST tutorial</a> as well as 2 small applications based on that tutorial, the last one being <a href="https://github.com/francisstephan/character_dictionary_manager">Chinese character dictionary management</a></p><p>But then I decided I wanted to port that last application to Rust language. Why is that?</p><ul><li>I very much appreciate rust’s “0 cost abstractions”, allowing for high level language features with functional programming concepts such as Option / Result, mapping over a vector, destructuring and pattern matching. Go provides some substitutes for these concepts, but not enough for my taste.</li><li>I do not like garbage collectors.</li></ul><p>I still think that Go is excellent for learning about web applications and for prototyping them.</p><h3>2. Design options</h3><p>While Go comes with all the required software (plus the Gin web framework package which I came to really appreciate), when arriving in<strong>rust</strong> country, you are on your own…</p><p>So I spent a few months reading all I could on web development with rust — once I had read “The rust programming language”, of course. Among the books I read the most helpful were :</p><ul><li>Zero to production in Rust — an opinionated introduction to backend development, by Luca Palmieri. This is indeed an opinionated book, so I had to come back to it after I read the following:</li><li>Code like a pro in Rust, by Brenden Matthews (Manning), which dedicates only one chapter to ‘Building an HTTP REST API service’. Complete that chapter, then come back to the Palmieri book, which will make more sense.</li></ul><p>After all that reading, I knew I had to get my feet wet. I already had the overall design of my program, based on the Go version. What I needed was to select the adequate libraries for web framework, database interface, templating and front-end framework:</p><ul><li>web framework: I chose actix_web, based on Palmieri’s recommendation, on the excellent <a href="https://actix.rs/docs/">actix_web documentation </a>available and on several resources mentioned in the comments of my <a href="https://github.com/francisstephan/rust_character_dictionary">source code</a>;</li><li>templating: I chose <a href="https://keats.github.io/tera/docs/">Tera</a> for the same reasons, noting that it looked to play well with actix_web;</li><li>database interface: I chose sqlx, mainly because it directly relies on SQL, making it much more directly usable. I did not, however, use the compilation time checking which looks to be one of the strong points of sqlx; sqlx has the drivers necessary for my sqlite3 database, which is the same as for the Go version;</li><li>front-end framework: I used <strong>htmx</strong> which has been my option for the Go version of the program. Actually <strong>htmx</strong>works with Rust without any difference, so all the considerations I developed in my <a href="https://medium.com/@francis.stephan/htmx-for-go-gin-web-development-ba206b6e2e7b">htmx article</a> are still valid here.</li></ul><h3>3. Program layout</h3><p>I adopted the same layout as for the Go version, except that I chose to have a separate module for handlers, making fo a cleaner code, with the following structure:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/292/1*540zG_MhCfpuV4dN4Y5T5w.png" /></figure><p>In this layout, main.rs defines the overall structure of the program, defining both the application data and the various handlers, with three modules:</p><ul><li>handlers.rs for the various routes,</li><li>dbase.rs for database access,</li><li>forms.rs defining most of the forms used by the program (most of them having the same name and function as in the go version).</li></ul><p>The vol directory contains various assets (css, pictures), templates (html files) and the zidian.db sqlite3 database.</p><p>The <a href="https://medium.com/@francis.stephan/developing-a-web-app-with-rust-part2-actix-web-95cec37af52a">next section</a> will be dedicated to implementing the actix_web framework for the project.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=11e86dfbce7e" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Discovering Zed for rust development, updated: Zed AI]]></title>
            <link>https://medium.com/@francis.stephan/discovering-zed-for-rust-development-b49c80452ca9?source=rss-52a738199362------2</link>
            <guid isPermaLink="false">https://medium.com/p/b49c80452ca9</guid>
            <category><![CDATA[editor]]></category>
            <category><![CDATA[rust]]></category>
            <dc:creator><![CDATA[Francis Stephan]]></dc:creator>
            <pubDate>Wed, 15 May 2024 13:25:48 GMT</pubDate>
            <atom:updated>2024-09-09T21:03:16.237Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/141/1*aE-libv0hgsnPPa0Wu0VXw.png" /></figure><p>I never liked IDEs, and preferred development text editors. I used <strong>atom</strong> until it got ‘sunsetted’ end of 2022, when I switched to <strong>VSCode</strong>, which was a very good experience.</p><p>Recently, while developing a toy rust project (<a href="https://github.com/francisstephan/rust_character_dictionary/tree/main">https://github.com/francisstephan/rust_character_dictionary/tree/main</a>) I discovered <a href="https://zed.dev/"><strong>Zed</strong></a><strong>.</strong></p><p>Zed is ‘a high-performance, multiplayer code editor from the creators of Atom and Tree-sitter’. It is available for 6 languages out of the box (Elixir, Go, Javascript, Python, Ruby, Rust), and more may be added by the user, but the present review specifically deals with my experience with Zed for Rust development</p><h3>1. Syntax checking</h3><p>Zed provides real time syntax checking, and full checking on each file save. For Rust, this is equivalent to running <strong>cargo check</strong>. The diagnostics are fully reported in a separate thumbnail which you activate by clicking on the error in the status bar. This considerably improves development time, meaning you only go for compilation once all errors are solved — and generally, the program works!<br> One exception is borrow checker errors, which I find are more easily readable in the cargo version.<br> Automatic formatting when saving a file is also an useful feature — though sometimes annoying. For instance, <strong>tera</strong> templates are not taken into account, meaning I still shall use vim to format my html tera templates… until I find the adequate plugin.</p><h3>2. Automatic type indication</h3><p>While autocompletion is not a new feature, type indication is very useful for a strongly typed language such as rust. As an example, see the following screen:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*9cnc_QOQeRtvNoXrUogs9w.png" /></figure><p>When I hover the mouse over the ‘res’ variable, a popup shows up, with various informations, the most interesting one being the type of the variable, in this case <strong>SqlQueryResult</strong>. With that info I look on the sqlx documentation and find the `last_insert_rowid` function I was looking for.</p><h3>3. Artificial intelligence support</h3><p>Currently, Zed supports OpenAI assistance (requires an OpenAI API key), and Github Copilot, (requires a Github Copilot subscription.) Since I don’t have either, I haven’t tested these functions. <br>However, the Zed development roadmap (<a href="https://zed.dev/roadmap">https://zed.dev/roadmap</a>) promises as a short-term goal to ship AI-enabled features based on emerging tech such as LLMs and vector databases, with no need for an OpenAI key. To be continued …</p><h4><strong>Edited Sep.8, 2024:</strong></h4><p>Zed Editor just announced <a href="https://zed.dev/ai">Zed AI</a>, an AI assistant integrated with Zed, powered by Claude 3.5 Sonnet. Read an in-depth introduction at <a href="https://zed.dev/blog/zed-ai">https://zed.dev/blog/zed-ai</a>. From this blog I read that “Zed AI is available now, free during our initial launch period.”</p><p>I’ll definetely give it a try for my next project.</p><h3>4. Collaborative support</h3><p>This also is a feature for which I have no present use, but which I feel may be very useful for team development.</p><h3>As a conclusion,</h3><p>I feel Zed is well worth trying for any rust developer.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=b49c80452ca9" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[htmx for GO gin web development]]></title>
            <link>https://medium.com/@francis.stephan/htmx-for-go-gin-web-development-ba206b6e2e7b?source=rss-52a738199362------2</link>
            <guid isPermaLink="false">https://medium.com/p/ba206b6e2e7b</guid>
            <category><![CDATA[web-development]]></category>
            <dc:creator><![CDATA[Francis Stephan]]></dc:creator>
            <pubDate>Mon, 25 Mar 2024 15:07:07 GMT</pubDate>
            <atom:updated>2024-03-26T13:36:31.659Z</atom:updated>
            <content:encoded><![CDATA[<p>I wish to present my experience using htmxtechnology within the context of web development with golang and the gin web framework.</p><p>As per the <a href="https://htmx.org/">htmx</a> site, <strong><em>“htmx gives you access to AJAX, CSS Transitions, WebSockets and Server Sent Events directly in HTML, using attributes, so you can build modern user interfaces with the simplicity and power of hypertext”.</em></strong> This article is not an htmxtutorial: the <a href="https://htmx.org/docs/">htmx docs</a> are user friendly and quite extensive. It describes how I used htmxto develop my “<a href="https://gozdman.fly.dev/">chinese character dicitionary manager</a>” (“gozdman”), showing some problems I had and how to solve them.</p><p>All source code is available on <a href="https://github.com/francisstephan/character_dictionary_manager">https://github.com/francisstephan/character_dictionary_manager</a></p><p>We shall have five sections:</p><ul><li>using htmx to generate ajax requests,</li><li>two step calls,</li><li>adding a ‘Cancel’ button to the forms,</li><li>displaying server errors,</li><li>using htmx to manage keyboard shortcuts.</li></ul><h4>1. Using htmx to generate ajax requests</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/896/1*hZmdjPlXrVpWLl2Qkutzig.png" /><figcaption>After /size GET request</figcaption></figure><p>All the buttons in the top line (Size, Zi =&gt; Pinyin, …) have htmx attributes and generate ajax requests based on these attributes.</p><p>For example, the Size button, when clicked, will start a GET AJAX request over the /size route, the result of which will overwrite the content (innerHTML) of the div element with CSS id &quot;content&quot; (further referred to as the #content div):</p><pre>&lt;button class = &quot;menubouton&quot; hx-get=&quot;/size&quot; hx-target=&quot;#content&quot; hx-swap=&quot;innerHTML&quot; &gt;Size&lt;/button&gt;</pre><p>The &quot;#content&quot; div source code within index.html :</p><pre>&lt;div id=&quot;content&quot;&gt;{{ .content }}&lt;/div&gt;</pre><p>This div’s content may be overwritten in two ways:</p><ul><li>with the GO templating system, through the {{.content}} tag</li><li>with the htmx ajax requests, such as here above, which will overwrite the text with the dictionary’s size.</li></ul><p>The /size route is handled with the dicsize handler within zdman.go :</p><pre>func dicsize(c *gin.Context) {<br>	len, time := data.Dicsize()<br>	c.Data(http.StatusOK, &quot;text/html; charset=utf-8&quot;, []byte(&quot;The dictionary presently contains &quot;+len+&quot; entries ; last updated on &quot;+time))<br>}</pre><p>We do not need to bother where this text will be displayed: this was already specified in the hx-target = &quot;#content&quot; tag of the button element hereabove.</p><h4>2. Two step requests:</h4><p>Many interactions with the program will require two requests:</p><ul><li>one to generate a form requiring user input (sending a GET request to generate this form)</li><li>one to process this form (sending a POST, PUT or DELETE request).</li></ul><p>For instance, identifying a chinese character (Zi =&gt; Pinyin) is done in two steps (two AJAX requests):</p><ul><li><strong>one GET request:</strong></li></ul><pre>&lt;button class = &quot;menubouton&quot; hx-get=&quot;/getziform&quot; hx-target=&quot;#content&quot; hx-swap=&quot;innerHTML&quot; &gt;Zi =&gt; Pinyin&lt;/button&gt;</pre><p>The gin handler in `zdman.go` displays the form within the #content div:</p><pre>func getziform(c *gin.Context) {<br>	c.Data(http.StatusOK, &quot;text/html; charset=utf-8&quot;, []byte(forms.Ziform()))<br>}</pre><p>Since the program includes not less than 7 forms, we chose to have a forms golang module, containing all forms. The Ziform function contains the following form:</p><pre>func Ziform() string {<br>	return `<br>	  &lt;form hx-post=&quot;/listzi&quot; hx-target=&quot;#content&quot; hx-swap=&quot;innerHTML&quot; &gt;<br>		    &lt;label for=&quot;carac&quot;&gt;Character:&lt;/label&gt;<br>		    &lt;input id=&quot;carac&quot; name=&quot;carac&quot; type=&quot;text&quot; autofocus required minlength=&quot;1&quot; maxlength=&quot;1&quot;&gt;<br>		    &lt;button class=&quot;menubouton&quot; type=&quot;submit&quot;&gt;Click to submit &lt;/button&gt;<br>			&lt;button class=&quot;menubouton&quot; hx-get=&quot;/remove&quot;&gt;Cancel&lt;/button&gt;<br>	  &lt;/form&gt;<br>	`<br>}</pre><p>As a result, we get the following screen:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/733/1*ZgyiYcQYXcYxUN2lVm56vA.png" /><figcaption>After first (GET) request</figcaption></figure><ul><li><strong>one POST request:</strong></li></ul><p>When the form here above is submitted, it will be processed as a POST request by the adequate handler (getziform within zdman.go), and the result will, once again, overwrite the #content div. If we enter the 陶 character, we get the following result:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/694/1*ZOGxJ6IxHUdQrS7yMqpJfg.png" /><figcaption>After second (POST) request</figcaption></figure><h4>3. Having a cancel button in our forms:</h4><p>We tried the htmx-remove extension, but this did not satisfy our requirements.</p><p>We solved this by associating a specific GET request with these buttons, requesting for removal of the #content div&#39;s content:</p><pre>&lt;button class=&quot;menubouton&quot; hx-get=&quot;/remove&quot; hx-target=&quot;#content&quot; hx-swap=&quot;innerHTML&quot;&gt;Cancel&lt;/button&gt;</pre><p>and the corresponding handler in zdman.go:</p><pre>func remove(c *gin.Context) {<br>	c.Data(http.StatusOK, &quot;text/html; charset=utf-8&quot;, []byte(&quot;Form canceled.&quot;))<br>}</pre><h4>4. Displaying server errors:</h4><p>With HTMX (version 1.9.9) server errors are only shown in the console, which is not acceptable in production code. We found good information in <a href="https://xvello.net/blog/htmx-error-handling/">https://xvello.net/blog/htmx-error-handling/</a> , and we used an EventListener in javascript, based on the htmx:afterRequest event:</p><pre>window.onload = function() {<br>  elem = document.body;<br>  document.body.addEventListener(&#39;htmx:afterRequest&#39;, function (evt) {<br>      contenu = document.getElementById(&quot;content&quot;);<br>      if (evt.detail.failed &amp;&amp; evt.detail.xhr) {  // display error message within the document (and not only the console)<br>        // Server error with response contents, equivalent to htmx:responseError<br>        console.warn(&quot;Server error&quot;, evt.detail)<br>        const xhr = evt.detail.xhr;<br>        contenu.innerHTML = `Unexpected server error: ${xhr.status} - ${xhr.statusText}`;<br>      } <br>    });<br>};</pre><h4>5. Keyboard shortcuts:</h4><p>We use 3 keyboard shortcuts:</p><ul><li>z to load the Zi =&gt; Pinyin form,</li><li>p to load the Pinyin =&gt; Zi form, and</li><li>Esc to abort a form.</li></ul><p>z and p eventlisteners should only be active when no form is displayed, while Esc should only be active in the opposite case, i.e. when a form is displayed. This is easily done using HTMX ajax functions. For instance, for the Esc key, the event listener (within footer.html) is :</p><pre>function esckey(e) {<br>   if(e.keyCode==27) htmx.ajax(&#39;GET&#39;, &quot;/remove&quot;, {target: &quot;#content&quot;, swap: &quot;innerHTML&quot;}); // Esc key : cancel form<br>}</pre><p>The syntax of this function call is very similar to the htmx attributes of the Cancel button here above.</p><p>The function to add or remove key event listeners tests the presence of a &lt;form &gt; element in the #content div :</p><pre>function ajustkey() {<br>      contenu = document.getElementById(&quot;content&quot;);<br>	  if (contenu.innerHTML.startsWith(&quot;&lt;form &quot;)) { // if form, enable Esc and remove z and p listeners<br>		  document.body.removeEventListener(&quot;keydown&quot;, shortkey);<br>		  document.body.addEventListener(&quot;keydown&quot;, esckey);<br>	  }<br>	  else { // if not form, remove Esc (there is nothing to cancel) and enable z and p listeners<br>		  document.body.addEventListener(&quot;keydown&quot;, shortkey);<br>		  document.body.removeEventListener(&quot;keydown&quot;, esckey);<br>	  }<br>}</pre><p>This function is triggered by the htmx:afterRequest event, through an event listener initially added to the page (remember, all htmx calls are ajax calls, meaning that the page is only loaded once):</p><pre>window.onload = function() {<br>   elem = document.body <br>   elem.addEventListener(&quot;keydown&quot;, shortkey) // initially enable z and p shortcut keys<br>   elem.addEventListener(&quot;htmx:afterRequest&quot;, ajustkey) // after ajax request performed by htmx, adjust keydown listeners<br>}</pre><h4>Conclusion:</h4><p>As a conclusion we may say that:</p><ul><li>HTMX makes for an elegant and simple program flow, using all HTTP verbs. Here we used 4 verbs: GET, POST, PUT and DELETE.</li><li>HTMX combines very well with go and the gin web framework (for which we propose a tutorial in <a href="https://github.com/francisstephan/gin-html-tutorial">https://github.com/francisstephan/gin-html-tutorial</a>)</li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=ba206b6e2e7b" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>