Intro

This is my personal journal on different topics I find interesting as I travel through life at approximately one second per second. My goal is to collect notes and thoughts and place them here for safe keeping. If you press the s key a live search will appear and may help you find what you're looking for more quickly.

Top Projects

• req_md : Requests via Markdown

  This is a CLI tool that understands how form http requests from an easy to read and understand markdown format. Currently it is just a Rust binary; however, I have hopes of also fashioning a Neovim plugin around it.

• elastic_lens : Ergonomic Elasticsearch Client in Rust

  Does what it says on the tin. I work with Elasticsearch a lot for my day job and when I wanted to get my hands wet with a bigger Rust project this was the outcome. It currently powers a real world use case for us.

• mdbook-journal : Journal Plugin for mdbook

  Plugin that powers the bulk of this journal that you are reading. This tool allows you to quickly add and organize journal content within a markdown book. As I get time I plan to add a lot more interesting features to it that has better "blog-like" functionality.

Index for snippet/rust/README.md

Playing With Git2

mod test {
    use anyhow::{Context, Ok, Result};
    use git2::Repository;
    use std::path::PathBuf;

    #[test]
    fn opening_a_repo() -> Result<()> {
        let file = PathBuf::from("crates/async_cb/src/lib.rs");
        let repo = Repository::discover("/home/bfalk/Projects/journal/crates/")?;
        let head = repo.revparse("HEAD")?;
        let id = head.from().unwrap().id();
        let commit = repo.find_commit(id)?;
        let tree = commit.tree()?;
        let entry = tree.get_path(&file)?;
        let blob = entry.to_object(&repo)?.into_blob().unwrap();
        let content = String::from_utf8(blob.content().to_owned())?;
        println!("{content}");
        Ok(())
    }
}

This snippet opens the repository for this journal, fetches the "HEAD" revision. From this you can get the id of the commit, which is the sha of that particular commit. Once you have a commit it becomes a drill-down to a particular file, which is what I'm interested in. Because the files can be anything it appears, if I want to get the contents as a string the "blob" it needs to be converted.

I've been trying to learn how to use the git2-rs bindings for my anchors aweigh project. It has been extremely slow going as the documentation is extremely sparse and hard to follow. The biggest breakthroughs I've made so far is these:

• examples have been the best source so far
• a lot of online resources are very out of date
• Repository::discover is handy for opening a repo

Routing Functions

#![allow(dead_code, unused_imports, unused_variables)]

mod structures {
    pub struct Config(pub String);
    pub struct User(pub u32);
    pub struct Context {
        pub(super) user: User,
        pub(super) config: Config,
    }
}

mod context {
    use super::structures::*;

    pub trait Ctx {
        fn user(&self) -> &User;
        fn config(&self) -> &Config;
    }

    impl Ctx for Context {
        fn user(&self) -> &User {
            &self.user
        }

        fn config(&self) -> &Config {
            &self.config
        }
    }

    pub trait FromContext {
        fn from_context(ctx: &impl Ctx) -> &Self;
    }

    impl FromContext for User {
        fn from_context(ctx: &impl Ctx) -> &Self {
            ctx.user()
        }
    }

    impl FromContext for Config {
        fn from_context(ctx: &impl Ctx) -> &Self {
            ctx.config()
        }
    }
}

mod handler {
    use super::context::{Ctx, FromContext};

    pub trait Handle<T> {
        type Value;
        fn call(self, ctx: &impl Ctx) -> Self::Value;
    }

    impl<F, T, R> Handle<T> for F
    where
        F: Fn(&T) -> R,
        T: FromContext,
    {
        type Value = R;
        fn call(self, ctx: &impl Ctx) -> Self::Value {
            (self)(T::from_context(ctx))
        }
    }

    impl<F, T1, T2, R> Handle<(T1, T2)> for F
    where
        F: Fn(&T1, &T2) -> R,
        T1: FromContext,
        T2: FromContext,
    {
        type Value = R;
        fn call(self, ctx: &impl Ctx) -> Self::Value {
            (self)(T1::from_context(ctx), T2::from_context(ctx))
        }
    }

    pub trait CtxHandle: Ctx + Sized {
        fn call<T, H>(&self, handle: H) -> H::Value
        where
            H: Handle<T>,
        {
            handle.call(self)
        }
    }

    impl<C: Ctx + Sized> CtxHandle for C {}
}

#[cfg(test)]
mod test {
    use super::context::*;
    use super::handler::*;
    use super::structures::*;

    fn next_user(user: &User) -> u32 {
        user.0 + 1
    }

    fn hello(config: &Config) -> String {
        format!("hello {}", config.0.as_str())
    }

    #[test]
    fn it_works() {
        let ctx = Context {
            user: User(42),
            config: Config("world".to_owned()),
        };

        assert_eq!(next_user.call(&ctx), 43);
        assert_eq!(ctx.call(next_user), 43);

        assert_eq!(ctx.call(hello), "hello world");
        assert_eq!(hello.call(&ctx), "hello world");
    }
}

Async Callback Struct

The Structure

mod structure {
    use ::futures::future::BoxFuture;

    type Cb<E> = Box<dyn Fn(E) -> BoxFuture<'static, ()>>;

    pub struct Callback<E> {
        pub(super) func: Cb<E>,
    }
}

First I create a Cb<E> type alias using BoxFuture from the futures crate. Before explaining this Cb<E> more first it helps to make sure we understand exactly what this BoxFuture actually is. It turns out that it is also a type alias:

