DEV Community: icsboyx

My Tiny Rust Utils, Part 5: mod.rs

icsboyx — Thu, 30 Apr 2026 16:13:25 +0000

This last part is about the least impressive file in the crate:

pub mod helpers;
pub mod macros;
pub mod save_load;
pub mod web;

That is src/utils/mod.rs.

It is just four lines.

And maybe that is why it feels like the right place to end the series.

Why a boring file still matters

I like this file because it does not pretend to be smarter than it is.

It just says:

these are the utility modules
they live together
this is the shape of the toolbox

After the previous parts, that shape is easier to read:

macros.rs helps me see what the program is doing
helpers.rs removes a bit of error and JSON friction
save_load.rs gives me one place for config-like persistence
web.rs keeps HTTP glue from leaking everywhere

None of those files is huge.

None of them is a framework.

That is very intentional.

I think I work better when the code is allowed to stay small and honest for as long as possible.

How the crate feels to me

This utils crate is not something I built because I wanted to be abstract.

It is something I built because I know how I work.

If I do not create a little structure around repeated pain points, I end up with the same code copied in slightly different ways across the project.

And then I get annoyed with myself later.

So this crate is a compromise between two things:

I do not want ceremony
I also do not want chaos

That is really the whole story.

A more personal ending

I think this is the part where I should be honest.

For me, coding is not really "work" in the emotional sense, even when it is tiring.

It is more like a mix of:

joy
frustration
curiosity
stubbornness

Sometimes it is fun.

Sometimes it is painful in a very specific and ridiculous way.

Sometimes a tiny bug ruins half a day.

Sometimes a four-line helper makes the whole project feel lighter again.

That is why I keep doing it.

Not because every line of code is important.

Not because every project needs to become a product.

But because coding, for me, is still one of the nicest forms of mental exercise I know.

It is a hobby, a habit, and occasionally a headache I choose on purpose.

And honestly, I mean that in a good way.

Final thought

If you also keep building small local utility files for your own projects, I do not think that is a bad sign.

Maybe it just means you are slowly learning what kind of friction bothers you, and what kind of tools help you think.

That is more or less what this crate is for me.

My Tiny Rust Utils, Part 4: web.rs

icsboyx — Thu, 30 Apr 2026 16:10:05 +0000

I like reqwest.

I just do not always like seeing raw reqwest patterns repeated all over my application code.

That is the whole reason src/utils/web.rs exists.

I don't need full HTTP framework. I just need one place to keep a few recurring things:

response decoding
basic header preparation
a default User-Agent
a simpler response type for the rest of the app

A smaller response model

The file starts here:

#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum ResponseBody {
    Json(Value),
    Text(String),
    Binary(Bytes),
}

#[derive(Debug, Clone)]
pub struct HttpReply {
    pub status: StatusCode,
    pub headers: HeaderMap,
    pub body: ResponseBody,
}

That already helps me.

Instead of passing raw reqwest::Response deeper into the app, I get a smaller local type that matches how this project actually thinks about HTTP replies.

That is enough abstraction for me. No more is needed here.

`json_try_into`

The helper I probably use the most is this one:

impl ResponseBody {
    pub fn json_try_into<T>(&self) -> Result<T>
    where
        T: for<'de> Deserialize<'de>,
    {
        match self {
            ResponseBody::Json(json) => serde_json::from_value(json.clone()).map_err(Into::into),
            _ => bail!("Response body is not JSON, cannot deserialize"),
        }
    }
}

That lets me write things like:

let token = http_reply.body.json_try_into::<BotIdentity>()?;

I like this because it is strict in a simple, readable way.

If the body is not JSON, it says so.

If the JSON shape does not match the target type, it says so.

That is exactly the level of honesty I want from utility code.

Default headers without fuss

The file also takes care of the default User-Agent:

