DEV Community: Syeed Talha

How to Inject Hidden Runtime Context into AI Agent Tools (LangChain + LangGraph)

Syeed Talha — Fri, 22 May 2026 09:57:31 +0000

When you build a multi-tenant AI agent — one that serves multiple users across multiple companies — you face a tricky problem: how do you make sure each user only sees their own data?

You can't just let the LLM decide what data to fetch. You need to inject trusted, server-side context — like user_id and company_id — directly into the tool at runtime, completely hidden from the user's input.

That's exactly what this article is about. We'll build a document search agent that scopes results to the authenticated user's company, using LangChain's ToolRuntime and context_schema pattern.

The Problem: LLMs Can't Be Trusted With Authorization

Imagine a user types:

"Search documents about invoices"

A naive agent might pass this straight to a database query — but with what company ID? If the user can influence that, they might search another company's documents. That's a serious security hole.

The right approach: inject user_id and company_id from the backend (your auth system, session, JWT token, etc.) — never from the user's message.

What We're Building

A LangChain agent with a search_company_docs tool that:

Takes a plain search query from the user
Automatically receives user_id and company_id from a hidden runtime context
Only returns documents belonging to that company
Never exposes the context injection mechanism to the LLM or the user

Prerequisites

pip install langchain langgraph langchain-openai

Step 1: Define the Models

We use two models here — a lightweight one for the agent's reasoning loop, and a more capable one for complex tasks. With langchain's init_chat_model, you can initialize any supported model by name.

from langchain.chat_models import init_chat_model

# Fast, lightweight model for the agent loop
basic_model = init_chat_model("openai:gpt-4o-mini")

# More powerful model for complex reasoning (optional — swap as needed)
advance_model = init_chat_model("openai:gpt-4o")

In this example the agent uses basic_model. The advance_model is defined for cases where you want to escalate to heavier reasoning — e.g. for a second-pass summarization step.

Step 2: Set Up a Dummy Database

For this tutorial, we simulate a multi-tenant document store as a plain Python dict. Each key is a company_id, and its value is a list of document names.

COMPANY_DOCUMENTS = {
    "company_abc": [
        "Invoice system migration guide",
        "HR leave policy 2026",
        "AI roadmap document",
    ],
    "company_xyz": [
        "Financial audit report",
        "Marketing strategy Q2",
        "Sales onboarding manual",
    ],
}

In a real application this would be a database query filtered by company_id at the SQL/ORM level.

Step 3: Define the Runtime Context

This is the key piece. We define a Context dataclass that holds the values we want to inject into every tool call — server-side, not from user input.

from dataclasses import dataclass

@dataclass
class Context:
    user_id: str
    company_id: str

Think of this as your session payload — the kind of data you'd extract from a verified JWT token or a session cookie on every request. The user never touches this; your backend populates it.

Step 4: Build the Tool with `ToolRuntime`

Here's where the magic happens. Our tool accepts two parameters:

query — visible to the LLM, comes from the user's message
runtime: ToolRuntime[Context] — invisible to the LLM, injected by the framework at call time

from langchain.tools import ToolRuntime, tool

@tool
def search_company_docs(query: str, runtime: ToolRuntime[Context]) -> str:
    """
    Search company documents.
    """
    # These values come from the runtime context — not from the user
    user_id = runtime.context.user_id
    company_id = runtime.context.company_id

    print("\n===== RUNTIME INFO =====")
    print("User ID:", user_id)
    print("Company ID:", company_id)

    # Fetch only this company's documents
    docs = COMPANY_DOCUMENTS.get(company_id, [])

    # Simple keyword search
    matched_docs = [doc for doc in docs if query.lower() in doc.lower()]

    if matched_docs:
        return (
            f"User {user_id} searched company documents.\n"
            f"Matched documents:\n- " + "\n- ".join(matched_docs)
        )

    return f"No documents found for query: '{query}'"

What makes `ToolRuntime` special?

The runtime parameter is stripped from the tool's schema before it's sent to the LLM. The LLM only sees query: str in the tool definition. It cannot read, modify, or even know about user_id or company_id. The framework injects those values at execution time from the context you provide.

This is the correct, secure way to handle authorization in agentic systems.

Step 5: Create the Agent with `context_schema`

We wire everything together with create_agent, passing context_schema=Context so the agent knows what shape the runtime context will take.

from langchain.agents import create_agent
from langgraph.checkpoint.memory import InMemorySaver

agent = create_agent(
    model=basic_model,
    tools=[search_company_docs],
    context_schema=Context,       # <-- tells the agent about our runtime context
)

Step 6: Invoke with Hidden Context

When we call agent.invoke, we pass the user's message in messages (as usual) and the trusted server-side data in context (completely separate).

response = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": "Search documents about invoice",
            }
        ]
    },
    # This comes from your auth system — never from the user's input
    context=Context(
        user_id="user_123",
        company_id="company_abc",
    ),
)

print("\n===== FINAL RESPONSE =====")
print(response["messages"][-1].content)

The context argument is passed at the framework level, not as part of the LLM conversation. The model never sees it, and the user cannot tamper with it.

Full Code

from dataclasses import dataclass

from langchain.agents import create_agent
from langchain.chat_models import init_chat_model
from langchain.tools import ToolRuntime, tool
from langgraph.checkpoint.memory import InMemorySaver

# ── Models ─────────────────────────────────────────────────────────────────────
basic_model = init_chat_model("openai:gpt-4o-mini")
advance_model = init_chat_model("openai:gpt-4o")

# ── Dummy Database ─────────────────────────────────────────────────────────────
COMPANY_DOCUMENTS = {
    "company_abc": [
        "Invoice system migration guide",
        "HR leave policy 2026",
        "AI roadmap document",
    ],
    "company_xyz": [
        "Financial audit report",
        "Marketing strategy Q2",
        "Sales onboarding manual",
    ],
}

# ── Runtime Context ────────────────────────────────────────────────────────────
@dataclass
class Context:
    user_id: str
    company_id: str

# ── Tool ───────────────────────────────────────────────────────────────────────
@tool
def search_company_docs(query: str, runtime: ToolRuntime[Context]) -> str:
    """Search company documents."""
    user_id = runtime.context.user_id
    company_id = runtime.context.company_id

    print("\n===== RUNTIME INFO =====")
    print("User ID:", user_id)
    print("Company ID:", company_id)

    docs = COMPANY_DOCUMENTS.get(company_id, [])
    matched_docs = [doc for doc in docs if query.lower() in doc.lower()]

    if matched_docs:
        return (
            f"User {user_id} searched company documents.\n"
            f"Matched documents:\n- " + "\n- ".join(matched_docs)
        )
    return f"No documents found for query: '{query}'"

# ── Agent ──────────────────────────────────────────────────────────────────────
agent = create_agent(
    model=basic_model,
    tools=[search_company_docs],
    context_schema=Context,
)

# ── Invoke ─────────────────────────────────────────────────────────────────────
response = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": "Search documents about invoice",
            }
        ]
    },
    context=Context(
        user_id="user_123",
        company_id="company_abc",
    ),
)

print("\n===== FINAL RESPONSE =====")
print(response["messages"][-1].content)

Sample Output

===== RUNTIME INFO =====
User ID: user_123
Company ID: company_abc

===== FINAL RESPONSE =====
I found the following document related to "invoice" in your company's knowledge base:

- Invoice system migration guide

Let me know if you'd like more details about this document!

Notice that company_xyz's documents (Financial audit report, etc.) never appear — even though they exist in the database. The company scoping happens silently at the tool level.

Why This Architecture Matters

Concern	Naive Approach	Runtime Context Approach
Authorization	LLM decides what to fetch	Backend enforces it via context
Data isolation	Relies on prompt instructions	Enforced in code, not in prompts
Auditability	Hard to trace who fetched what	`user_id` is always available in the tool
Security surface	User input can influence data scope	Context is injected server-side only
Multi-tenancy	Fragile, prompt-based	Structurally enforced

The core insight: never trust the LLM for authorization. The LLM's job is to reason about what the user wants. Your backend's job is to enforce what the user is allowed to access. These are separate concerns and should live in separate layers.

Real-World Integration

In production, you'd populate Context from your auth middleware:

# FastAPI example
@app.post("/chat")
async def chat(request: ChatRequest, user=Depends(get_current_user)):
    response = agent.invoke(
        {"messages": [{"role": "user", "content": request.message}]},
        context=Context(
            user_id=user.id,
            company_id=user.company_id,   # from your auth system
        ),
    )
    return {"reply": response["messages"][-1].content}

The context is assembled from a verified token — never from the request body.

Wrapping Up

The ToolRuntime + context_schema pattern gives you a clean, secure way to inject trusted server-side data into your AI agent's tools — without leaking it to the LLM or exposing it to users.

This is one of those patterns that seems like a small detail but becomes critical the moment you build anything multi-tenant. Get it right from the start.

If this helped you, drop a ❤️ below. And if you're building multi-tenant agents and running into other challenges, let's talk in the comments!

How to Build a Human-in-the-Loop AI Agent with LangChain & LangGraph

Syeed Talha — Fri, 22 May 2026 08:43:16 +0000

AI agents are powerful — but sometimes too powerful. What if your agent is about to send an email on your behalf and you want a chance to say "wait, hold on"? That's exactly what Human-in-the-Loop (HITL) is for.

In this article, we'll build an AI agent that can send emails, but pauses and asks for your approval before actually doing it. If you approve, it goes through. If you reject, it doesn't. Simple, safe, and production-ready.

What We're Building

A LangChain agent powered by an LLM that:

Receives a user request like "Send an email to talha@gmail.com"
Decides to call the send_email tool
Pauses and waits for human approval
Sends the email (or drops it) based on your decision

Prerequisites

pip install langchain langgraph

You'll also need an LLM. In this article we'll use OpenAI's GPT-4o-mini via langchain-openai, but you can swap in any LangChain-compatible model.

pip install langchain-openai

Set your API key:

export OPENAI_API_KEY="your-key-here"

Step 1: Set Up the Model

from langchain_openai import ChatOpenAI

# You can swap this for any LangChain-compatible chat model
model = ChatOpenAI(model="gpt-4o-mini", temperature=0)

Using a different provider? LangChain supports Anthropic, Mistral, Groq, and many others. Just replace ChatOpenAI with the appropriate class and install its package (e.g. langchain-anthropic for Claude).

Step 2: Define the Tool

This is the action the agent will want to take. We keep it simple — just a function that prints the email details.

def send_email(email: str, message: str) -> str:
    """Send email"""

    print(f"\nEMAIL SENT TO: {email}")
    print(f"MESSAGE: {message}")

    return "Email sent successfully"

In a real app, you'd integrate this with SendGrid, SES, or your SMTP server.

Step 3: Create the Agent with Human-in-the-Loop Middleware

Here's where the magic happens. We use:

create_agent — builds the agent with tools attached
HumanInTheLoopMiddleware — tells the agent to pause before calling specific tools
InMemorySaver — a checkpointer that saves agent state so it can be resumed after the pause

import warnings

warnings.filterwarnings("ignore", category=UserWarning)
warnings.filterwarnings("ignore", category=DeprecationWarning)

from langchain.agents import create_agent
from langchain.agents.middleware import HumanInTheLoopMiddleware
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.types import Command

agent = create_agent(
    model=model,
    tools=[send_email],
    middleware=[HumanInTheLoopMiddleware(interrupt_on={"send_email": True})],
    checkpointer=InMemorySaver(),
)

The key line is interrupt_on={"send_email": True}. This tells the middleware: "Before you actually run send_email, freeze and hand control back to the human."

The InMemorySaver checkpointer is what makes resuming possible — it snapshots the agent's state at the interruption point so you can pick up exactly where you left off.

Step 4: First Invocation — Let the Agent Plan

We kick things off with the user's request. The agent will reason about what to do and reach the point of calling send_email — then stop.

config = {"configurable": {"thread_id": "test-thread"}}

response = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": "Send an email to talha@gmail.com with message 'hello world'",
            }
        ]
    },
    config=config,
)

print("\nAGENT PAUSED FOR APPROVAL\n")

The thread_id in config is how LangGraph tracks this specific conversation. Use the same thread ID when you resume so it picks up the right checkpoint.

Step 5: Ask the Human

Now we prompt the user in the terminal. This is the "human" part of human-in-the-loop.

decision = input("Approve email? (yes/no): ")

Step 6: Resume Based on the Decision

This is where Command(resume=...) comes in. We send the agent's paused state a signal telling it whether to proceed or abort.

If Approved

if decision.lower() == "yes":
    response = agent.invoke(
        Command(resume={"decisions": [{"type": "approve"}]}),
        config=config,
    )

    print("\nFINAL RESPONSE:")
    print(response["messages"][-1].content)

The agent resumes from the checkpoint, actually calls send_email, and continues to completion.

If Rejected

else:
    response = agent.invoke(
        Command(
            resume={
                "decisions": [{"type": "reject", "message": "Human rejected the email"}]
            }
        ),
        config=config,
    )

    print("\nEMAIL REJECTED")

The agent is told the action was rejected. It can use the rejection message to inform its final response (e.g., "The email was not sent as per your instruction.").

Full Code

Here's everything together:

import warnings

warnings.filterwarnings("ignore", category=UserWarning)
warnings.filterwarnings("ignore", category=DeprecationWarning)