type BoxFuture<'a, T> = Pin<Box<dyn Future<Output = T> + Send + 'a>>;

This BoxFuture can be read as a dynamically allocated future on the stack, it must be be pinned to prevent references from moving, and has a reported lifetime. With this understanding we can now look back at the Cb<E> type. This is a dynamically allocated function pointer which receives some owned type E and returns a BoxFuture.

The 'static lifetime is assigned to the BoxFuture because it owns it's own data and therefore can live the entire life of the application. The type of () simply means the future returns no output.

The Implementation

mod impls {
    use super::Callback;

    impl<E> Callback<E> {
        pub fn new<F, Ret>(func: F) -> Self
        where
            F: Fn(E) -> Ret + 'static,
            Ret: Future<Output = ()> + Send + 'static,
        {
            Self {
                func: Box::new(move |e| Box::pin(func(e))),
            }
        }

        pub fn call(&self, e: E) -> impl Future<Output = ()> {
            (self.func)(e)
        }
    }
}

This Callback<E> can seem a little scary; however, I think after we break down the code it will seem more approachable. This new function has two declared types of F and Ret. The F type must be a function which returns a type Ret and the function's lifetime must be 'static. The Ret which the function returns has to implement a Future that has no output, is Send safe, and has a 'static lifetime.

The Ret type of this signature is very important, it is what allows us to create our final callback. This future return is exactly what can be boxed into our Cb<E> from before. Inside of the method body a lambda is boxed up to create the BoxFuture when called. With that we now have a callback ready.

The Test

mod test {
    use super::Callback;
    use mockall::predicate::*;
    use mockall::*;

    #[cfg_attr(test, mockall::automock)]
    trait Foo {
        async fn say(&self, string: &str);
    }

    #[tokio::test]
    async fn example() {
        let mut foo = MockFoo::new();

        foo.expect_say()
            .with(predicate::eq("hello"))
            .returning(|_| ());

        foo.expect_say()
            .with(predicate::eq("goodbye"))
            .returning(|_| ());

        let cb = Callback::new(|foo: MockFoo| async move {
            foo.say("hello").await;
            foo.say("goodbye").await;
        });

        cb.call(foo).await;
    }
}

Advanced Async Testing Via Mockall

#![allow(dead_code, unused_imports, unused_variables)]

use anyhow::{Ok, Result};
use futures::future::BoxFuture;

struct Pool;
pub struct Config;
type AsyncCallback<E> = Box<dyn Fn(&E) -> BoxFuture<'static, ()>>;
struct Callback<E>(AsyncCallback<E>);

impl<E> Callback<E> {
    pub async fn call(&self, value: &E) {
        (self.0)(value).await
    }
}

impl<E> Default for Callback<E> {
    fn default() -> Self {
        let do_nothing = |_: &E| async {};
        Self(Box::new(move |e: &E| Box::pin(do_nothing(e))))
    }
}

impl<E> Callback<E> {
    fn new<F, Fut>(func: F) -> Self
    where
        F: Fn(&E) -> Fut + 'static,
        Fut: Future<Output = ()> + Send + 'static,
    {
        Self(Box::new(move |e: &E| Box::pin(func(e))))
    }
}

#[cfg_attr(test, mockall::automock)]
trait Db {
    fn pool(&self) -> &Pool;

    async fn exec<Q>(&self, query: &Q) -> Result<Q::Value>
    where
        Q: Query + 'static,
    {
        query.exec(self.pool()).await
    }
}

impl Db for &Pool {
    fn pool(&self) -> &Pool {
        self
    }
}

trait Query {
    type Value;
    async fn exec(&self, pool: &Pool) -> Result<Self::Value>;
}

#[cfg_attr(test, mockall::automock)]
trait Repo {
    async fn report(&self, bar: u32);
}

pub trait Env {
    fn db(&self) -> &impl Db;
    fn repo(&self) -> &impl Repo;
    fn config(&self) -> &Config;
}

struct ImporterEnv<D: Db, R: Repo> {
    db: D,
    repo: R,
}

impl<D: Db, R: Repo> Env for ImporterEnv<D, R> {
    fn db(&self) -> &impl Db {
        &self.db
    }

    fn repo(&self) -> &impl Repo {
        &self.repo
    }

    fn config(&self) -> &Config {
        todo!()
    }
}

#[derive(Debug, PartialEq, Eq)]
pub struct GetData {
    pub value: u8,
}

impl Query for GetData {
    type Value = u32;
    async fn exec(&self, pool: &Pool) -> Result<Self::Value> {
        todo!()
    }
}

async fn download_data<E>(env: &E) -> Result<u32>
where
    E: Env,
{
    let query = GetData { value: 42 };
    let val = env.db().exec(&query).await?;
    Ok(val)
}

#[cfg(test)]
mod test {
    type TestEnv = ImporterEnv<MockDb, MockRepo>;
    use super::*;
    use mockall::predicate::*;
    use mockall::*;
    use rstest::{fixture, rstest};

    #[fixture]
    fn test_env() -> TestEnv {
        TestEnv {
            repo: MockRepo::new(),
            db: MockDb::new(),
        }
    }

    #[rstest]
    #[tokio::test]
    async fn it_works(mut test_env: TestEnv) {
        test_env
            .db
            .expect_exec()
            .with(predicate::eq(GetData { value: 42 }))
            .times(1)
            .returning(|_| Ok(69));
        let val = download_data(&test_env).await.unwrap();
        assert_eq!(val, 69);
    }
}