pub const DEFAULT_USER_AGENT: &str = concat!(env!("CARGO_PKG_NAME"), "/", env!("CARGO_PKG_VERSION"));

fn prepare_headers(headers: Option<HeaderMap>, user_agent: Option<&str>) -> Result<HeaderMap> {
    let mut headers = headers.unwrap_or_default();

    if !headers.contains_key(header::USER_AGENT) {
        let value = HeaderValue::from_str(user_agent.unwrap_or(DEFAULT_USER_AGENT))?;
        headers.insert(header::USER_AGENT, value);
    }

    Ok(headers)
}

This is a tiny thing, but it is one of those details that becomes annoying if I have to remember it in every call site.

So I would rather centralize it once and stop thinking about it.

The public API stays small

The actual entry points are just these:

pub async fn get_http(
    url: impl AsRef<str>,
    headers: Option<HeaderMap>,
    query: Option<&[(&str, &str)]>,
    user_agent: Option<&str>,
) -> Result<HttpReply> {
    let headers = prepare_headers(headers, user_agent)?;
    let request = http_client().get(url.as_ref()).headers(headers);
    let response = apply_query(request, query).send().await?;

    decode_response(response).await
}

pub async fn post_http(
    url: impl AsRef<str>,
    headers: Option<HeaderMap>,
    query: Option<&[(&str, &str)]>,
    body: Option<Value>,
    user_agent: Option<&str>,
) -> Result<HttpReply> {
    let headers = prepare_headers(headers, user_agent)?;
    let mut request = http_client().post(url.as_ref()).headers(headers);
    if let Some(body) = body {
        request = request.json(&body);
    }
    let response = apply_query(request, query).send().await?;

    decode_response(response).await
}

I am happy when a utility module stays about this size.

It does not try to be clever.

It just absorbs repetition so the rest of the code stays calmer.

Where it pays off

A real call site looks like this:

let sub_reply: Value = post_http(url, Some(headers), None, Some(subscription_request.json_value()?), None)
    .await?
    .body
    .json_try_into()?;

I still recognize that as ordinary application code.

That is important to me.

If the wrapper made this harder to read, I would not consider it a win.

Moving to Part 5

At this point the pieces are all on the table:

macros
helpers
save/load
HTTP

The last part is the simplest file, mod.rs, but it is also where I can finally say what this whole crate means to me.

My Tiny Rust Utils, Part 3: save_load.rs

icsboyx — Thu, 30 Apr 2026 16:07:25 +0000

Sooner or later, even a small bot needs to remember something.

In my case, that usually means token-like or config-like data.

I do not want to build a whole persistence subsystem for that, but I also do not want save/load code duplicated in random places.

That is where src/utils/save_load.rs comes from.

The basics

The file starts with a few exports and a format enum:

pub use anyhow::{Error, Result, bail};
pub use serde::{Deserialize, Serialize};
pub use serde_json;
pub use toml;

pub static CONFIG_BASE_DIR: &str = ".config";

#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum SaveType {
    JSON,
    YAML,
    #[default]
    TOML,
}

This is a very local design.
It is just trying to answer a smaller question:

"How does this project save and load structured data without repeating itself?"

For that, this is enough.

`ConfigManager`

The main trait is:

pub trait ConfigManager
where
    Self: Sized + Serialize + for<'de> Deserialize<'de>,
{
    fn save_custom(&self, file_path: PathBuf, dir_path: PathBuf, save_type: SaveType) -> Result<()> {
        let file_path = PathBuf::new()
            .join(dir_path)
            .join(file_path)
            .with_extension(save_type.as_str());
        save_file(&file_path, self, save_type)
    }

    fn load_custom(file_path: PathBuf, dir_path: PathBuf, save_type: SaveType) -> Result<Self> {
        let file_path = PathBuf::new()
            .join(dir_path)
            .join(file_path)
            .with_extension(save_type.as_str());
        load_file(&file_path)
    }

    fn save(&self) -> Result<()> {
        let struct_name = struct_name_from_type::<Self>()?;
        let file_path = PathBuf::new()
            .join(CONFIG_BASE_DIR)
            .join(struct_name)
            .with_extension(SaveType::default().as_str());
        save_file(&file_path, self, SaveType::default())
    }

    fn load() -> Result<Self> {
        let struct_name = struct_name_from_type::<Self>()?;
        let file_path = PathBuf::new()
            .join(CONFIG_BASE_DIR)
            .join(struct_name)
            .with_extension(SaveType::default().as_str());
        load_file(&file_path)
    }
}