from langchain.agents import create_agent
from langchain.agents.middleware import HumanInTheLoopMiddleware
from langchain_openai import ChatOpenAI
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.types import Command

# ── Model ──────────────────────────────────────────────────────────────────────
model = ChatOpenAI(model="gpt-4o-mini", temperature=0)


# ── Tool ───────────────────────────────────────────────────────────────────────
def send_email(email: str, message: str) -> str:
    """Send email"""
    print(f"\nEMAIL SENT TO: {email}")
    print(f"MESSAGE: {message}")
    return "Email sent successfully"


# ── Agent ──────────────────────────────────────────────────────────────────────
agent = create_agent(
    model=model,
    tools=[send_email],
    middleware=[HumanInTheLoopMiddleware(interrupt_on={"send_email": True})],
    checkpointer=InMemorySaver(),
)

config = {"configurable": {"thread_id": "test-thread"}}

# ── First call: agent plans and pauses ─────────────────────────────────────────
response = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": "Send an email to talha@gmail.com with message 'hello world'",
            }
        ]
    },
    config=config,
)

print("\nAGENT PAUSED FOR APPROVAL\n")

# ── Human decision ─────────────────────────────────────────────────────────────
decision = input("Approve email? (yes/no): ")

if decision.lower() == "yes":
    response = agent.invoke(
        Command(resume={"decisions": [{"type": "approve"}]}),
        config=config,
    )
    print("\nFINAL RESPONSE:")
    print(response["messages"][-1].content)

else:
    response = agent.invoke(
        Command(
            resume={
                "decisions": [{"type": "reject", "message": "Human rejected the email"}]
            }
        ),
        config=config,
    )
    print("\nEMAIL REJECTED")

Sample Output

When approved:

AGENT PAUSED FOR APPROVAL

Approve email? (yes/no): yes

EMAIL SENT TO: talha@gmail.com
MESSAGE: hello world

FINAL RESPONSE:
The email has been sent to talha@gmail.com with the message "hello world".

When rejected:

AGENT PAUSED FOR APPROVAL

Approve email? (yes/no): no

EMAIL REJECTED

Why This Pattern Matters

Human-in-the-loop isn't just a safety net — it's an architectural pattern for building trust between AI and users. Here's when you'd want it:

Use Case	Why HITL Helps
Sending emails / messages	Prevents accidental or hallucinated sends
Database writes	Confirms destructive operations
API calls with side effects	Gives humans a veto before real-world actions
Financial transactions	Compliance and audit requirements
Customer-facing responses	Quality control before publishing

Taking It Further

Async approval: Instead of a terminal input(), send an approval request to Slack, email, or a web dashboard.
Timeout handling: Auto-reject if no human responds within N minutes.
Audit logs: Persist every approval/rejection to a database for compliance.
Multiple tools: Pass multiple tool names to interrupt_on to gate any subset of your agent's capabilities.

Wrapping Up

LangGraph's checkpointing + LangChain's middleware make it surprisingly clean to add human oversight to any AI agent. The agent does the thinking; you keep the final say.

If you found this useful, drop a ❤️ and let me know what kinds of agents you're building in the comments!

Running Nvidia Nemotron on LangChain via OpenRouter

Syeed Talha — Wed, 20 May 2026 09:46:09 +0000

Nvidia's Nemotron models are powerful, free-to-use AI models available through OpenRouter. In this guide, you'll learn how to set up a LangChain agent that uses Nemotron — from installing packages to running your first tool-calling agent.

What Are We Building?

A simple LangChain agent that:

Uses Nvidia Nemotron as its brain (via OpenRouter's free tier)
Has access to a custom tool (a weather function)
Answers questions by calling that tool automatically

Prerequisites

Python 3.10 or higher
A free OpenRouter account and API key
uv (recommended) or pip

Step 1 — Get Your OpenRouter API Key

Go to openrouter.ai/settings/keys
Click Create Key
Copy the key — you'll need it shortly

OpenRouter gives you free access to many models, including Nvidia's Nemotron family, with no credit card required.

Step 2 — Set Up Your Project

Create a new project folder and initialize it:

mkdir my-nemotron-agent
cd my-nemotron-agent
uv init

Or if you're using pip, just create a folder and a virtual environment:

mkdir my-nemotron-agent
cd my-nemotron-agent
python -m venv .venv
.venv\Scripts\activate   # Windows
# source .venv/bin/activate  # Mac/Linux

Step 3 — Install Dependencies

uv add langchain langchain-openrouter python-dotenv

Or with pip:

pip install langchain langchain-openrouter python-dotenv

These three packages are all you need:

langchain — the agent framework
langchain-openrouter — connects LangChain to OpenRouter's API
python-dotenv — loads your API key from a .env file safely

Step 4 — Store Your API Key

Create a .env file in your project folder (never commit this to Git!):

OPENROUTER_API_KEY=your-key-here

Also create a .gitignore to protect it:

.env
.venv

Step 5 — Choose a Nemotron Model

OpenRouter hosts several free Nvidia Nemotron models. Here are the main ones:

Model	ID	Best For
Nemotron 3 Nano 30B	`nvidia/nemotron-3-nano-30b-a3b:free`	Fast, general tasks
Nemotron 3 Super 120B	`nvidia/nemotron-3-super-120b-a12b:free`	Complex reasoning
Nemotron Nano 9B V2	`nvidia/nemotron-nano-9b-v2:free`	Lightweight tasks

Note: The :free suffix is required. Without it, OpenRouter will look for a paid endpoint.

For beginners, nvidia/nemotron-3-nano-30b-a3b:free is a great starting point — it's fast and capable.

Step 6 — Write Your Agent

Create a file called main.py:

from dotenv import load_dotenv
from langchain.agents import create_agent

# Load the OPENROUTER_API_KEY from your .env file
load_dotenv()

# Define a tool — any plain Python function works!
def get_weather(city: str) -> str:
    """Get weather for a given city."""
    return f"It's always sunny in {city}!"

# Create the agent
agent = create_agent(
    model="openrouter:nvidia/nemotron-3-nano-30b-a3b:free",
    tools=[get_weather],
    system_prompt="You are a helpful assistant",
)

# Run the agent
result = agent.invoke(
    {"messages": [{"role": "user", "content": "What's the weather in San Francisco?"}]}
)

# Print the final response
print(result["messages"][-1].content)

How It Works

load_dotenv() reads your .env file and sets the OPENROUTER_API_KEY environment variable
get_weather is a regular Python function — LangChain uses its docstring to describe the tool to the model
create_agent wires everything together: the model, the tools, and the system prompt
agent.invoke(...) sends the user's message and returns a result dict
result["messages"][-1].content gets the final text response from the last message

Step 7 — Run It

uv run main.py

Or with pip/venv:

python main.py

You should see something like:

The weather in San Francisco is sunny!

Step 8 — Add More Tools

You can give your agent multiple tools — just add more functions to the list:

def get_weather(city: str) -> str:
    """Get the current weather for a city."""
    return f"It's always sunny in {city}!"

def get_population(city: str) -> str:
    """Get the population of a city."""
    populations = {
        "San Francisco": "870,000",
        "New York": "8,300,000",
        "Dhaka": "21,000,000",
    }
    return populations.get(city, "Population data not available.")

agent = create_agent(
    model="openrouter:nvidia/nemotron-3-nano-30b-a3b:free",
    tools=[get_weather, get_population],
    system_prompt="You are a helpful assistant",
)

The agent will automatically decide which tool to call based on the user's question.

Common Errors & Fixes

Error	Cause	Fix
`OPENROUTER_API_KEY must be set`	Missing API key	Add it to your `.env` file and call `load_dotenv()`
`is not a valid model ID`	Wrong model name	Use the exact ID from openrouter.ai/models, with `:free` suffix
`No endpoints found`	Model unavailable	Try a different Nemotron model ID
`cannot import name 'create_agent'`	Wrong Python / old langchain	Use `uv run` instead of `python`, or upgrade langchain

Project Structure

When you're done, your project should look like this:

my-nemotron-agent/
├── .env              ← Your API key (never share this!)
├── .gitignore        ← Excludes .env from Git
├── main.py           ← Your agent code
└── pyproject.toml    ← Dependencies (if using uv)

Next Steps

Once you're comfortable with the basics, here's what to explore next:

Real tools — connect to real APIs (weather, search, databases) instead of mock functions
Memory — give your agent conversation history so it remembers past messages
Streaming — stream the response token by token for a ChatGPT-like feel
LangSmith — trace and debug your agent's reasoning visually
Other free models — try deepseek/deepseek-r1:free or google/gemma-3-27b-it:free for comparison

Happy building!

Using Groq API with OpenAI Agents SDK

Syeed Talha — Mon, 18 May 2026 08:58:30 +0000

If you have tried using the OpenAI Agents SDK with Groq and ran into confusing import errors or decommissioned model warnings, you are not alone. This guide walks you through the correct setup from scratch, explains why the common mistakes happen, and leaves you with a working example you can build on.

What Is the OpenAI Agents SDK?

The OpenAI Agents SDK is an open-source Python framework for building agentic AI applications. It gives you clean abstractions for agents (an LLM with instructions and tools), handoffs between agents, guardrails, and built-in tracing. Despite the "OpenAI" name, the SDK is designed to work with any OpenAI-compatible API endpoint, which includes Groq.

What Is Groq?

Groq provides cloud-based LLM inference at very high speeds using their custom LPU hardware. Their API is largely compatible with the OpenAI API specification, which means you can point any OpenAI client at Groq's base URL and it will work with minimal changes.

Prerequisites

Before you start, make sure you have the following:

Python 3.10 or higher
A Groq API key (sign up at console.groq.com)
A virtual environment set up for your project

Installation

Install the required packages:

pip install openai-agents python-dotenv

The openai-agents package includes the openai package as a dependency, so you do not need to install it separately.

Project Structure

your-project/
├── .env
└── main.py

Create a .env file and add your Groq API key:

GROQ_API_KEY=your_groq_api_key_here
OPENAI_AGENTS_DISABLE_TRACING=1

The second line disables trace export to OpenAI's dashboard. Since you are not using an OpenAI API key, the SDK will otherwise print a warning every time you run your script. Setting this variable silences it cleanly.

The Wrong Way (and Why It Fails)

A common pattern beginners try is importing set_default_openai_client from the openai package:

# This will fail
from openai import OpenAI, set_default_openai_client

This throws an ImportError because set_default_openai_client does not exist in the openai package. It is a function from an older or incorrect reference that does not reflect the actual API of either library.

Another mistake is passing the model name as a plain string while using a custom client:

# This does not associate the model with your custom Groq client
agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant",
    model="llama-3.3-70b-versatile",  # SDK will try to use OpenAI, not Groq
)

When you pass a string, the SDK has no way of knowing you want to route requests to Groq. It will attempt to use the default OpenAI endpoint and fail if no OpenAI API key is set.

The Correct Approach

The right way is to use OpenAIChatCompletionsModel from the agents SDK. This class accepts an AsyncOpenAI client, which you configure to point at Groq's base URL. You then pass the model object directly to the Agent.

Here is the complete working example:

import os
from dotenv import load_dotenv
from openai import AsyncOpenAI
from agents import Agent, Runner
from agents.models.openai_chatcompletions import OpenAIChatCompletionsModel

load_dotenv()

# Step 1: Create an async OpenAI client pointed at Groq
groq_client = AsyncOpenAI(
    api_key=os.environ.get("GROQ_API_KEY"),
    base_url="https://api.groq.com/openai/v1"
)

# Step 2: Wrap it in OpenAIChatCompletionsModel
groq_model = OpenAIChatCompletionsModel(
    model="llama-3.3-70b-versatile",
    openai_client=groq_client
)

# Step 3: Pass the model object to the Agent
agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant",
    model=groq_model,
)

# Step 4: Run it
result = Runner.run_sync(agent, "Write a haiku about recursion in programming.")
print(result.final_output)

Why AsyncOpenAI and Not OpenAI?

The OpenAI Agents SDK is built on top of Python's asyncio and makes asynchronous HTTP calls internally. The synchronous OpenAI client is not compatible with this. Always use AsyncOpenAI when building the client for the agents SDK, even if you are calling Runner.run_sync(). The sync wrapper handles the event loop externally; the internal model calls are still async.

Choosing the Right Groq Model

Groq periodically deprecates older model IDs. If you see an error like this:

openai.BadRequestError: Error code: 400 - {'error': {'message': 'The model `llama3-70b-8192` 
has been decommissioned...'}}

You are using a model ID that Groq no longer supports. Here are the current recommended replacements as of mid-2025:

Deprecated Model	Recommended Replacement
`llama3-70b-8192`	`llama-3.3-70b-versatile`
`llama3-8b-8192`	`llama-3.1-8b-instant`
`mixtral-8x7b-32768`	`qwen/qwen3-32b`

Always check console.groq.com/docs/models for the current list of supported models.

Running the Script

python main.py

Expected output:

Code within the code,
Functions calling themselves deep,
Infinite loop's dance.

Key Takeaways

Do not import set_default_openai_client from openai. It does not exist there.
Always use AsyncOpenAI, not OpenAI, when building a client for the agents SDK.
Pass a OpenAIChatCompletionsModel object to Agent, not a plain model name string, when using a custom provider like Groq.
Set OPENAI_AGENTS_DISABLE_TRACING=1 in your .env to suppress the tracing warning when not using OpenAI.
Check Groq's deprecation page if you get a model_decommissioned error and update your model ID accordingly.

What to Build Next

Once you have the basic setup working, you can explore:

Adding tools to your agent using the @function_tool decorator
Creating multi-agent workflows with handoffs
Using Groq's faster, lighter models like llama-3.1-8b-instant for lower-latency tasks

The OpenAI Agents SDK documentation is available at openai.github.io/openai-agents-python and Groq's API reference at console.groq.com/docs.

Multithreading in Rust (Beginner Guide )

Syeed Talha — Mon, 11 May 2026 17:51:58 +0000

When beginners first hear the word “multithreading”, it often sounds scary and complicated.

But the core idea is actually very simple.

In this article, we will learn:

What multithreading is
Why we need it
How workers and queues work
A very easy Rust example
How jobs are processed in parallel

No advanced Rust knowledge required.

What is Multithreading?

Imagine you own a pizza shop.

If only one worker cooks all pizzas:

Order 1 → Wait
Order 2 → Wait
Order 3 → Wait

Everything happens one by one.

This is similar to a single-threaded program.

Now imagine you hire 3 workers.

Worker 1
Worker 2
Worker 3

Now multiple pizzas can be prepared at the same time.

This is multithreading.

Real-Life Programming Example

Suppose your application needs to process:

100 PDF pages
500 images
thousands of files

Doing everything one by one can be slow.

Instead, multiple workers can process jobs simultaneously.

Important Terms

Before seeing code, let’s understand some important terms.

Term	Meaning
Thread	A separate execution path
Worker	A thread that performs jobs
Queue	A waiting line for jobs
Job	A task to process
Parallel Processing	Multiple tasks running together

The Basic Idea

The workflow looks like this:

Main Thread
     |
     | sends jobs
     v

+------------+
| Job Queue  |
+------------+
   /   |   \
  /    |    \

W1    W2    W3

The main thread creates jobs.

Workers continuously take jobs from the queue.

Our Beginner Example

We will build:

A job queue
3 worker threads
Workers processing jobs

Full Code Example

use std::sync::{mpsc, Arc, Mutex};
use std::thread;
use std::time::Duration;

fn main() {

    // Create queue
    let (sender, receiver) = mpsc::channel();

    // Share receiver between workers
    let receiver = Arc::new(Mutex::new(receiver));

    // Create 3 worker threads
    for worker_id in 1..=3 {

        let receiver = Arc::clone(&receiver);

        thread::spawn(move || {

            loop {

                // Take a job from queue
                let job = {
                    let receiver = receiver.lock().unwrap();
                    receiver.recv()
                };

                match job {

                    Ok(number) => {

                        println!(
                            "Worker {} got job {}",
                            worker_id,
                            number
                        );

                        // Simulate work
                        thread::sleep(Duration::from_secs(2));

                        println!(
                            "Worker {} finished job {}",
                            worker_id,
                            number
                        );
                    }

                    Err(_) => {

                        println!(
                            "Worker {} stopping",
                            worker_id
                        );

                        break;
                    }
                }
            }
        });
    }

    // Send jobs into queue
    for job in 1..=10 {

        println!("Main thread sending job {}", job);

        sender.send(job).unwrap();

        thread::sleep(Duration::from_millis(500));
    }

    // Close sender
    drop(sender);

    // Wait for workers
    thread::sleep(Duration::from_secs(10));
}

Step-by-Step Explanation

1. Creating the Queue

let (sender, receiver) = mpsc::channel();

This creates a communication channel.

Think of it like a job table.

sender puts jobs into the table
receiver takes jobs from the table

2. Sharing the Queue

let receiver = Arc::new(Mutex::new(receiver));

Why do we need this?

Because multiple workers will access the same queue.

`Arc`

Arc allows multiple threads to share ownership safely.

`Mutex`

Mutex ensures:

Only one worker accesses the queue at a time.

Without it, workers could conflict with each other.

3. Creating Workers

for worker_id in 1..=3

This creates:

Worker 1
Worker 2
Worker 3

Each worker runs in a separate thread.

4. Waiting for Jobs

receiver.recv()

This means:

Wait until a job arrives.

Workers continuously wait for new jobs.

5. Sending Jobs

sender.send(job).unwrap();

The main thread sends jobs into the queue.

Example:

Job 1
Job 2
Job 3

6. Workers Process Jobs

Possible output:

Main thread sending job 1
Worker 1 got job 1

Main thread sending job 2
Worker 2 got job 2

Main thread sending job 3
Worker 3 got job 3

Now all workers process tasks simultaneously.

7. Simulating Work

thread::sleep(Duration::from_secs(2));

This simulates heavy processing.

In real applications this could be:

image processing
AI inference
file conversion
database work

8. Closing the Queue

drop(sender);

This means:

No more jobs are coming.

Workers automatically stop.

Example Visualization

Imagine this queue:

[1][2][3][4][5]

Workers take jobs like this:

Worker 1 → Job 1
Worker 2 → Job 2
Worker 3 → Job 3

When a worker finishes:

Worker 1 → Job 4

Free workers immediately take the next available job.

Why Is This Faster?

Suppose each job takes:

2 seconds

If one worker processes 10 jobs:

10 × 2 = 20 seconds

With 3 workers:

Much faster because work is shared.

Real Applications of Multithreading

Multithreading is used everywhere.

Examples:

Web servers
AI systems
PDF processing
Video rendering
Game engines
File explorers
Compilers

Important Beginner Note

Rust is famous for thread safety.

Many languages allow dangerous threading bugs.

Rust prevents many problems during compilation.

That is why Rust uses tools like:

Arc
Mutex
channels

to ensure safe concurrency.

What You Should Learn Next

After understanding this article, learn these topics next:

Ownership in threads
move keyword
Arc
Mutex
RwLock
Channels (mpsc)
Thread pools
Async programming with Tokio

Final Summary

Multithreading allows multiple tasks to run simultaneously.

In our example:

Main thread creates jobs
Jobs go into a queue
Workers continuously take jobs
Workers process jobs in parallel

The core architecture looks like this:

Main Thread
      ↓
  Job Queue
   ↓ ↓ ↓
Workers

This simple pattern is one of the most important concepts in modern systems programming.

CRUD API in Rust Using Axum, SQLite, and sqlx

Syeed Talha — Sun, 03 May 2026 16:31:23 +0000

In this article, we will build a beginner-friendly CRUD API using Rust, Axum, SQLite, and sqlx.

We will build a simple users API where we can:

Create a user
Get all users
Get one user by ID
Update a user
Delete a user

This article uses a clean project structure instead of putting everything inside main.rs.

What We Are Using

We will use:

axum for building the web API
tokio for async runtime
sqlx for async database queries
sqlite as the database
serde for JSON serialization and deserialization

SQLite is a good database for learning because it does not need a separate database server. It stores data inside a local file.

Project Structure

Create a new Rust project:

cargo new axum_sqlite_crud
cd axum_sqlite_crud

Our final project structure will look like this:

axum_sqlite_crud/
├── Cargo.toml
└── src/
    ├── main.rs
    ├── db.rs
    ├── state.rs
    ├── models.rs
    └── handlers.rs

Here is what each file will do:

main.rs      -> starts the server and connects routes
db.rs        -> database connection and table creation
state.rs     -> shared application state
models.rs    -> request and response structs
handlers.rs  -> CRUD handler functions

Step 1: Add Dependencies

Open Cargo.toml and add:

[dependencies]
axum = "0.8"
tokio = { version = "1", features = ["full"] }

sqlx = {
    version = "0.8",
    features = [
        "sqlite",
        "runtime-tokio-rustls"
    ]
}

serde = { version = "1", features = ["derive"] }

Step 2: Create `state.rs`

Create this file:

src/state.rs

Add this code:

use sqlx::SqlitePool;

#[derive(Clone)]
pub struct AppState {
    pub db: SqlitePool,
}

Explanation

AppState is used to share application data across routes.

In our case, we want every handler to access the SQLite database connection pool.

The SqlitePool is a database connection pool. Instead of creating a new database connection for every request, the pool manages and reuses connections.

Step 3: Create `models.rs`

Create this file:

src/models.rs

Add this code:

use serde::{Deserialize, Serialize};
use sqlx::FromRow;

#[derive(Debug, Serialize, FromRow)]
pub struct User {
    pub id: i64,
    pub name: String,
    pub email: String,
}

#[derive(Debug, Deserialize)]
pub struct CreateUser {
    pub name: String,
    pub email: String,
}

#[derive(Debug, Deserialize)]
pub struct UpdateUser {
    pub name: String,
    pub email: String,
}

Explanation

We created three structs.

User represents the data we return from the database.

pub struct User {
    pub id: i64,
    pub name: String,
    pub email: String,
}

CreateUser represents the JSON body when creating a new user.

pub struct CreateUser {
    pub name: String,
    pub email: String,
}

UpdateUser represents the JSON body when updating an existing user.

pub struct UpdateUser {
    pub name: String,
    pub email: String,
}

Why `Serialize`?

Serialize allows Rust structs to be converted into JSON responses.

Why `Deserialize`?

Deserialize allows JSON request bodies to be converted into Rust structs.

Why `FromRow`?

FromRow allows sqlx to convert database rows into our User struct.

Step 4: Create `db.rs`

Create this file:

src/db.rs

Add this code:

use sqlx::sqlite::{SqliteConnectOptions, SqlitePoolOptions};
use sqlx::SqlitePool;
use std::str::FromStr;

pub async fn init_db() -> SqlitePool {
    let options = SqliteConnectOptions::from_str("sqlite:test.db")
        .unwrap()
        .create_if_missing(true);

    SqlitePoolOptions::new()
        .max_connections(5)
        .connect_with(options)
        .await
        .unwrap()
}

pub async fn create_table(pool: &SqlitePool) {
    sqlx::query(
        "CREATE TABLE IF NOT EXISTS users (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            name TEXT NOT NULL,
            email TEXT NOT NULL
        )",
    )
    .execute(pool)
    .await
    .unwrap();
}

Explanation

This file handles database setup.

SqliteConnectOptions::from_str("sqlite:test.db")

This tells SQLite to use a database file named:

test.db

If the file does not exist, this line creates it:

.create_if_missing(true)

Without this, you may get an error like:

unable to open database file

Then we create a connection pool:

SqlitePoolOptions::new()
    .max_connections(5)

This means the pool can manage up to 5 database connections.

Then we create a table:

CREATE TABLE IF NOT EXISTS users (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT NOT NULL,
    email TEXT NOT NULL
)

IF NOT EXISTS is important because the table creation code runs every time the app starts. If the table already exists, SQLite will not create it again.

Step 5: Create `handlers.rs`

Create this file:

src/handlers.rs

Add this code:

use axum::{
    extract::{Path, State},
    http::StatusCode,
    Json,
};

use crate::{
    models::{CreateUser, UpdateUser, User},
    state::AppState,
};

pub async fn create_user(
    State(state): State<AppState>,
    Json(payload): Json<CreateUser>,
) -> (StatusCode, Json<User>) {
    let user = sqlx::query_as::<_, User>(
        "INSERT INTO users (name, email)
         VALUES (?, ?)
         RETURNING id, name, email",
    )
    .bind(payload.name)
    .bind(payload.email)
    .fetch_one(&state.db)
    .await
    .unwrap();

    (StatusCode::CREATED, Json(user))
}

pub async fn get_users(
    State(state): State<AppState>,
) -> Json<Vec<User>> {
    let users = sqlx::query_as::<_, User>(
        "SELECT id, name, email FROM users",
    )
    .fetch_all(&state.db)
    .await
    .unwrap();

    Json(users)
}

pub async fn get_user_by_id(
    Path(id): Path<i64>,
    State(state): State<AppState>,
) -> Result<Json<User>, StatusCode> {
    let user = sqlx::query_as::<_, User>(
        "SELECT id, name, email FROM users WHERE id = ?",
    )
    .bind(id)
    .fetch_optional(&state.db)
    .await
    .unwrap();

    match user {
        Some(user) => Ok(Json(user)),
        None => Err(StatusCode::NOT_FOUND),
    }
}

pub async fn update_user(
    Path(id): Path<i64>,
    State(state): State<AppState>,
    Json(payload): Json<UpdateUser>,
) -> Result<Json<User>, StatusCode> {
    let user = sqlx::query_as::<_, User>(
        "UPDATE users
         SET name = ?, email = ?
         WHERE id = ?
         RETURNING id, name, email",
    )
    .bind(payload.name)
    .bind(payload.email)
    .bind(id)
    .fetch_optional(&state.db)
    .await
    .unwrap();

    match user {
        Some(user) => Ok(Json(user)),
        None => Err(StatusCode::NOT_FOUND),
    }
}

pub async fn delete_user(
    Path(id): Path<i64>,
    State(state): State<AppState>,
) -> StatusCode {
    let result = sqlx::query(
        "DELETE FROM users WHERE id = ?",
    )
    .bind(id)
    .execute(&state.db)
    .await
    .unwrap();

    if result.rows_affected() == 0 {
        StatusCode::NOT_FOUND
    } else {
        StatusCode::NO_CONTENT
    }
}

Understanding the Handlers

Now let’s understand the important parts.

`State(state): State<AppState>`

This gives the handler access to shared application state.

Because our AppState contains the database pool, every handler can use:

state.db

to run database queries.

`Json(payload): Json<CreateUser>`

This extracts JSON from the request body.

For example, if the client sends:

{
  "name": "Talha",
  "email": "talha@example.com"
}

Axum converts it into:

CreateUser {
    name: "Talha".to_string(),
    email: "talha@example.com".to_string(),
}

`Path(id): Path<i64>`

This extracts the ID from the URL.

For example:

GET /users/1

Axum takes 1 from the URL and gives it to the handler as:

id = 1

In Axum 0.8, path parameters use curly braces in routes:

"/users/{id}"

not:

"/users/:id"

`.bind()`

This is very important.

Instead of writing SQL like this:

format!("SELECT * FROM users WHERE id = {}", id)

we write:

sqlx::query("SELECT * FROM users WHERE id = ?")
    .bind(id)

This is safer because it helps prevent SQL injection.

`fetch_one`

This is used when we expect one row.

Example:

.fetch_one(&state.db)

We use it after inserting a user because we return the newly created user.

`fetch_all`

This is used when we expect many rows.

Example:

.fetch_all(&state.db)

We use it when getting all users.

`fetch_optional`

This is used when the data may or may not exist.

Example:

.fetch_optional(&state.db)

If the user exists, it returns:

Some(user)

If the user does not exist, it returns:

None

That is why we can return 404 NOT FOUND.

`.execute()`

No rows (INSERT/UPDATE without RETURNING or Delete)
Example:

.execute(&state.db)

Step 6: Create `main.rs`

Now open:

src/main.rs

Replace everything with:

mod db;
mod handlers;
mod models;
mod state;

use axum::{
    routing::{get, post},
    Router,
};

use db::{create_table, init_db};
use handlers::{
    create_user,
    delete_user,
    get_user_by_id,
    get_users,
    update_user,
};
use state::AppState;

#[tokio::main]
async fn main() {
    let pool = init_db().await;

    create_table(&pool).await;

    let state = AppState { db: pool };

    let app = Router::new()
        .route("/users", post(create_user).get(get_users))
        .route(
            "/users/{id}",
            get(get_user_by_id)
                .put(update_user)
                .delete(delete_user),
        )
        .with_state(state);

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000")
        .await
        .unwrap();

    println!("Server running on http://localhost:3000");

    axum::serve(listener, app).await.unwrap();
}

Understanding `main.rs`

These lines import our other files:

mod db;
mod handlers;
mod models;
mod state;

This means Rust can use code from:

db.rs
handlers.rs
models.rs
state.rs

Then we initialize the database:

let pool = init_db().await;

Then we create the table:

create_table(&pool).await;

Then we create shared state:

let state = AppState { db: pool };

Then we define routes:

.route("/users", post(create_user).get(get_users))

This means:

POST /users -> create user
GET  /users -> get all users

Then:

.route(
    "/users/{id}",
    get(get_user_by_id)
        .put(update_user)
        .delete(delete_user),
)

This means:

GET    /users/{id} -> get one user
PUT    /users/{id} -> update one user
DELETE /users/{id} -> delete one user

Finally, we attach the shared state:

.with_state(state)

Now all handlers can access the database pool.

Step 7: Run the Server

Run:

cargo run

You should see:

Server running on http://localhost:3000

Also, after running the app, you should see a new file in your project:

test.db

That is your SQLite database file.

Step 8: Test the API

You can test using Postman, Thunder Client, or curl.

Create User

Request:

POST http://localhost:3000/users

Body:

{
  "name": "Talha",
  "email": "talha@example.com"
}

curl:

curl -X POST http://localhost:3000/users \
  -H "Content-Type: application/json" \
  -d '{"name":"Talha","email":"talha@example.com"}'

On Windows CMD, use:

curl -X POST http://localhost:3000/users ^
  -H "Content-Type: application/json" ^
  -d "{\"name\":\"Talha\",\"email\":\"talha@example.com\"}"

Expected response:

{
  "id": 1,
  "name": "Talha",
  "email": "talha@example.com"
}

Get All Users

Request:

GET http://localhost:3000/users

curl:

curl http://localhost:3000/users

Expected response:

[
  {
    "id": 1,
    "name": "Talha",
    "email": "talha@example.com"
  }
]

Get One User

Request:

GET http://localhost:3000/users/1

curl:

curl http://localhost:3000/users/1

Expected response:

{
  "id": 1,
  "name": "Talha",
  "email": "talha@example.com"
}

If the user does not exist, the API returns:

404 NOT FOUND

Update User

Request:

PUT http://localhost:3000/users/1

Body:

{
  "name": "Updated Talha",
  "email": "updated@example.com"
}

curl:

curl -X PUT http://localhost:3000/users/1 \
  -H "Content-Type: application/json" \
  -d '{"name":"Updated Talha","email":"updated@example.com"}'

Windows CMD:

curl -X PUT http://localhost:3000/users/1 ^
  -H "Content-Type: application/json" ^
  -d "{\"name\":\"Updated Talha\",\"email\":\"updated@example.com\"}"

Expected response:

{
  "id": 1,
  "name": "Updated Talha",
  "email": "updated@example.com"
}

Delete User

Request:

DELETE http://localhost:3000/users/1

curl:

curl -X DELETE http://localhost:3000/users/1

If deleted successfully, the API returns:

204 NO CONTENT

If the user does not exist, the API returns:

404 NOT FOUND

Why We Did Not Put Everything in `main.rs`

For very small examples, putting all code in main.rs is okay.

But as your project grows, main.rs becomes hard to read.

This structure is better:

main.rs      -> application startup
db.rs        -> database setup
state.rs     -> shared state
models.rs    -> data types
handlers.rs  -> request handlers

This makes the project easier to understand, maintain, and extend.

Current Limitations

This project is beginner-friendly, but it is not fully production-ready yet.

For production, we should improve:

Error handling instead of using .unwrap()
Database migrations instead of creating tables in code
Validation for user input
Separate service/repository layers for larger apps
Environment variables for database URL

But this version is a strong starting point.

Final Thoughts

In this article, we built a CRUD API using Axum, SQLite, and sqlx.

We learned:

How to connect Axum with SQLite
How to use a database connection pool
How to share database access using state
How to create clean file structure
How to write Create, Read, Update, and Delete handlers
How to test the API using curl or Postman

SQLite is a great choice when you are learning database integration because it is simple, local, and does not require a separate database server.

Once you understand this, switching to PostgreSQL later will be much easier because sqlx supports both SQLite and PostgreSQL.

Sharing Data in Axum State, Arc, Mutex & RwLock

Syeed Talha — Sun, 03 May 2026 11:04:05 +0000

If you're building web APIs in Rust with Axum, you'll quickly hit a very relatable question:

"How do I share a database connection, a config value, or an in-memory cache across my route handlers?"

The answer involves four tools working together: State<T>, Arc<T>, Mutex<T>, and RwLock<T>. Each one does a specific job. By the end of this article, you'll understand what each one is for, when to use which, and how to combine them confidently in Axum 0.8.

Let's go step by step. 🦀

The Problem: Handlers Don't Share Memory by Default

In Axum, each request is handled by an async function. These handlers are independent — they don't automatically have access to shared resources like:

A database connection pool
An API key loaded from environment variables
An in-memory counter or key-value store

You need a way to inject shared data into your handlers safely — especially when multiple requests run concurrently on different threads.

Tool #1 — `Arc<T>`: Shared Ownership Across Threads

Arc stands for Atomically Reference Counted. It lives in Rust's standard library (std::sync::Arc).

Rust's ownership system normally allows only one owner per value. But in a web server, multiple request handlers run at the same time and all need to read the same data. Arc<T> solves this by letting you have multiple owners of the same data. Internally it keeps a count of how many owners exist, and when the last one is dropped, the data is cleaned up.

use std::sync::Arc;

let config = Arc::new(AppConfig {
    db_url: "postgres://localhost/mydb".to_string(),
});

// Both config and config_clone point to the same allocation — no data is copied
let config_clone = Arc::clone(&config);

💡 Arc::clone() is cheap — it just increments the reference count. The actual data is never duplicated.

When is plain Arc<T> enough?
When your data is read-only — like app configuration or feature flags loaded at startup. No mutations means no synchronization needed beyond Arc.

Tool #2 — `State<T>`: Axum's Dependency Injection

State<T> is Axum's built-in extractor for shared application state. An extractor is just something you put in a handler's function signature, and Axum automatically provides it.

use axum::extract::State;

async fn hello_handler(State(config): State<Arc<AppConfig>>) -> String {
    format!("Connected to: {}", config.db_url)
}

You attach your state to the router using .with_state(), and from then on any handler can request it via State<T>:

let app = Router::new()
    .route("/hello", get(hello_handler))
    .with_state(Arc::new(config)); // 👈 attach once, available everywhere

⚠️ Order matters! State must come before body extractors like Json in your handler's parameter list.

Tool #3 — `Mutex<T>`: Exclusive Access for Writes

What if you need to mutate your shared data? Reading and writing at the same time from multiple threads is a data race — and Rust won't let you do it without synchronization.

Mutex<T> (Mutual Exclusion) is the classic solution. It acts as a lock — only one thread can hold it at a time:

use std::sync::{Arc, Mutex};

let counter = Arc::new(Mutex::new(0u64));

// To read or write, you lock() first
let mut val = counter.lock().unwrap();
*val += 1;
// lock is automatically released when `val` is dropped

In an Axum handler:

async fn increment(State(state): State<Arc<AppState>>) -> String {
    let mut count = state.counter.lock().unwrap();
    *count += 1;
    format!("Count is now: {}", *count)
}

The key rule with std::sync::Mutex:

❌ Never hold a std::sync::Mutex lock across an .await point!

// BAD — other tasks can't proceed while this one awaits
let data = state.items.lock().unwrap();
some_async_function().await; // 🔴 still holding the lock!

If you genuinely need to hold a lock across an .await, use tokio::sync::Mutex instead (more on this below).

Tool #4 — `RwLock<T>`: Many Readers, One Writer

Mutex<T> is simple but strict — even reading blocks all other threads. For workloads that are read-heavy, this is wasteful.

Enter RwLock<T> (Read-Write Lock). It has two modes:

Read lock (.read()) — Many threads can hold this simultaneously
Write lock (.write()) — Only one thread can hold this, and it blocks all readers

use std::sync::{Arc, RwLock};

let store = Arc::new(RwLock::new(vec!["hello".to_string()]));

// Multiple readers at the same time — fine!
let data = store.read().unwrap();
println!("{:?}", *data);

// One writer at a time — blocks until all readers are done
let mut data = store.write().unwrap();
data.push("world".to_string());

In an Axum handler:

async fn get_items(State(state): State<Arc<AppState>>) -> String {
    let items = state.store.read().unwrap(); // 🔒 shared read lock
    items.join(", ")
}

async fn add_item(State(state): State<Arc<AppState>>) -> String {
    let mut items = state.store.write().unwrap(); // 🔒 exclusive write lock
    items.push("new item".to_string());
    format!("Total: {}", items.len())
}

💡 Use RwLock when your data is read far more often than it's written. A good rule of thumb: if 80%+ of accesses are reads, RwLock wins.

`std::sync` vs `tokio::sync` — Which Should You Use?

This trips up a lot of beginners. Here's the quick answer:

	`std::sync::Mutex` / `RwLock`	`tokio::sync::Mutex` / `RwLock`
Holding across `.await`	❌ Will panic / cause `!Send` errors	✅ Safe
Performance	✅ Faster (OS-level)	Slightly more overhead
When to use	Lock is held briefly, no `.await` inside	You must hold the lock across async calls

The practical advice: Start with std::sync::Mutex. Only reach for tokio::sync::Mutex if you need to hold the lock while awaiting something.

// std::sync version — fine as long as you drop the lock before .await
{
    let mut data = state.cache.lock().unwrap();
    data.insert("key", "value"); // quick operation
} // lock dropped here ✅
some_async_call().await;

// tokio::sync version — needed if you must hold the lock across await
use tokio::sync::Mutex;
let mut data = state.cache.lock().await; // async lock acquisition
do_something_async().await; // safe to hold the lock here

Choosing the Right Tool

Here's a simple decision tree:

Is your data read-only after startup?
  └── YES → Arc<T>  (no lock needed)
  └── NO (you need to mutate it)
        ├── Reads and writes happen equally?
        │     └── Arc<Mutex<T>>
        └── Reads are much more frequent than writes?
              └── Arc<RwLock<T>>

Do you need to hold the lock across .await points?
  └── YES → tokio::sync::Mutex / tokio::sync::RwLock
  └── NO  → std::sync::Mutex / std::sync::RwLock (preferred)

A Complete Working Example

Let's build a small in-memory key-value store that demonstrates all four tools together.

`Cargo.toml`

[dependencies]
axum = "0.8.9"
tokio = { version = "1", features = ["full"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"

`main.rs`

use axum::{
    extract::{Path, State},
    routing::{get, post},
    Json, Router,
};
use std::{
    collections::HashMap,
    sync::{Arc, RwLock},
};

// Our shared application state
struct AppState {
    // RwLock because reads (GET) will far outnumber writes (POST)
    store: RwLock<HashMap<String, String>>,
}

#[tokio::main]
async fn main() {
    let shared_state = Arc::new(AppState {
        store: RwLock::new(HashMap::new()),
    });

    let app = Router::new()
        .route("/store/{key}", get(get_value))
        .route("/store", post(set_value))
        .with_state(shared_state);

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    println!("🚀 Listening on http://localhost:3000");
    axum::serve(listener, app).await.unwrap();
}

// GET /store/:key — many of these can run concurrently
async fn get_value(
    Path(key): Path<String>,
    State(state): State<Arc<AppState>>,
) -> String {
    let store = state.store.read().unwrap(); // shared read lock
    match store.get(&key) {
        Some(val) => val.clone(),
        None => format!("Key '{}' not found", key),
    }
} // read lock released here

// POST /store — exclusive write, blocks readers only for an instant
async fn set_value(
    State(state): State<Arc<AppState>>,
    Json(payload): Json<HashMap<String, String>>,
) -> String {
    let mut store = state.store.write().unwrap(); // exclusive write lock
    let count = payload.len();
    for (k, v) in payload {
        store.insert(k, v);
    }
    format!("Inserted {} key(s). Total keys: {}", count, store.len())
} // write lock released here

Try it out:

# Set some values
curl -X POST http://localhost:3000/store \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice", "lang": "Rust"}'

# Read them back (concurrent reads are safe!)
curl http://localhost:3000/store/name
curl http://localhost:3000/store/lang

Common Gotchas

❌ Forgetting `.with_state()`

If you use State<T> in a handler but forget to call .with_state() on the router, Axum will panic at startup with a clear error message. Always pair them.

❌ Using `Rc<T>` instead of `Arc<T>`

Rc<T> is single-threaded reference counting. Axum requires Send + Sync because handlers run across threads. Use Arc<T> always.

❌ Holding `std::sync::Mutex` across `.await`

// ❌ This will either panic or cause a compile error
let lock = state.data.lock().unwrap();
some_async_fn().await; // still holding the lock!

Drop the lock before any .await, or switch to tokio::sync::Mutex.

❌ `RwLock` write starvation

If write requests pile up, RwLock can starve. For high-contention scenarios, a Mutex may actually perform better in practice. Profile before optimizing.

Quick Reference Cheatsheet

// Read-only state (config, flags)
Arc<AppConfig>

// Mutable state, equal reads/writes
Arc<Mutex<T>>

// Mutable state, mostly reads
Arc<RwLock<T>>

// Mutable state, must hold lock across .await
Arc<tokio::sync::Mutex<T>>
Arc<tokio::sync::RwLock<T>>

// In your handler signature:
async fn my_handler(State(state): State<Arc<AppState>>) { ... }

// Attach to router:
Router::new()
    .route("/path", get(my_handler))
    .with_state(Arc::new(app_state))

Summary

Here's the full picture:

Arc<T> — enables multiple handlers to own the same data without copying it, safely across threads.
State<T> — Axum's extractor that delivers shared state to your handlers automatically.
Mutex<T> — ensures only one handler modifies mutable data at a time (exclusive lock).
RwLock<T> — allows many concurrent readers or one exclusive writer, great for read-heavy data.

Together they form the idiomatic Rust pattern for safe, performant shared state in concurrent web applications. Once you internalize this, you'll reach for it naturally in every Axum project.

Happy coding!

Got questions or spotted something? Drop a comment below — I'd love to hear from you!

Error Handling in Axum

Syeed Talha — Sat, 02 May 2026 17:06:54 +0000

Axum is a web framework for Rust built on top of Tokio and Hyper. One of its
standout features is a simple and predictable error handling model — once
you understand the pattern, writing safe, expressive web servers becomes
surprisingly natural.

This guide walks you from the very basics to real-world patterns you'll use in
production.

The Core Idea: Errors Must Become Responses

In Axum, every error must eventually become an HTTP response. There is no
unhandled-exception mechanism. If something goes wrong, you decide what the
client sees — a 404, a 500, a JSON error body, or anything else.

The key trait is IntoResponse. Anything that implements it can be returned
from a handler, including error types.

1. The Simplest Error: Return a `StatusCode`

The easiest way to signal an error is to return a StatusCode directly.

use axum::{
    extract::Path,
    http::StatusCode,
    routing::get,
    Router,
};

async fn get_user(Path(id): Path<u32>) -> Result<String, StatusCode> {
    if id == 0 {
        return Err(StatusCode::NOT_FOUND);
    }
    Ok(format!("User #{}", id))
}

#[tokio::main]
async fn main() {
    let app = Router::new().route("/users/{id}", get(get_user)); // ✅ use {id}
    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

Here the handler returns Result<String, StatusCode>. When Ok, Axum sends
the string as a 200 OK. When Err, it sends the status code you chose. Clean
and simple!

2. Returning Richer Errors with Tuples

A bare StatusCode doesn't tell the client why something went wrong. You can
pair a status code with a message using a tuple.

use axum::{http::StatusCode, routing::post, Json, Router};
use serde::Deserialize;

#[derive(Deserialize)]
struct CreateUser {
    username: String,
}

async fn create_user(
    Json(payload): Json<CreateUser>,
) -> Result<String, (StatusCode, String)> {
    if payload.username.is_empty() {
        return Err((
            StatusCode::BAD_REQUEST,
            "Username cannot be empty".to_string(),
        ));
    }

    Ok(format!("Created user: {}", payload.username))
}

The tuple (StatusCode, String) is automatically turned into a response with
the given status and a text body. Axum knows how to convert it thanks to the
IntoResponse trait.

3. Building a Custom Error Type (The Right Way)

For real applications, you want a single error enum that covers all the things
that can go wrong. Then you implement IntoResponse for it so Axum can turn
your errors into HTTP responses automatically.

use axum::{
    http::StatusCode,
    response::{IntoResponse, Response},
    routing::get,
    Router,
};

// Your application's error type
enum AppError {
    NotFound(String),
    Unauthorized,
    InternalError(String),
}

// Teach Axum how to turn your error into a response
impl IntoResponse for AppError {
    fn into_response(self) -> Response {
        let (status, message) = match self {
            AppError::NotFound(msg) => (StatusCode::NOT_FOUND, msg),
            AppError::Unauthorized => (
                StatusCode::UNAUTHORIZED,
                "You are not authorized".to_string(),
            ),
            AppError::InternalError(msg) => (StatusCode::INTERNAL_SERVER_ERROR, msg),
        };

        (status, message).into_response()
    }
}

// Now use it in your handlers
async fn get_document(Path(id): Path<u32>) -> Result<String, AppError> {
    if id == 99 {
        return Err(AppError::Unauthorized);
    }
    if id > 100 {
        return Err(AppError::NotFound(format!("Document {} not found", id)));
    }
    Ok(format!("Document #{}", id))
}

This is the pattern you'll use most often. One error type, one place to define
what each error looks like to clients.

4. Returning JSON Errors

APIs usually return JSON error bodies instead of plain text. Here's how to
return structured JSON from your error type.

use axum::{
    http::StatusCode,
    response::{IntoResponse, Response},
    Json,
};
use serde::Serialize;

#[derive(Serialize)]
struct ErrorBody {
    error: String,
    code: u16,
}

enum ApiError {
    NotFound(String),
    BadRequest(String),
    Internal,
}

impl IntoResponse for ApiError {
    fn into_response(self) -> Response {
        let (status, message) = match self {
            ApiError::NotFound(msg) => (StatusCode::NOT_FOUND, msg),
            ApiError::BadRequest(msg) => (StatusCode::BAD_REQUEST, msg),
            ApiError::Internal => (
                StatusCode::INTERNAL_SERVER_ERROR,
                "Something went wrong".to_string(),
            ),
        };

        let body = Json(ErrorBody {
            error: message,
            code: status.as_u16(),
        });

        (status, body).into_response()
    }
}

Now your clients get responses like:

{
  "error": "Document 999 not found",
  "code": 404
}

5. Converting `?` Errors with `From`

In real code, you'll use ? to propagate errors from libraries like database
drivers or HTTP clients. You can implement From<SomeError> for AppError to
make this seamless.

use std::num::ParseIntError;

enum AppError {
    BadRequest(String),
    Internal(String),
}

impl IntoResponse for AppError {
    fn into_response(self) -> Response {
        // ... (same as above)
    }
}

// Convert ParseIntError into AppError automatically
impl From<ParseIntError> for AppError {
    fn from(err: ParseIntError) -> Self {
        AppError::BadRequest(format!("Invalid number: {}", err))
    }
}

async fn parse_id(Path(raw): Path<String>) -> Result<String, AppError> {
    // The `?` operator automatically calls From<ParseIntError> here
    let id: u32 = raw.parse()?;
    Ok(format!("Parsed id: {}", id))
}

The ? after raw.parse() will, on failure, call your From impl and return
an Err(AppError::BadRequest(...)) — no manual conversion needed.

6. Using `anyhow` for Quick Prototyping

The anyhow crate is popular for applications where you don't need fine-grained
error types yet. You can bridge it into Axum with a small wrapper.

use anyhow::Context;
use axum::{
    http::StatusCode,
    response::{IntoResponse, Response},
};

// A wrapper so we can impl IntoResponse for anyhow::Error
struct AnyhowError(anyhow::Error);

impl IntoResponse for AnyhowError {
    fn into_response(self) -> Response {
        (
            StatusCode::INTERNAL_SERVER_ERROR,
            format!("Internal error: {}", self.0),
        )
            .into_response()
    }
}

// Allow using `?` on anyhow::Result in handlers
impl<E: Into<anyhow::Error>> From<E> for AnyhowError {
    fn from(err: E) -> Self {
        AnyhowError(err.into())
    }
}

async fn risky_handler() -> Result<String, AnyhowError> {
    let data = std::fs::read_to_string("config.txt")
        .context("Failed to read config file")?;
    Ok(data)
}

7. Handler-Level Error Handling with `HandleError`

Sometimes you use a Tower Service or middleware that returns errors Axum
doesn't know how to handle. The HandleError layer lets you convert those.

use axum::{
    error_handling::HandleError,
    http::StatusCode,
    routing::get,
    Router,
};
use std::convert::Infallible;

async fn might_fail() -> Result<String, String> {
    Err("Something broke".to_string())
}

// Wrap the service to handle its errors
let service = tower::service_fn(|_req| async {
    Ok::<_, Infallible>("ok")
});

let handled = HandleError::new(service, |err: String| async move {
    (StatusCode::INTERNAL_SERVER_ERROR, err)
});

This is more advanced and mainly relevant when integrating third-party Tower
services.

Quick Reference

Pattern	Best For
`Result<T, StatusCode>`	Simple, code-only errors
`Result<T, (StatusCode, String)>`	Errors with a message
Custom `enum` + `impl IntoResponse`	Production apps with typed errors
`impl IntoResponse` returning `Json`	APIs that return JSON error bodies
`impl From<LibError> for AppError`	Using `?` with library errors
`anyhow` wrapper	Quick prototypes or scripts

Summary

Axum's error handling boils down to one rule: your errors must implement
IntoResponse. Once they do, you can use Result<T, YourError> in any
handler and Axum handles the rest.

The recommended path for most apps:

Define an enum AppError with variants for each failure mode.
Implement IntoResponse for it (returning JSON is usually best).
Implement From<LibError> for AppError for each third-party error type you use with ?.
Return Result<impl IntoResponse, AppError> from your handlers.

That's it. No magic, no hidden panics — just clean, explicit error paths.

Build In-Memory CRUD API in Axum (Rust)

Syeed Talha — Sat, 02 May 2026 14:01:38 +0000

If you're learning Rust and want to build APIs, Axum is one of the best frameworks to start with.

In this tutorial, we'll build a simple CRUD API (Create, Read, Update, Delete) using:

✅ Axum
✅ In-memory storage (no database)
✅ Beginner-friendly concepts

What We Will Build

A simple User API with these endpoints:

Method	Route	Description
POST	`/users`	Create a user
GET	`/users`	Get all users
GET	`/user/:id`	Get a single user
PUT	`/user/:id`	Update a user
DELETE	`/user/:id`	Delete a user

Step 1: Setup Dependencies

Add this to your Cargo.toml:

[dependencies]
axum = "0.7"
tokio = { version = "1", features = ["full"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"

Step 2: Define Our Data

#[derive(Debug, Serialize, Deserialize, Clone)]
struct User {
    id: u32,
    name: String,
    email: String,
}

#[derive(Deserialize)]
struct CreateUser {
    name: String,
    email: String,
}

User → the stored data structure
CreateUser → the incoming request body

Step 3: App State (In-Memory Database)

type AppState = Arc<Mutex<Vec<User>>>;

We use:

Vec<User> → to store users
Mutex → for safe concurrent access
Arc → to share state across threads

Step 4: Create User (POST)

async fn create_user(
    State(state): State<AppState>,
    Json(body): Json<CreateUser>,
) -> (StatusCode, Json<User>) {
    let mut users = state.lock().unwrap();
    let new_id = users.last().map_or(1, |u| u.id + 1);
    let new_user = User {
        id: new_id,
        name: body.name,
        email: body.email,
    };
    users.push(new_user.clone());
    (StatusCode::CREATED, Json(new_user))
}

Step 5: Get All Users (GET)

async fn user_list(State(state): State<AppState>) -> Json<Vec<User>> {
    let users = state.lock().unwrap();
    Json(users.clone())
}

Step 6: Get Single User

async fn get_user(
    State(state): State<AppState>,
    Path(id): Path<u32>,
) -> Result<Json<User>, StatusCode> {
    let users = state.lock().unwrap();

    if let Some(user) = users.iter().find(|u| u.id == id) {
        Ok(Json(user.clone()))
    } else {
        Err(StatusCode::NOT_FOUND)
    }
}

Step 7: Update User

async fn update_user(
    State(state): State<AppState>,
    Path(id): Path<u32>,
    Json(body): Json<CreateUser>,
) -> Result<Json<User>, StatusCode> {
    let mut users = state.lock().unwrap();

    if let Some(user) = users.iter_mut().find(|u| u.id == id) {
        user.name = body.name;
        user.email = body.email;
        Ok(Json(user.clone()))
    } else {
        Err(StatusCode::NOT_FOUND)
    }
}

Step 8: Delete User

async fn delete_user(
    State(state): State<AppState>,
    Path(id): Path<u32>,
) -> StatusCode {
    let mut users = state.lock().unwrap();

    if let Some(pos) = users.iter().position(|u| u.id == id) {
        users.remove(pos);
        StatusCode::NO_CONTENT
    } else {
        StatusCode::NOT_FOUND
    }
}

Step 9: Setup Router & Main

#[tokio::main]
async fn main() {
    let state: AppState = Arc::new(Mutex::new(vec![]));

    let app = Router::new()
        .route("/users", get(user_list).post(create_user))
        .route(
            "/user/:id",
            get(get_user)
                .put(update_user)
                .delete(delete_user),
        )
        .with_state(state);

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000")
        .await
        .unwrap();

    println!("Server running on http://localhost:3000");
    axum::serve(listener, app).await.unwrap();
}

Full Code (Mutex Version)

use axum::{
    extract::{State, Path},
    http::StatusCode,
    routing::{get, post, put, delete},
    Json,
    Router,
};

use serde::{Deserialize, Serialize};
use std::sync::{Arc, Mutex};

#[derive(Debug, Serialize, Deserialize, Clone)]
struct User {
    id: u32,
    name: String,
    email: String,
}

#[derive(Deserialize)]
struct CreateUser {
    name: String,
    email: String,
}

type AppState = Arc<Mutex<Vec<User>>>;

async fn create_user(
    State(state): State<AppState>,
    Json(body): Json<CreateUser>,
) -> (StatusCode, Json<User>) {
    let mut users = state.lock().unwrap();
    let new_user = User {
        id: users.len() as u32 + 1,
        name: body.name,
        email: body.email,
    };
    users.push(new_user.clone());
    (StatusCode::CREATED, Json(new_user))
}

async fn user_list(State(state): State<AppState>) -> Json<Vec<User>> {
    let users = state.lock().unwrap();
    Json(users.clone())
}

async fn get_user(
    State(state): State<AppState>,
    Path(id): Path<u32>,
) -> Result<Json<User>, StatusCode> {
    let users = state.lock().unwrap();
    if let Some(user) = users.iter().find(|u| u.id == id) {
        Ok(Json(user.clone()))
    } else {
        Err(StatusCode::NOT_FOUND)
    }
}

async fn update_user(
    State(state): State<AppState>,
    Path(id): Path<u32>,
    Json(body): Json<CreateUser>,
) -> Result<Json<User>, StatusCode> {
    let mut users = state.lock().unwrap();
    if let Some(user) = users.iter_mut().find(|u| u.id == id) {
        user.name = body.name;
        user.email = body.email;
        Ok(Json(user.clone()))
    } else {
        Err(StatusCode::NOT_FOUND)
    }
}

async fn delete_user(
    State(state): State<AppState>,
    Path(id): Path<u32>,
) -> StatusCode {
    let mut users = state.lock().unwrap();
    if let Some(pos) = users.iter().position(|u| u.id == id) {
        users.remove(pos);
        StatusCode::NO_CONTENT
    } else {
        StatusCode::NOT_FOUND
    }
}

#[tokio::main]
async fn main() {
    let state: AppState = Arc::new(Mutex::new(vec![]));

    let app = Router::new()
        .route("/users", post(create_user))
        .route("/users", get(user_list))
        .route("/user/:id", put(update_user))
        .route("/user/:id", delete(delete_user))
        .route("/user/:id", get(get_user))
        .with_state(state);

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    println!("Server running on http://localhost:3000");
    axum::serve(listener, app).await.unwrap();
}

Bonus: Async RwLock Version

For better read performance (multiple concurrent reads), use tokio::sync::RwLock instead of Mutex:

use axum::{
    extract::State,
    http::StatusCode,
    routing::{get, post, put, delete},
    extract::{Path, Json},
    Router,
};
use serde::{Deserialize, Serialize};
use std::sync::Arc;
use tokio::sync::RwLock;

#[derive(Debug, Clone, Serialize, Deserialize)]
struct User {
    id: u32,
    name: String,
    email: String,
}

#[derive(Debug, Deserialize)]
struct CreateUser {
    name: String,
    email: String,
}

type AppState = Arc<RwLock<Vec<User>>>;

async fn create_user(
    State(state): State<AppState>,
    Json(body): Json<CreateUser>,
) -> (StatusCode, Json<User>) {
    let mut users = state.write().await;
    let new_id = users.last().map_or(1, |u| u.id + 1);
    let new_user = User {
        id: new_id,
        name: body.name,
        email: body.email,
    };
    users.push(new_user.clone());
    (StatusCode::CREATED, Json(new_user))
}

async fn user_list(State(state): State<AppState>) -> Json<Vec<User>> {
    let users = state.read().await;
    Json(users.clone())
}

async fn get_user(
    State(state): State<AppState>,
    Path(id): Path<u32>,
) -> Result<Json<User>, StatusCode> {
    let users = state.read().await;
    if let Some(user) = users.iter().find(|u| u.id == id) {
        Ok(Json(user.clone()))
    } else {
        Err(StatusCode::NOT_FOUND)
    }
}

async fn delete_user(
    State(state): State<AppState>,
    Path(id): Path<u32>,
) -> StatusCode {
    let mut users = state.write().await;
    if let Some(pos) = users.iter().position(|u| u.id == id) {
        users.remove(pos);
        StatusCode::NO_CONTENT
    } else {
        StatusCode::NOT_FOUND
    }
}

async fn update_user(
    State(state): State<AppState>,
    Path(id): Path<u32>,
    Json(body): Json<User>,
) -> Result<Json<User>, StatusCode> {
    let mut users = state.write().await;
    if let Some(user) = users.iter_mut().find(|u| u.id == id) {
        user.name = body.name;
        user.email = body.email;
        Ok(Json(user.clone()))
    } else {
        Err(StatusCode::NOT_FOUND)
    }
}

#[tokio::main]
async fn main() {
    let state: AppState = Arc::new(RwLock::new(vec![]));

    let app = Router::new()
        .route("/users", get(user_list))
        .route("/users", post(create_user))
        .route("/user/{id}", get(get_user))
        .route("/user/{id}", delete(delete_user))
        .route("/user/{id}", put(update_user))
        .with_state(state);

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    println!("Server running on http://localhost:3000");
    axum::serve(listener, app).await.unwrap();
}

Mutex vs RwLock: Use Mutex for simplicity. Use RwLock when you have many reads and few writes — it allows multiple readers simultaneously.

How to Test

Use Postman or curl to test your endpoints.

Create a user:

POST /users
Content-Type: application/json

{
  "name": "John",
  "email": "john@example.com"
}

Get all users:

GET /users

Get a single user:

GET /user/1

Update a user:

PUT /user/1
Content-Type: application/json

{
  "name": "John Updated",
  "email": "john_updated@example.com"
}

Delete a user:

DELETE /user/1

Key Concepts You Learned

Axum routing — how to define and chain HTTP routes
State management — sharing data across handlers with Arc<Mutex<T>>
JSON handling — extracting request bodies and returning JSON responses
Path parameters — reading dynamic values from the URL
CRUD operations — implementing all four basic data operations

What's Next?

Now that you have the basics down, you can level up by:

Replacing in-memory storage with PostgreSQL (using sqlx)
Adding input validation (using validator)
Adding authentication (JWT tokens)
Switching to tokio::sync::RwLock for better concurrency

Happy coding!

Understanding the match Keyword in Rust with Examples

Syeed Talha — Thu, 30 Apr 2026 02:39:24 +0000

If you've ever written a long if/else chain and thought "there must be a cleaner way" — match is Rust's answer. It lets you check a value against a list of patterns and run different code for each one.

By the end of this post, you'll understand exactly how match works, why Rust forces you to use it a certain way, and how it handles real-world things like errors.

What is `match`?

match compares a value against a list of patterns. The first matching pattern wins, and the code next to it runs.

Here's the simplest example — matching a number:

let number = 2;

match number {
    1 => println!("One"),
    2 => println!("Two"),
    3 => println!("Three"),
    _ => println!("Something else"),
}
// Output: Two

Each pattern => code pair is called an arm. Rust checks arms from top to bottom and stops at the first match.

The anatomy of a match expression

match  <value>  {
    pattern1 => code to run,
    pattern2 => code to run,
    _        => code to run,  // catch-all
}

match — the keyword
<value> — the thing you're checking
each pattern => code — one arm
_ — the catch-all (like default in other languages)

The catch-all pattern: `_`

Rust requires you to cover every possible value. If you only match 1, 2, and 3 — what happens when the number is 99? You must either list every possibility or use _ as a catch-all.

⚠️ Compile error without it! If you forget the catch-all and don't cover every possible value, Rust will refuse to compile your code. This is a feature — it prevents bugs.

let day = 5;

let name = match day {
    1 => "Monday",
    2 => "Tuesday",
    3 => "Wednesday",
    4 => "Thursday",
    5 => "Friday",
    6 => "Saturday",
    7 => "Sunday",
    _ => "Invalid day",  // covers anything outside 1–7
};

println!("Day {} is {}", day, name);
// Output: Day 5 is Friday

Notice something cool here — match returned a value and we stored it in name. That's because match is an expression in Rust, not just a statement.

Matching ranges

Instead of listing every number, you can match a whole range using ..= (inclusive range):

let score = 72;

let grade = match score {
    90..=100 => "A",   // matches 90, 91, 92 ... 100
    80..=89  => "B",
    70..=79  => "C",
    60..=69  => "D",
    _        => "F",
};

println!("Your grade is: {}", grade);
// Output: Your grade is: C

💡 90..=100 means "90 to 100, including both endpoints". The = in ..= makes it inclusive.

Matching enums — the most common use

This is where match truly shines. Rust enums can have different variants, and match is the natural way to handle each one.

enum Direction {
    North,
    South,
    East,
    West,
}

let heading = Direction::North;

let message = match heading {
    Direction::North => "Going up!",
    Direction::South => "Going down!",
    Direction::East  => "Going right!",
    Direction::West  => "Going left!",
    // No _ needed — all 4 variants are covered!
};

println!("{}", message);
// Output: Going up!

When you cover every enum variant, no catch-all is needed. And if you add a new variant later (say, NorthEast), Rust will immediately tell you everywhere in your code that you forgot to handle it.

Destructuring — unpacking values from enums

Enum variants can hold data. With match, you can unpack that data right in the pattern. This is called destructuring.

enum Message {
    Hello(String),   // holds a String
    Number(i32),     // holds an i32
    Quit,            // holds nothing
}

let msg = Message::Hello(String::from("Rustacean"));

match msg {
    Message::Hello(name) => println!("Hello, {}!", name),
    Message::Number(n)   => println!("Got number: {}", n),
    Message::Quit        => println!("Quit!"),
}
// Output: Hello, Rustacean!

Message::Hello(name) both matches the variant and pulls out the inner String into a variable called name. One line does two things!

Matching `Option<T>`

Option is one of Rust's most important types. It represents a value that might or might not exist — either Some(value) or None. You'll use match with it all the time.

fn find_first_even(numbers: Vec<i32>) -> Option<i32> {
    for n in numbers {
        if n % 2 == 0 {
            return Some(n);  // found one!
        }
    }
    None  // nothing found
}

let result = find_first_even(vec![1, 3, 4, 7]);

match result {
    Some(n) => println!("First even number: {}", n),
    None    => println!("No even numbers found."),
}
// Output: First even number: 4

Matching `Result<T, E>` — handling errors

Result is how Rust handles errors. A function that can fail returns either Ok(value) for success or Err(reason) for failure. match is the standard way to handle both cases.

Example 1 — password check

fn check_password(input: &str) -> Result<&str, &str> {
    if input == "secret123" {
        Ok("Access granted")
    } else {
        Err("Wrong password")
    }
}

fn main() {
    match check_password("secret123") {
        Ok(msg)  => println!("{}", msg),
        Err(err) => println!("{}", err),
    }
}
// Output: Access granted

The Result<&str, &str> return type means: "this function returns either a success &str or an error &str". The match handles both cases and unpacks the inner value.

Example 2 — safe division

fn divide(a: i32, b: i32) -> Result<i32, String> {
    if b == 0 {
        Err("Can't divide by zero".to_string())
    } else {
        Ok(a / b)
    }
}

fn main() {
    let result = divide(10, 0);

    match result {
        Ok(value) => println!("Result is {}", value),
        Err(err)  => println!("Error: {}", err),
    }
}
// Output: Error: Can't divide by zero

Since b is 0, the function returns Err(...), and our match catches it cleanly. No crashes, no panics!

💡 Option vs Result:

Use Option when a value might not exist.

Use Result when an operation can fail and you want to explain why.

`match` vs `if/else` — when to use which

Situation	Use	Why
Checking many specific values	`match`	Cleaner and exhaustive
Handling `Option` or `Result`	`match`	Unpacks values naturally
Simple true/false condition	`if/else`	More readable for one condition
Comparing with `>`, `<`	`if/else`	`match` doesn't support these directly
Matching enum variants	`match`	Compiler verifies all variants covered

Quick summary

Here's everything match gives you:

Patterns & arms — each pattern => code pair is an arm; Rust tries them top to bottom
Exhaustive — every possible value must be covered, or your code won't compile
Returns a value — you can write let x = match ... to capture the result
Destructuring — unpack data from inside enum variants right in the pattern

What to try next

Write a function that returns Result<i32, String> and handle it with match
Look into if let — a shorthand for when you only care about one pattern
Explore Option methods like .unwrap_or() and .map() — they use match under the hood

That's it! match might feel different at first if you're coming from other languages, but once it clicks, you'll wonder how you ever lived without it. 🦀

Found this helpful? Drop a ❤️ or share it with someone learning Rust!

JWT Auth Middleware in Axum 0.8 — A Beginner's Guide

Syeed Talha — Sun, 26 Apr 2026 17:09:13 +0000

If you've ever built a web API, you've probably asked yourself: "How do I make sure only the right people can access certain routes?" That's exactly what authentication middleware solves — and in this guide, you'll learn how to do it in Axum 0.8 using JSON Web Tokens (JWT).

By the end of this article, you'll understand:

What JWTs are and why they're useful
How middleware works in Axum 0.8
How to write a JWT auth middleware from scratch
How to protect routes and pass user data to your handlers

Let's get started.

What is a JWT?

A JSON Web Token (JWT) is a compact, self-contained string that carries information about a user. It looks like this:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0IiwiZXhwIjoxNzAwMDAwfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

It has three parts separated by dots:

Header — the algorithm used to sign the token (e.g. HS256)
Payload — the actual data (e.g. user ID, expiry time)
Signature — proves the token hasn't been tampered with

Here's the flow: a user logs in → your server creates a JWT and sends it back → the user includes that JWT in future requests → your middleware validates it before the request reaches your handler.

What is Middleware in Axum?

Think of middleware as a security guard standing between the internet and your handlers. Every request passes through the guard first. The guard can:

Let the request through (valid token → call next.run(req))
Block the request (invalid or missing token → return 401 Unauthorized)
Attach extra information to the request (e.g. the logged-in user's ID)

In Axum 0.8, you write middleware as a plain async function and wrap it with middleware::from_fn().

Project Setup

Start by creating a new project:

cargo new axum-jwt-demo
cd axum-jwt-demo

Add these dependencies to your Cargo.toml:

[dependencies]
axum       = "0.8"
tokio      = { version = "1", features = ["full"] }
tower      = "0.5"
jsonwebtoken = { version = "10.3.0", features = ["rust_crypto"] }
serde      = { version = "1", features = ["derive"] }
serde_json = "1"

Here's what each crate does:

axum — the web framework
tokio — the async runtime axum runs on
tower — the middleware system axum uses under the hood
jsonwebtoken — encode and decode JWTs
serde / serde_json — serialize and deserialize the JWT payload (called "claims")

Step 1 — Define Your JWT Claims

A JWT's payload is called claims. Claims are just a Rust struct that you serialize into the token. At a minimum you want a user ID and an expiry time.

Create src/claims.rs:

use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct Claims {
    pub sub: String,   // subject — usually the user ID
    pub exp: usize,    // expiry timestamp (Unix time)
}

The field names sub and exp are standard JWT claim names. exp is especially important — the jsonwebtoken crate automatically rejects tokens where exp is in the past.

Step 2 — Create Helper Functions

You need two helpers: one to create a JWT (for your login route), and one to validate a JWT (for your middleware).

Create src/auth.rs:

use jsonwebtoken::{decode, encode, DecodingKey, EncodingKey, Header, Validation};
use std::time::{SystemTime, UNIX_EPOCH};

use crate::claims::Claims;

// In a real app, store this in an environment variable — never hardcode it!
const SECRET: &[u8] = b"my-super-secret-key";

/// Create a JWT for a given user ID.
/// Returns the token string on success.
pub fn create_token(user_id: &str) -> Result<String, jsonwebtoken::errors::Error> {
    let expiry = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .unwrap()
        .as_secs() as usize
        + 3600; // token expires in 1 hour

    let claims = Claims {
        sub: user_id.to_string(),
        exp: expiry,
    };

    encode(
        &Header::default(),
        &claims,
        &EncodingKey::from_secret(SECRET),
    )
}

/// Validate a JWT string.
/// Returns the decoded Claims on success, or an error if the token is invalid/expired.
pub fn validate_token(token: &str) -> Result<Claims, jsonwebtoken::errors::Error> {
    let token_data = decode::<Claims>(
        token,
        &DecodingKey::from_secret(SECRET),
        &Validation::default(),
    )?;

    Ok(token_data.claims)
}

Quick note on the secret key: In production, never hardcode this. Load it from an environment variable using the dotenvy crate. Anyone who knows the secret can forge tokens.

&[u8] in Simple Terms

Think of it as a peek at some bytes — you're looking, not touching.

The pieces:

u8 → a number from 0–255 (one byte)
[u8] → a list of those numbers
& → "I'm just looking at it, not owning it"

The most common use:

let key: &[u8] = b"hello";

b"hello" just means "give me the raw numbers behind this text" → [104, 101, 108, 108, 111]

String vs Bytes — one line:

let a = "ABC";    // text
let b = b"ABC";   // same thing, but as numbers: [65, 66, 67]

One-line summary:
&[u8] = "borrowed list of numbers" — you're pointing at bytes, not storing them.

Now lets understand `encode(...)` — What Each Argument Does

encode(
        &Header::default(),
        &claims,
        &EncodingKey::from_secret(SECRET),
    )

This line creates the actual JWT token. Think of it as:

"Pack my data, sign it with a key, and give me a token string."

&Header::default()
The token format settings — just use defaults (algorithm: HS256).
Like saying "standard packaging, nothing special."

&claims
The actual data you want to store in the token — the user ID + expiry time.
This is the "what's inside the box."

&EncodingKey::from_secret(SECRET)
Your secret key used to sign the token, so nobody can fake it.
Like a wax seal on a letter — if it's broken, you know it was tampered with.
Now why the & on everything?
Just means "borrow it, don't consume it" — same & you already learned.

Full picture in one line:

encode( how to pack it,  what to pack,  your secret stamp )
       └─ Header ──────┘ └─ Claims ──┘ └─ EncodingKey ───┘

Now lets understand `validate_token` Simply

    let token_data = decode::<Claims>(
        token,
        &DecodingKey::from_secret(SECRET),
        &Validation::default(),
    )?;
    Ok(token_data.claims)

This function checks if a token is real and trustworthy, then pulls out the data inside.

decode::<Claims>(...)
Open the token and try to read it as Claims (user ID + expiry).
The <Claims> part just says "I expect this type inside."

token
The raw JWT string the user sent you — "here's the token, check it."

&DecodingKey::from_secret(SECRET)
Your secret key to verify the signature.
Like checking the wax seal — "did I actually stamp this, or did someone fake it?"

&Validation::default()
The rules to check against — expiry time, algorithm, etc.
Like saying "run the standard checks, nothing custom."

? at the end
If anything fails (fake token, expired, wrong key) — stop and return the error immediately.

Ok(token_data.claims)
Everything passed ✅ — return just the useful part (user ID + expiry), not the whole token object.

Full picture:

decode( the token,  your secret key,   the rules )
        └─ input ─┘ └─ verify seal ──┘ └─ checks ┘
             ↓
        token_data.claims  →  just give me the data inside

Step 3 — Write the Auth Middleware

Now for the heart of this guide — the middleware function.

Create src/middleware.rs:

use axum::{
    extract::Request,
    http::{header, StatusCode},
    middleware::Next,
    response::Response,
};

use crate::auth::validate_token;
use crate::claims::Claims;

pub async fn jwt_auth(
    mut req: Request,
    next: Next,
) -> Result<Response, StatusCode> {

    // 1. Get the Authorization header
    let auth_header = req
        .headers()
        .get(header::AUTHORIZATION)
        .and_then(|value| value.to_str().ok());

    // 2. Make sure it starts with "Bearer "
    let token = match auth_header {
        Some(header) if header.starts_with("Bearer ") => {
            &header["Bearer ".len()..] // slice off "Bearer " prefix
        }
        _ => {
            // No token or wrong format — reject with 401
            return Err(StatusCode::UNAUTHORIZED);
        }
    };

    // 3. Validate the token
    match validate_token(token) {
        Ok(claims) => {
            // 4. Attach the claims to the request so handlers can use them
            req.extensions_mut().insert(claims);
            // 5. Pass the request to the next layer (your handler)
            Ok(next.run(req).await)
        }
        Err(_) => {
            // Invalid or expired token — reject with 401
            Err(StatusCode::UNAUTHORIZED)
        }
    }
}

Let's walk through what happens:

The middleware reads the Authorization header from the incoming request.
It checks that the header starts with "Bearer " — the standard format for JWT tokens.
It calls validate_token() to verify the signature and check the expiry.
If valid, it inserts the decoded Claims into the request's extensions — a type-safe bag you can attach extra data to.
It calls next.run(req) to pass the request onward to your handler.
If anything fails, it immediately returns a 401 Unauthorized response. The handler never runs.

Lets understand the `Auth Header` — Simply Explained

    let auth_header = req 
        .headers()
        .get(header::AUTHORIZATION)
        .and_then(|v| v.to_str().ok());

This code looks for the Authorization header in the request — like checking if someone showed their ID card.

req.headers()
Get all headers from the incoming request.
Like "open the envelope and look at the labels."

A real request might carry headers like:

Authorization: Bearer eyJ...   // who you are (token)
Content-Type: application/json // what format the body is in
Accept-Language: en-US         // what language you prefer
User-Agent: Mozilla/5.0        // what browser/app you're using

All of these live inside .headers() — a map of key → value pairs.

.get(header::AUTHORIZATION)
Find specifically the Authorization header.
Like "do you have an ID card?"

There are many header types you could .get() instead:

.get(header::CONTENT_TYPE)     // "what format is the body?"
.get(header::USER_AGENT)       // "what app sent this?"
.get(header::ACCEPT_LANGUAGE)  // "what language does the user want?"

Returns Some(value) if found, None if missing. ✅ / ❌

.and_then(|v| v.to_str().ok())
If the header exists, try to convert it to a readable string.

and_then → "if it exists, do this next step"
to_str().ok() → convert bytes to text, or return None if it fails

let auth_header
The result is either:

Some("Bearer eyJ...") → token found ✅
None → no header, no token ❌

Full picture:

req.headers()          // all headers
  .get(AUTHORIZATION)  // find the auth one
  .and_then(...)        // if found → convert to string
                              ↓
                 Some("Bearer eyJ...") or None

Lets understand the Extracting the Token — Simply Explained

let token = match auth_header {
        Some(header) if header.starts_with("Bearer ") => {
            &header["Bearer ".len()..]
        }
        _=>{
            return Err(StatusCode::UNAUTHORIZED);
        }
    };

This code pulls out the actual token from the header value — like "ok you have an ID card, now let me read what's on it."

match auth_header
Check what's inside auth_header — like an if/else but cleaner.

Some(header) if header.starts_with("Bearer ")
Two checks in one line:

Some(header) → the header actually exists
if header.starts_with("Bearer ") → it looks like a real auth header

A valid header looks like this:

Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...
                ↑
           this part is the format we expect

If both checks pass → go ahead ✅

&header["Bearer ".len()..]
Cut off the "Bearer " part and keep only the token.

"Bearer eyJhbGci..."
         ↑
         start here → "eyJhbGci..."

"Bearer ".len() → the length of "Bearer " which is 7
[7..] → "give me everything after position 7"

_ => return Err(StatusCode::UNAUTHORIZED)
_ means everything else — no header, wrong format, anything unexpected.
Just say "401 Unauthorized, go away."

Full picture:

match auth_header
  ├── exists + starts with "Bearer " → strip it → just the token ✅
  └── anything else                  → 401 Unauthorized ❌

Lets understand the Token validation part

match validate_token(token) {
        Ok(claims) => {
            // 4. Attach the claims to the request so handlers can use them
            req.extensions_mut().insert(claims);
            // 5. Pass the request to the next layer (your handler)
            Ok(next.run(req).await)
        }
        Err(_) => {
            // Invalid or expired token — reject with 401
            Err(StatusCode::UNAUTHORIZED)
        }
    }

This code checks if the token is real, then either lets the request through or blocks it.

match validate_token(token)
Run the token through the validator we saw earlier.
Returns either Ok(claims) or Err(...) — "valid or not?"

Ok(claims) =>
Token is valid ✅ — now do two things:

req.extensions_mut().insert(claims)
Attach the user's data (claims) to the request.
Like "staple the user's ID info to the envelope" so any handler down the line can read it without checking the token again.

request  →  [token checked ✅]  →  claims attached  →  handler can use it

Ok(next.run(req).await)
Pass the request forward to the actual handler.

next → "whoever is waiting for this request"
.run(req) → "send it through"
.await → "wait for it to finish"

Like a security guard who checked your ID and now says "ok, you can go in." 🚪✅

Err(_) => Err(StatusCode::UNAUTHORIZED)
Token is fake, expired, or broken ❌
_ means "I don't care what the error is" — just reject with 401.

Full picture:

validate_token(token)
  ├── Ok  → attach claims to request → pass to handler ✅
  └── Err → 401 Unauthorized ❌

Step 4 — Write the Handlers

Now write a login handler (issues the token) and a protected handler (requires the token).

Create src/handlers.rs:

use axum::{extract::Extension, http::StatusCode, response::Json};
use serde_json::{json, Value};

use crate::auth::create_token;
use crate::claims::Claims;

/// Public route — anyone can call this to get a token.
pub async fn login() -> Result<Json<Value>, StatusCode> {
    // In a real app: verify username/password from the request body first!
    let user_id = "user-42";

    match create_token(user_id) {
        Ok(token) => Ok(Json(json!({ "token": token }))),
        Err(_) => Err(StatusCode::INTERNAL_SERVER_ERROR),
    }
}

/// Protected route — only accessible with a valid JWT.
pub async fn dashboard(
    Extension(claims): Extension<Claims>,
) -> Json<Value> {
    // `claims` was attached by the middleware — no manual extraction needed
    Json(json!({
        "message": "Welcome to your dashboard!",
        "user_id": claims.sub,
    }))
}

Notice how dashboard receives Extension(claims): Extension<Claims> — it's able to read the claims that the middleware attached to the request, without doing any JWT work itself. The middleware and handler are cleanly separated.

Lets understand the `Extension(claims): Extension<Claims>`

This is how the handler grabs the user's data that the middleware stapled to the request earlier.

The whole thing is just a function argument:

pub async fn dashboard(
    Extension(claims): Extension<Claims>,  // ← this is just one argument
)

Axum automatically reads the request and fills this in for you. No manual work needed.

Extension<Claims> — the type
"I want to extract an Extension that contains Claims from the request."
Like saying "I know there's a stamped ID card on this envelope, give it to me."

Extension(claims) — the pattern
Unwrap the Extension wrapper and give me just the inner value as claims.

Think of it like a gift box:

Extension( claims )
└─ the box ─┘└─ what's inside ─┘

You don't care about the box — you just want what's inside. ✅

Together:

Extension(claims): Extension<Claims>
//    ↑                   ↑
// unwrap it,         expect this type
// call it `claims`   in the request

Why no manual extraction?
Because middleware already did the hard work:

middleware → validate token → insert(claims) → attached to request
handler   → Extension(claims)               → just grab it, done ✅

Step 5 — Wire Everything Together

Finally, set up the router in src/main.rs:

mod auth;
mod claims;
mod handlers;
mod middleware;

use axum::{middleware as axum_middleware, routing::get, Router};
use handlers::{dashboard, login};
use middleware::jwt_auth;

#[tokio::main]
async fn main() {
    // Protected routes — JWT middleware runs before each handler
    let protected = Router::new()
        .route("/dashboard", get(dashboard))
        .route_layer(axum_middleware::from_fn(jwt_auth));

    // Public routes — no middleware
    let app = Router::new()
        .route("/login", get(login))
        .merge(protected);

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000")
        .await
        .unwrap();

    println!("Listening on http://localhost:3000");
    axum::serve(listener, app).await.unwrap();
}

Two important things here:

route_layer() applies the middleware only to the routes defined above it in protected. The /login route is completely unaffected.
layer() (if used on the whole router) would apply the middleware to every route — including /login and even 404 responses. Use route_layer when you want surgical control.

Step 6 — Try It Out

Run the server:

cargo run

Get a token (hit the login route):

curl http://localhost:3000/login
# Response: {"token":"eyJhbGci..."}

Access the protected route with the token:

curl -H "Authorization: Bearer eyJhbGci..." http://localhost:3000/dashboard
# Response: {"message":"Welcome to your dashboard!","user_id":"user-42"}

Try without a token:

curl http://localhost:3000/dashboard
# Response: 401 Unauthorized

Try with a fake token:

curl -H "Authorization: Bearer fake-token" http://localhost:3000/dashboard
# Response: 401 Unauthorized

Everything works exactly as expected.

Common Mistakes to Avoid

Hardcoding the secret key. Use environment variables in production. The dotenvy crate makes this easy — load your secret with std::env::var("JWT_SECRET") at startup.

Forgetting the expiry claim. If you don't set exp, anyone who gets hold of a token can use it forever. Always set a reasonable expiry (1 hour is a common choice for access tokens).

Using layer() instead of route_layer(). This accidentally protects your login route too, creating a chicken-and-egg problem where users can't log in because they need a token to get a token.

Not returning the right HTTP status codes. Use 401 Unauthorized when the token is missing or invalid. Use 403 Forbidden if the token is valid but the user doesn't have permission for that specific resource.

What's Next?

Now that you have the basics working, here are some natural next steps:

Refresh tokens — issue a short-lived access token and a long-lived refresh token so users stay logged in without re-entering their password.
Role-based access control — add a role field to your Claims struct and check it in the middleware or handler to differentiate between admin and regular users.
The governor crate — pair your auth middleware with rate limiting to protect your login route from brute-force attacks.
Secure your secret — use dotenvy to load JWT_SECRET from a .env file and never commit secrets to version control.

Authentication is one of those things that feels complex at first but clicks once you see the full picture. You've now got a solid foundation to build on.

Axum Middleware Explained for Absolute Beginners (With Full Code)

Syeed Talha — Wed, 22 Apr 2026 02:46:03 +0000

Middleware in Axum often looks scary—not because it’s hard, but because the code syntax feels unfamiliar.

This guide explains everything in a very simple, beginner-friendly way, including:

Full working code
Cargo.toml setup
Clear explanation of the confusing parts

🧠 What is Middleware?

Middleware is just a function that runs:

before your handler
after your handler

Think of it like a wrapper around your route.

📦 Step 1: Cargo.toml Setup

Create a new Rust project and add this:

[dependencies]
axum = "0.7"
tokio = { version = "1", features = ["full"] }
tracing = "0.1"
tracing-subscriber = "0.3"

💻 Step 2: Full Working Code

use axum::{
    routing::get,
    Router,
    middleware,
    extract::Request,
    response::Response,
};

use tracing::info;
use std::time::Instant;
use tokio::time::{sleep, Duration};

async fn handler() -> &'static str {
    sleep(Duration::from_secs(2)).await;
    "Hello world from Axum"
}

async fn my_middleware(
    req: Request<axum::body::Body>,
    next: middleware::Next,
) -> Response {

    println!("-> Before handler");

    let start = Instant::now();

    let res = next.run(req).await;

    println!("<- After handler");
    println!("Time: {:?}", start.elapsed());

    res
}

#[tokio::main]
async fn main() {

    tracing_subscriber::fmt::init();

    let app = Router::new()
        .route("/", get(handler))
        .layer(middleware::from_fn(my_middleware));

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000")
        .await
        .unwrap();

    info!("Server running on http://0.0.0.0:3000");

    axum::serve(listener, app).await.unwrap();
}

🚀 What Happens When You Run This?

You visit http://localhost:3000
Middleware runs before
Handler runs (waits 2 seconds)
Middleware runs after
Response is sent

Console output:

-> Before handler
<- After handler
Time: 2.00s

🔥 Now Let’s Explain the Confusing Parts

This is the most important section.

1️⃣ `req: Request<axum::body::Body>`

req: Request<axum::body::Body>

What is this?

This is the incoming HTTP request.

It contains:

URL (/)
headers
body (data sent by client)

Why is it written like this?

Rust is very strict about types, so it says:

Request<T> → request with some body type
axum::body::Body → the actual body format

👉 Simple meaning:

“This is the full request coming from the client”

You can just think:

req = user request

2️⃣ `next: middleware::Next`

next: middleware::Next

What is this?

This represents the next step in the chain.

That could be:

your handler
or another middleware

Simple meaning:

“What should happen after this middleware?”

3️⃣ The MOST IMPORTANT Line

let res = next.run(req).await;

What is happening here?

This line says:

“Send the request forward and wait for the response”

Break it down:

Part	Meaning
`next.run(...)`	call the next step
`req`	pass the request
`.await`	wait for result
`res`	store the response

Why is this REQUIRED?

Without this line:

the handler will never run
the request will stop inside middleware

👉 Middleware must always decide:

forward request ❓
or block it ❌

4️⃣ `tracing_subscriber::fmt::init();`

tracing_subscriber::fmt::init();

What is this?

This sets up logging system.

Why do we need it?

Because this line alone does nothing:

info!("Server running...");

Rust logging works like this:

tracing → creates logs
tracing-subscriber → displays logs

Without init():

logs are silently ignored ❌

With init():

logs are printed to console ✅

5️⃣ `info!`

info!("Server running on http://0.0.0.0:3000");

What is this?

This is a log message, like println! but better.

Why use it instead of `println!`?

Because it supports:

log levels (info, debug, error)
filtering
structured logging

👉 Example:

RUST_LOG=debug cargo run

⚡ Quick Comparison

Feature	println!	info!
Works instantly	✅	❌ (needs init)
Log levels	❌	✅
Production use	❌	✅

🎯 Final Mental Model

Whenever you see middleware, think:

1. Receive request
2. Do something BEFORE
3. Call next.run(req)
4. Do something AFTER
5. Return response

🏁 Summary

req → the incoming request
next → what happens next
next.run(req).await → pass control forward
tracing_subscriber::fmt::init() → enable logging
info! → structured logging

Middleware is not complex — it just looks complex.

Once you understand the flow, everything becomes simple.

If you want to go further, next steps could be:

Authentication middleware
Logging every request
Error handling middleware

Just continue building — that’s the best way to learn 🚀

DEV Community: Syeed Talha

How to Inject Hidden Runtime Context into AI Agent Tools (LangChain + LangGraph)

The Problem: LLMs Can't Be Trusted With Authorization

What We're Building

Prerequisites

Step 1: Define the Models

Step 2: Set Up a Dummy Database

Step 3: Define the Runtime Context

Step 4: Build the Tool with ToolRuntime

What makes ToolRuntime special?

Step 5: Create the Agent with context_schema

Step 6: Invoke with Hidden Context

Full Code

Sample Output

Why This Architecture Matters

Real-World Integration

Wrapping Up

How to Build a Human-in-the-Loop AI Agent with LangChain & LangGraph

What We're Building

Prerequisites

Step 1: Set Up the Model

Step 2: Define the Tool

Step 3: Create the Agent with Human-in-the-Loop Middleware

Step 4: First Invocation — Let the Agent Plan

Step 5: Ask the Human

Step 6: Resume Based on the Decision

If Approved

If Rejected

Full Code

Sample Output

Why This Pattern Matters

Taking It Further

Wrapping Up

Running Nvidia Nemotron on LangChain via OpenRouter

What Are We Building?

Prerequisites

Step 1 — Get Your OpenRouter API Key

Step 2 — Set Up Your Project

Step 3 — Install Dependencies

Step 4 — Store Your API Key

Step 5 — Choose a Nemotron Model

Step 6 — Write Your Agent

How It Works

Step 7 — Run It

Step 8 — Add More Tools

Common Errors & Fixes

Project Structure

Next Steps

Using Groq API with OpenAI Agents SDK

What Is the OpenAI Agents SDK?

What Is Groq?

Prerequisites

Installation

Project Structure

The Wrong Way (and Why It Fails)

The Correct Approach

Why AsyncOpenAI and Not OpenAI?

Choosing the Right Groq Model

Running the Script

Key Takeaways

What to Build Next

Multithreading in Rust (Beginner Guide )

What is Multithreading?

Real-Life Programming Example

Important Terms

The Basic Idea

Our Beginner Example

Full Code Example

Step-by-Step Explanation

1. Creating the Queue

2. Sharing the Queue

Arc

Mutex

3. Creating Workers

4. Waiting for Jobs

5. Sending Jobs

6. Workers Process Jobs

7. Simulating Work

8. Closing the Queue

Example Visualization

Step 4: Build the Tool with `ToolRuntime`

What makes `ToolRuntime` special?

Step 5: Create the Agent with `context_schema`

`Arc`

`Mutex`

Step 2: Create `state.rs`

Step 3: Create `models.rs`

Why `Serialize`?

Why `Deserialize`?

Why `FromRow`?

Step 4: Create `db.rs`

Step 5: Create `handlers.rs`

`State(state): State<AppState>`

`Json(payload): Json<CreateUser>`

`Path(id): Path<i64>`

`.bind()`

`fetch_one`

`fetch_all`

`fetch_optional`

`.execute()`

Step 6: Create `main.rs`

Understanding `main.rs`

Why We Did Not Put Everything in `main.rs`

Tool #1 — `Arc<T>`: Shared Ownership Across Threads

Tool #2 — `State<T>`: Axum's Dependency Injection

Tool #3 — `Mutex<T>`: Exclusive Access for Writes

Tool #4 — `RwLock<T>`: Many Readers, One Writer

`std::sync` vs `tokio::sync` — Which Should You Use?

`Cargo.toml`

`main.rs`

❌ Forgetting `.with_state()`

❌ Using `Rc<T>` instead of `Arc<T>`

❌ Holding `std::sync::Mutex` across `.await`

❌ `RwLock` write starvation

1. The Simplest Error: Return a `StatusCode`

5. Converting `?` Errors with `From`

6. Using `anyhow` for Quick Prototyping

7. Handler-Level Error Handling with `HandleError`