What I like here is not sophistication.

It is that the feature code stays short.

In the token flow, I can simply do:

let mut tw_token = TwitchToken::load_or_default();
tw_token.save()?;

That feels about right for a project of this size.

The part that matters most to me

The most important part of this file is not the serialization format.

It is the path validation.

Here is the real function:

fn validate_path(file_path: &Path) -> anyhow::Result<PathBuf> {
    let mut normalized = PathBuf::new();

    for comp in file_path.components() {
        match comp {
            Component::Normal(part) => normalized.push(part),
            Component::CurDir => {}
            Component::Prefix(p) => {
                bail!("Config path should not contain prefix component: {:?}", p);
            }
            Component::RootDir => {
                bail!("Config path should not contain root component: /..",);
            }
            Component::ParentDir => {
                if !normalized.pop() {
                    bail!(
                        "Path traversal detected: config path should not contain parent directory component that goes beyond root dir",
                    )
                }
            }
        }
    }

    if normalized.as_os_str().is_empty() {
        anyhow::bail!("Empty config path");
    }

    Ok(normalized)
}

I trust code more when the rules are visible.

This function makes the rules visible:

no absolute paths
no prefix components
no climbing upward beyond the normalized relative path
no empty paths

That is the kind of small defensive behavior I like to centralize.

Not because it is glamorous, but because I do not want to rediscover the same problem later.

Why I prefer this over inline file code

Without a file like this, the same chores start leaking everywhere:

picking the file extension
creating directories
converting values into the chosen format
validating paths
building consistent error messages

I would rather make those choices once.

This file is basically me admitting that repetitive file IO glue is not something I want to keep solving in five different places.

Moving to Part 4

Once local persistence is under control, the next obvious pain point is external IO.

For this project, that means HTTP.

So the next part is web.rs.

My Tiny Rust Utils, Part 2: helpers.rs

icsboyx — Thu, 30 Apr 2026 16:02:35 +0000

After logging, the next kind of repetition that starts bothering me is usually this:

adding context to errors
converting typed values into JSON request bodies

Neither of those is dramatic on its own.

But if I leave them totally inline, they spread everywhere.

That is why src/utils/helpers.rs exists.

`WithLocation`

This is the first helper:

pub trait WithLocation<T> {
    fn with_location(self) -> anyhow::Result<T>;
    fn with_location_msg(self, msg: &str) -> anyhow::Result<T>;
}

impl<T, E> WithLocation<T> for std::result::Result<T, E>
where
    E: Into<anyhow::Error>,
{
    #[track_caller]
    fn with_location(self) -> anyhow::Result<T> {
        let loc = Location::caller();

        self.map_err(Into::into)
            .with_context(|| format!("{}:{}:{}", loc.file(), loc.line(), loc.column()))
    }

    #[track_caller]
    fn with_location_msg(self, msg: &str) -> anyhow::Result<T> {
        let loc = Location::caller();

        self.map_err(Into::into)
            .with_context(|| format!("{} at {}:{}:{}", msg, loc.file(), loc.line(), loc.column()))
    }
}

I like this because it captures something I personally care about when debugging:

not only what failed, but where I decided to wrap or reinterpret that failure.

That is often the more useful location for me.

Why I still keep it as a helper

Yes, I could just write .context(...) everywhere.

Sometimes I do.

But I know myself well enough: if the repetitive part feels slightly annoying, I will postpone it in one or two places, and then the code becomes uneven.

This helper lowers that friction just enough that I actually use it.

That is a recurring theme in this utils crate, honestly. I am not searching for elegance as much as I am trying to remove small excuses.

`IntoJsonValue`

The second helper is very small:

pub trait IntoJsonValue {
    fn json_value(self) -> serde_json::Result<Value>
    where
        Self: Sized + Serialize,
    {
        serde_json::to_value(self)
    }
}

impl<T> IntoJsonValue for T {}

This is almost embarrassingly tiny.

Still, I like it.

It lets me write:

Some(subscription_request.json_value()?)

instead of:

Some(serde_json::to_value(subscription_request)?)

That difference is not huge.

But I think a lot of utility code lives exactly in that zone: not essential, not magical, just a little nicer to use.

`TrackError`

The same file also has a very small custom error type:

#[derive(Debug)]
pub struct TrackError {
    pub location: &'static std::panic::Location<'static>,
    pub message: String,
}

impl TrackError {
    #[track_caller]
    pub fn new(message: impl Into<String>) -> Self {
        Self {
            location: std::panic::Location::caller(),
            message: message.into(),
        }
    }
}

I keep it around because sometimes I want something between:

a full error enum
and a generic error chain

Sometimes I just want a normal error value with a message and a caller location.

This gives me that, without pretending to be more important than it is.

Moving to Part 3

Once logs and helper traits are in place, the next problem is usually state.

Small apps still need to save things. Tokens, config-like values, maybe a bit of local persistence.

That is where save_load.rs comes in.

My Tiny Rust Utils, Part 1: macros.rs

icsboyx — Thu, 30 Apr 2026 16:01:19 +0000

I did not build this little utils crate because I thought I had something revolutionary to show.

I built it for a much simpler reason: while working on small Rust projects, I keep running into the same tiny frictions over and over again.

Nothing dramatic. Just the usual stuff:

logging that starts inconsistent
little helper code repeated in the wrong places
config or HTTP glue leaking into feature modules
small annoyances that are easy to ignore for a day and then annoying for a month

So this crate is mostly me trying to be a bit kinder to my future self.

I wanted one place for the small things that make the project easier to read, easier to debug, and a little less noisy.

And I wanted to share it for the exact same reason.

Not because these files are perfect, and not because I think anyone should copy them as-is, but because I always enjoy seeing how other people solve these very ordinary problems in their own projects.

Sometimes the most useful things to share are not big architectures or polished libraries.

Sometimes they are just small, honest utilities that made a project nicer to work on.

This is the crate I am talking about:

src/
└── utils/
    ├── helpers.rs
    ├── macros.rs
    ├── mod.rs
    ├── save_load.rs
    └── web.rs

So before getting into the rest of the series, I wanted to show the shape of it.

It is a small crate, but each file has its own job:

macros.rs for logs, timestamps, and source breadcrumbs
helpers.rs for small error and JSON helpers
save_load.rs for config-like persistence
web.rs for a thin HTTP layer
mod.rs as the glue that exposes the submodules

If I had to choose where this little series really starts, it would be macros.rs.

Not because macros are the most important thing in the world, and not because this file is especially smart.

It is just the first file that makes the rest of the project easier to live with.

When I am building a small bot or service, I usually want a few very basic things:

log lines that look consistent
timestamps without repeating formatting code everywhere
a cheap way to see where something happened

That is all src/utils/macros.rs is trying to do.

The real `log!` macro

Here is the actual code:

#[macro_export]
macro_rules! log {
    () => {{
        $crate::log!("");
    }};
    ($($arg:tt)*) => {{
        std::println!(
            "[ {} ] {} {}",
            $crate::timestamp!(millis),
            if cfg!(debug_assertions){crate::here!()} else {format!("[ {:<20} ]", module_path!())},
            format!($($arg)*)
        );
    }};
}

And the stderr version:

#[macro_export]
macro_rules! err_log {
    () => {{
        $crate::err_log!("");
    }};
    ($($arg:tt)*) => {{
        std::eprintln!(
            "[ {} ] {} {}",
            $crate::timestamp!(millis),
            if cfg!(debug_assertions){crate::here!()} else {format!("[ {:<20} ]", module_path!())},
            format!($($arg)*)
        );
    }};
}

This is not a grand logging system.

It is just a format I do not have to think about every time I want to print something.

That matters more than it sounds.

When the friction is low, I log more consistently. When I log more consistently, I understand the project better.

The small trick I still like

This part is probably my favorite:

if cfg!(debug_assertions){crate::here!()} else {format!("[ {:<20} ]", module_path!())}

In debug builds, I get source position.

In release builds, I get the module path instead.

That feels modest, but useful:

during development I want precise breadcrumbs
outside development I usually want something a bit cleaner

I do not need this to be perfect. I just need it to help.

`here!` is tiny, but honest

This is the real macro:

#[macro_export]
macro_rules! here {
    () => {
        format!(
            "[ {:<30} ]",
            format!("{}:{}:{}", file!(), line!(), column!())
        )
    };
    ($fmt:literal $(, $arg:expr)* $(,)?) => {
        format!(
            "[ {:<30} ] {}",
            format!("{}:{}:{}", file!(), line!(), column!()),
            format_args!($fmt $(, $arg)*)
        )
    };
}

I use it directly in places like this:

let session_id = msg.payload.session.as_ref().context(here!()).unwrap().id.as_str();

That line is not fancy at all. It is basically me saying:

"If this breaks, please show me exactly where I made this assumption."

I like helpers that are honest like that.

Timestamp helpers

The timestamp macro is also deliberately small:

#[macro_export]
macro_rules! timestamp {
    () => {{ chrono::Local::now().format("%Y-%m-%d %H:%M:%S").to_string() }};
    (milliseconds) => {{ chrono::Local::now().format("%Y-%m-%d %H:%M:%S%.3f").to_string() }};
    (millis) => {{ $crate::timestamp!(milliseconds) }};
    (micro) => {{ chrono::Local::now().format("%Y-%m-%d %H:%M:%S%.6f").to_string() }};
    (micros) => {{ $crate::timestamp!(micro) }};
    (nano) => {{ chrono::Local::now().format("%Y-%m-%d %H:%M:%S%.9f").to_string() }};
    (nanos) => {{ $crate::timestamp!(nano) }};
    ($fmt:literal) => {{ chrono::Local::now().format($fmt).to_string() }};
    ($unknown:tt) => {
        compile_error!(
            "unsupported timestamp! argument. Use: milliseconds|millis|micro|micros|nano|nanos|\"custom fmt\""
        );
    };
}

I am aware this is not revolutionary code.

That is kind of the point.

It saves me from repeating chrono formatting noise, and it keeps the call sites readable:

log!("Token will expire at: {:#?}", TW_TOKEN.expires_at().await);

For this project, that is enough justification.

What the output looks like

In debug builds, the output includes the exact source location:

[ 2026-04-30 12:15:44.381 ] [ src/tw_client.rs:94:36       ] Handling session welcome message, id abc123

In release builds, the same kind of line becomes a bit cleaner and shows the module path instead:

[ 2026-04-30 12:15:44.381 ] [ botox::tw_client     ] Handling session welcome message, id abc123

That difference is small, but it is intentional.

When I am debugging, I usually want the exact place.

When I am not, the module name is often enough.

It is not beautiful. It is not trying to be.

It is just useful in the exact way I need.

Moving to Part 2

Once I have logs and source breadcrumbs, the next annoyance is usually error context and JSON glue.

That is where helpers.rs starts to matter, so that is the next part.