Cassiano Aquino

Transparent agents

Sun, 26 Apr 2026 09:00:00 +0000

Hello everyone! Has been a long time since I last posted here, but hey! as they say better late than never!

As many of you can imagine, based on my content, I’ve always been a homelab enthusiast, and the last addition to my homelab was a DGX Spark from Nvidia.

I remember since the first time I saw a computer the first thing that came to my mind was:

How can I make something like this? How does this computer-thing works? How can I make it do what I want?

And this is what pushed me to learn about things, how to build them, and obviously it could not be different when we talk about AI.

I see all these big companies doing fun things and I was thinking how could I do something similar? How can I make the user experience better? More powerful without requiring the user to install a lot of things on their machines.

From my previous experience I was thinking about transparent proxies and how they work and then I had the idea:

What if we could make a transparent proxy that has an agent on it?

And here we are! Let me share with you how the concept works.

The reason for this whole pattern is simple: every chat client I already use speaks the OpenAI Chat Completions API, Open WebUI, Cursor, the OpenAI SDK, n8n’s HTTP node, all of them. None of them speak any “agent protocol” because there isn’t one yet. So whatever I build has to look like a model from the wire, and still behave like an agent inside.

I’m calling this a transparent agent. The transparent proxy in HTTP is the same idea: a proxy that sits between client and origin and intercepts traffic without the client having to know it’s there. Squid, HAProxy, Envoy, NGINX all support it. The client doesn’t configure anything special, doesn’t speak a different protocol, just makes the same request it always made, and a proxy in the middle does whatever it does while the client sees a normal response back.

Same idea, one layer up:

A transparent proxy sits between client and origin without requiring client configuration. The client thinks it’s talking directly to the origin; the proxy is invisible to it.

A transparent agent sits between client and model without requiring client configuration. The client thinks it’s talking directly to a chat completions model; the agent is invisible to it.

The agent reaches out to MCP servers, retrieves from a vector store, summarizes old turns, dispatches tools, and assembles a reply. The client posts to /v1/chat/completions, gets a streaming response, and never finds out that the response came from three MCP calls, a vector retrieval, and four turns of tool dispatching. All of the complexity stays on the server.

I tried a few other names before this one stuck. Smart model and wrapped model got the wire surface right but the substance wrong, this thing is an agent, not a model. Agent gateway and agentic gateway are basically taken by agentgateway.dev (a real project, but it does inter-agent A2A/MCP routing, not what I’m building). Wire agent and hosted agent were close but they don’t say what’s invisible, which is the whole point. Transparent agent hangs off a real networking term, and the rest of the post leans on it.

Why a callback proxy is the wrong place

The first version of this in my homelab ran on top of LiteLLM with a callback hook. LiteLLM is a great router, and lets you hook into each request and response with a Python plugin. So the hook intercepted the prompt, did a vector search, injected a <retrieved_context> system message, did a small amount of cleanup on the way out, and called it done.

This works for one round. It breaks the moment the model wants to call a tool, get a result, and call another tool. The hook fires once per HTTP request. The agent loop the OpenAI SDK runs is multiple HTTP requests with tool messages in between. You can fake one round by parsing the response, dispatching the tool yourself, and stitching a follow-up call. At that point you have reimplemented the agent loop inside a callback that wasn’t designed to host one. The state ends up split across the proxy and the client and nobody owns the conversation. In practice that meant Open WebUI re-sending the entire chat history on every turn, including the base64 of any chart we had emitted. We paid for the same image five turns in a row.

The lesson everyone hits eventually: a callback layer is the wrong place to host an agent loop or any meaningful conversational state. You need something that owns the conversation. A callback hook can’t, by design. A transparent agent does, also by design.

What does fit

A small HTTP service that exposes /v1/chat/completions and runs the OpenAI Agents SDK inside. The agent reaches out to MCP servers, retrieves from pgvector, and streams back. From the client’s side it’s still a chat completions endpoint, it points at a model name I picked. Internally it’s a proper agent loop with max_turns=10.

Three pipelines ended up sitting around the agent:

sequenceDiagram
    participant Client as Open WebUI / curl
    participant GW as Transparent agent
    participant Pipe as Pipeline
    participant Agent as Agents SDK + MCPs
    Client->>GW: POST /v1/chat/completions
    GW->>Pipe: run_request(ctx)
    Note over Pipe: cache replay, time injection,<br/>RAG retrieval, rotation
    GW->>Agent: Runner.run_streamed(...)
    Agent-->>GW: text deltas, tool calls, reasoning
    GW->>Pipe: run_chunks(ctx, content)
    Note over Pipe: harmony strip, image substitution
    GW->>Pipe: run_completion(ctx, content)
    Note over Pipe: disclaimer, audit
    GW-->>Client: SSE stream (reasoning then content)

on_request mutates the message list before the agent runs. The conversation cache replays here, retrieved context gets injected, a temporal “today is” line gets added, and rotation drops the oldest pairs if the conversation got too long. on_chunk operates on the assembled assistant text after the agent finishes, before the client sees it. Strip out tokenizer artifacts, swap placeholder strings for image data URLs, redact things you should never have allowed the model to emit in the first place. on_completion is the last gate. Append a disclaimer in the user’s language, write an audit row, send.

Each processor is a Python class, declared by name on the YAML, loaded on the right pipeline. Adding a new one is a one-line registry entry plus a file. Removing one is a one-line config edit. The orchestration code stays small, around 180 lines in the version I have now, and the agent assembly is 90 lines, mostly MCP wiring.

The rule that makes this work: every piece of behavior the client never sees lives in a processor, and every processor either runs before the agent (to shape what the agent sees) or after the agent (to shape what the client sees). The agent stays clean. It runs the loop and that’s it.

What’s next

This post is the opener. The next one is about the conversation cache and KV-prefix stability, since Open WebUI re-sends the full chat history on every turn and the upstream prompt cache invalidates the moment we inject anything the client never saw. The fix is keeping our own canonical view of the conversation, keyed by chat_id, and replaying that instead of what the client sent.

After that, background context compaction. When the cached prefix grows past a threshold, an out-of-band task summarizes the oldest turns into one system message and atomically swaps it in, race-safe via Redis WATCH/MULTI, and the current request never blocks waiting for it.

Then the smaller context-reduction tricks: image substitution at egress so the model never sees base64, placeholder-form caching so we don’t pay for the same chart twice, pair-aligned rotation as a floor when even compaction can’t keep up.

Then the reasoning channel, streaming reasoning tokens before content so the o1-style “thinking” panel works in clients that already render reasoning_content, without any client-side code.

And finally the metrics worth keeping. Token-inflation per processor is the one chart that pays for itself, the rest is usual SRE hygiene.

That is all for this post, it is quite long already! I will be documenting my struggles trying to justify why I spent so much money on a DGX Spark, if this is something that interests you, make yourself at home, you are a welcome guest!

Until next post!

NGINX - CORS with a single if

Fri, 20 Sep 2019 09:00:10 +0000

Hello everyone, long time no see!

Today while working on a PR, I was thinking about how to do CORS without using ifs on NGINX.

If you are not familiar with the reasons to try to avoid using IF, you should take a look at this post

And as usual, map comes at our rescue!

Sadly, I could not remove all IFs from the configuration as I required to use return 204 for the HTTP method OPTIONS.

# Origin whitelist
map $http_origin $allowed_origin {
  default             "false";

  "~*\.?test\.com"    "true";
  "~*\.?example\.com" "true";
}

# Methods
map $request_method $cors {
  "OPTIONS" "${allowed_origin}options";
  "GET"     "${allowed_origin}get";
  "POST"    "${allowed_origin}post";
  default   "${allowed_origin}";
}

# Access-Control-Allow-Origin, if cors true add header.
map $cors $acao {
  "~^true.+?" "$http_origin";
}

# Access-Control-Allow-Credentials, and method is GET/POST/OPTIONS and cors true add header.
map $cors $acac {
  "~^true(options|get|post)" "true";
}

# Access-Control-Allow-Methods, and method is GET/POST/OPTIONS and cors true add header.
map $cors $acam {
  "~^true(options|get|post)" "GET, POST, OPTIONS";
}

# Access-Control-Allow-Headers, and method is GET/POST/OPTIONS and cors true add header.
map $cors $acah {
  "~^true(options|get|post)" "Keep-Alive,User-Agent,ETag,Last-Modified,Vary,If-Modified-Since,Cache-Control,Content-Type";
}

# Access-Control-Max-Age, and method is OPTIONS and cors true add header.
map $cors $acma {
  "trueoptions" "1728000";
}

server {
  listen 80 default_server reuseport;
  expires 24h;

  root /usr/share/nginx/html;
  index index.html index.htm;

  location / {
    add_header 'Access-Control-Allow-Origin' $acao;
    add_header 'Access-Control-Allow-Credentials' $acac;
    add_header 'Access-Control-Allow-Methods' $acam;
    add_header 'Access-Control-Allow-Headers' $acah;
    add_header 'Access-Control-Max-Age' $acma;

    if ($request_method = "OPTIONS") {
      return 204;
    }

    try_files $uri $uri/ =404;
  }
}

One interesting behavior that allows this configuration to work is the fact that add_header will not add headers if the value is empty.

With that in mind, we can use maps without a default value to return empty, which disable headers when they are not necessary.

If you are only serving static assets, all the references to POST can be removed from the configuration as NGINX returns 405 if you try to POST to a static asset.

DNS Round Robin, Consul and Java

Thu, 26 Apr 2018 13:06:22 +0000

Hello everyone! Today, for a change, I will be talking about Consul from Hashicorp instead of NGINX.

I will start with the assumption that you’re aware of what a DNS round robin is and how it’s supposed to work and evolve from there.

I would like to start saying that the “problem” we faced, it’s not related to Consul, but the solution that we looked for was for Consul. Today Rafael while troubleshooting some uneven load distribution across his services, noticed an unexpected behavior.

He had his service correctly configured in Consul, the DNS response from Consul was returning the expected information, but still, only one node was receiving all the requests.

First of all, we started to take a look at java DNS lookup functionality to understand what could cause this issue, especially that both of us saw Greg Banks presentation about Java’s internal DNS caching, which threw us out a little bit.

After doing some tests disabling Java’s internal DNS caching and still having the same issue, we started to break the problem into pieces and test piece by piece, which we should’ve done since the beginning.

We started doing direct DNS queries to Consul to verify that the DNS response was what we expected to be, and it was, so we know that the problem is not Consul.

The next step on our DNS path is the local dnsmasq, which also proved to be working as expected after some simple DNS queries.

Now we were to a point where the DNS path leads us back to Java-land, which we tested before and looked OK.

But just to be sure that Java was the issue and not something else, we tried to use curl, after all the DNS path for both will be the same, and to our surprise, curl had the same behavior that Java had.

After this test, we can safely assume, that what’s causing this issue, it’s not only on Java-land, but we also know that’s NOT on DNS land, so what is the problem? Where to go now?

While trying to search for more information, regarding DNS round robin, we found this post written in 2012 by Daniel Stenberg curl lead developer, which gave us more clues about our problem.

The short version is that most applications used gethostbyname to make DNS requests, which will just give you a randomly ordered list of hosts, which makes DNS round robin work as expected.

But gethostbyname was built to support IPv4 and with IPv6 a new function was required, this is when getaddrinfo comes to play.

The “problem” is that getaddrinfo implements RFC3484 which returns the address always in a specific order, thus breaking DNS round robin, which relied on the random order from gethostbyname.

The idea is that when using getaddrinfo, the application should control the desired behavior, for example, grabbing a random IP from the list, or trying in order until you find one that’s working.

In one hand, this is good as it gives applications more control over the desired behavior, but on the other hand, it makes the behavior inconsistent as each application do whatever they want.

Now that we knew what we were facing, we had some options, change our internal application to control this, or figure out a way to make our application work as it worked on the good old gethostbyname times.

And for our surprise, Consul had a clever workaround for this issue, which limit the size of the answer, and returns a random IP from the list instead of returning the full list and assume that the client application handles it as expected.

This has some trade-offs, for example, DNS TTL needs to be shorter as the DNS RR will rely on returning a different address for each query, which may increase the load on your DNS infrastructure and Consul.

But this will solve our issue until we have a more consistent behavior from applications using getaddrinfo.

For some extra information, you can also take a look at this post at Consul’s mailing list.

That’s all for today!

Thanks

NGINX+ - Replicated Key-Value Store

Tue, 24 Apr 2018 09:00:10 +0000

Today I would like to show how two NGINX+ modules can work together to create a replicated and load balanced RESTfull key-value storage.

If you have any question, not only about NGINX, that you think that I can answer for you, feel free to leave a comment! I’ve been monitoring NGINX questions on Twitter, but let’s say that people have a really bad time asking questions, especially when they have a limited amount of characters to do so.

The current implementation of NGINX+ API has support for a key-value store, but not to replicate it, but nothing that can’t be solved if we use the mirror module.

The concept that I will show below has two NGINX+ nodes, registered in Consul.

The servers have a service called nginx-kv, and tags that identify which node is the master or slave of the cluster.

This is optional and can be done using plain DNS, but I’ve used Consul because it’s another powerful technology that can augment NGINX functionality.

On the master node we have the following configuration:

resolver consul:8600 valid=2s ipv6=off;
resolver_timeout 2s;

keyval_zone zone=default:32k state=default.json;
keyval $arg_text $text1 zone=default;

server {
  status_zone default;

  root /usr/share/nginx/html;

  listen 80 default_server;
  server_name _;

  location /replicated {
    mirror /mirror;
    api write=on;
  }

  location /mirror {
    internal;
    proxy_set_header X-Replication-Source master;
    limit_except GET HEAD {
      proxy_pass http://slave.nginx-kv.service.consul$request_uri;
    }
  }

  location / {
    try_files $uri $uri/ index.html;
  }
}

The API is accessible via the URI /replicated, and every request is mirrored to /mirror.

On the /mirror location, a header X-Replication-Source with the value master is set, and I will get back to it as it’s really important.

And any request that is not GET or HEAD is mirrored via proxy_pass to the slave node.

We have no interest in mirroring GETs and HEADs to the mirror as this would waste resources.

On the slave we have the following configuration:

keyval_zone zone=default:32k state=default.json;
keyval $arg_text $text1 zone=default;

server {
  status_zone default;

  root /usr/share/nginx/html;

  listen 80 default_server;
  server_name _;

  set $mmethod "$http_x_replication_source$request_method";

  if ( $mmethod ~ ^(POST|PUT|DELETE|PATCH)$ ) {
    return 307 http://master.nginx-kv.service.consul$request_uri;
  }

  location /replicated {
    api write=on;
  }

  location / {
    try_files $uri $uri/ index.html;
  }
}

The first thing to note on the slave, we have a variable that we concatenate the header X-Replicated-Source with the request_method, this way if a request comes from the master nginx, it will not be affected by the if clause.

The if clause then checks from any write operations, that is not coming from the master node, and redirect them to the master server.

This is a similar approach to LDAP updateref; the slave server is aware that it’s a slave, and redirect writes to the master.

With this in place, a simple load balancer can be added in front of the two nodes, and reads will be load balanced and writes will be sent to the master server.

I quickly presented this concept at nginx.conf 2017 in Portland, where I said that I would share more information in a blog post, took some time, but here it is!

EDIT 2026-04-24. The industry has largely moved away from the “master/slave” naming I used above. The mechanics of this design are identical whether you call the nodes “master/replica”, “primary/replica”, or “writer/follower”; the technique works the same. I’m leaving the post unchanged to preserve the 2018 voice, but if you’re adapting this for anything new, please adopt a replacement pair.

NGINX+ Automatic PURGE when content is changed

Tue, 17 Apr 2018 09:00:33 +0000

One of the biggest challenges for content caching is the expiration of this content, too short lived and your cache is not effective, too long, and you will serve stale data.

The sweet spot for caching is exactly to cache the content while it’s valid, which is hard as you may not know for how long your content will be valid at the moment that’s being cached. To help with that NGINX+ has a cache purge functionality, that allows applications to send a request to NGINX+ and ask that specific content to be removed from the cache.

This requires extra application logic, which is fine, but sometimes you need to be able to purge content for applications that are not aware of the caching in front of it.

For applications that use the same URIs to read and write data based on methods, for example, let’s imagine that we have a URI /profile/syshero.

If a GET is sent to /profile/syshero, the application will render and serve the output to the client.

If a PUT/POST/DELETE is sent to /profile/syshero, the application will do a write operation and change this content

This concept is similar to how REST API works, which makes this approach compatible with a large number of REST applications.

The desired solution would:

Cache or serve cached content for GET/HEAD requests
Purge cached content for any other HTTP method e.g.: POST, PUT, DELETE, PATCH, MKCOL, etc

The following configuration achieves that by using the NGINX+ mirror module together with the purge option.

resolver consul:8600 valid=2s ipv6=off;
resolver_timeout 2s;

proxy_cache_path /tmp/nginx levels=1:2 keys_zone=default:10m max_size=50m;

upstream backends {
  zone backends 32k;
  server service.consul service=backend resolve;
}

server {
  status_zone default;

  listen 80;
  server_name _;

  root /usr/share/nginx/html;

  add_header X-Cache-Status $upstream_cache_status;

  location / {
    mirror /mirror;
    mirror_request_body off;
    proxy_cache_valid 200 1m;
    proxy_cache default;
    proxy_cache_key $uri;
    proxy_pass http://backends;
  }

  location /mirror {
    internal;
    if ($request_method ~ "HEAD|GET") {
      return 204;
    }
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";
    proxy_cache_purge 1;
    proxy_cache default;
    proxy_cache_key $request_uri;
    proxy_pass http://backends$request_uri;
  }
}

This configuration receives any request to /, forward to the backends servers and also mirrors this request to the location /mirror.

The location /mirror will return a 204 for GET and HEAD methods as we want to avoid duplicating all our requests to the backend, and also to avoid purging the cache on every request, and for any other method that is not GET or HEAD purge the cache for the specific URI.

As can be seen on the following test:

root@host:~# curl -v http://localhost/data 2>&1 | grep X-Cache-Status
< X-Cache-Status: HIT
root@host:~# curl -X POST --data "test=1" -v http://localhost/data 2>&1 | grep X-Cache-Status
root@host:~# curl -v http://localhost/data 2>&1 | grep X-Cache-Status
< X-Cache-Status: MISS
root@host:~# curl -v http://localhost/data 2>&1 | grep X-Cache-Status
< X-Cache-Status: HIT

Simple as that!

One important thing to note is that as you can see, different variables are required on both location blocks as the proxy_cache_key, and why is that? This is necessary because of how the mirror module works. To be able to have the same value on both blocks it was necessary to use $uri and $request_uri.

I would like to thank all of NGINX+ Support team for the constant help and support but especially Dmitry Pryadko that helped me figure our how to filter out methods as limit_except was not working as expected.

Also, I would like to thank Bruno Paiuca for asking this question on twitter which got me thinking about on how to solve this problem.

@nginx you need an option to purge cache after post/put/delete to works with our Rest APIs. proxy_cache_purge_after POST, PUT, DELETE— Bruno Paiuca (@BPaiuca) February 10, 2018

Thanks, everyone! See you next time!

NGINX - Unique Request Identifier

Fri, 13 Apr 2018 10:00:20 +0000

A really useful information to have while debugging applications is an end-to-end request id.

To be able to achieve that you need not only NGINX but also application changes, to forward the ids but also to log them. On this post, I would like to share how to implement the NGINX side.

One way to achieve that is setting a header for both the client side and to the upstream called X-Request-ID for example.

The behavior expect is that, if X-Request-ID is set, NGINX will forward the same value to the next upstream, if the header is not set, NGINX will generate a random request identifier and add it to the request.

To achieve that we use a map configuration as can be seen in the following configuration.

map $http_x_request_id $uuid {
  default   "${request_id}";
  ~*        "${http_x_request_id}";
}

server {
  listen 80;
  server_name _;

  proxy_set_header X-Request-ID $uuid;
  add_header X-Request-ID $uuid;

  location / {
    proxy_pass http://backend.local;
  }
}

On my previous implementation, we used a Lua piece of code to generate the unique request identifier, and this had specific formatting similar to:

12345678-1234-1234-1234-1234

To guarantee backward compatibility, I used an NGINX map to format the $request_id variable to a format that matches my old setup.

map $request_id $formatted_id {
  "~*(?<p1>[0-9a-f]{8})(?<p2>[0-9a-f]{4})(?<p3>[0-9a-f]{4})(?<p4>[0-9a-f]{4})(?<p5>.*)$" "${p1}-${p2}-${p3}-${p4}-${p5}";
}

map $http_x_request_id $uuid {
  default   "${formatted_id}";
  ~*        "${http_x_request_id}";
}

Using map, you can apply regular expressions to variables and transform the variables based on the regular expression.

This is one of the many reasons why I think map is one of the most versatile and powerful configuration options for NGINX.

I hope this helps you!

NGINX+ Chained PURGE

Thu, 12 Apr 2018 17:06:13 +0000

After a long winter, I’m here again to post about my favorite subject, wanna guess? NGINX! (Like it was hard to guess)

I will start with a story, which may or may not be based in real life, you get to choose. Once upon the time, Mr. J worked in a big company that used NGINX as their caching layer.

As the company grew, so their infrastructure, and now they needed to run multiple NGINXs (What’s the plural of NGINX BTW?), and seemed to be an easy task, turned into a complex problem.

Their applications used NGINX as a cache, and now doing cache PURGE was a lot more complex than it was before, as they needed to do it on every NGINX server as the caches were isolated from each other.

Mr. J was also worried about how this would work in the Cloud™, what about Autoscaling Groups?

All that fancy functionalities that I can leverage BUT now it’s much harder to do PURGEs.

How do I keep a list of the servers? Do I need to call the Cloud™ API?

After some research, he had some ideas, one was to use shared storage between the caches, but he felt that this would increase the complexity even more and steered away from this option.

What about using Lua? After some research, he had some issues to overcome.

First, How to maintain a list of the NGINX nodes dynamically.

We have a way to solve this, as we use NGINX+ and Consul, we could use an upstream to have a list of the NGINX servers.

Sadly, Lua has no access to the list of servers in an upstream without extra modules, which almost drove him away from the solution!

After thinking harder, Mr. J didn’t want to add unnecessary modules to his NGINX+, which made him remember that NGINX+ has an API that can be used to query the upstream servers list.

But then, another problem! Lua has no access to external HTTP requests without extra Lua modules!

But this one was easily solved! Lua has a function to do internal HTTP requests, ngx.location.capture(), which will not work to call other external endpoints, but if we join forces between ngx.location.capture and proxy_pass we can make it work.

Mr. J continued to move forward with the mission in his mind of doing it using only what he had available to avoid increasing the complexity of his system.

After a lot of research and hard work (not really, it was done in a couple of hours, but don’t tell anyone.) Mr. J managed to come up with a solution for his problems.

Let’s imagine a simple NGINX+, which works well with a single cache node:

proxy_cache_path /tmp/nginx levels=1:2 keys_zone=default:10m max_size=50m;

upstream backends {
  server service.consul service=backend resolve;
}

server {
  status_zone default;

  listen 80;
  server_name _;

  add_header X-Cache-Status $upstream_cache_status;
  
  location / {
    proxy_cache_valid 200 1m;
    proxy_cache default;
    proxy_cache_key $uri;
    proxy_pass http://backends;
  }

}

On this example, NGINX+ uses Consul to populate the backends upstream server list.

Nothing special here, no PURGE or anything just yet!

Now, to allow PURGE, Mr. J decided to go with an invalid internal domain, and this was the configuration used.

proxy_cache_path /tmp/nginx levels=1:2 keys_zone=default:10m max_size=50m;

upstream backends {
  server service.consul service=backend resolve;
}

map $request_method $purge_method {
  PURGE 1;
  default 0;
}

server {
  status_zone purger;

  listen 80;
  server_name purger.local;

  location / {
    proxy_cache default;
    proxy_cache_key $uri;
    proxy_pass http://backends;
    proxy_cache_purge $purge_method;
  }

}

Basically, to purge any content, he can even use cli tools like curl:

curl -X PURGE -H 'Host: purger.local' http://127.0.0.1/uri/to/purge/index.html

When executing a PURGE, NGINX+ will return a 204 No Content.

But still, Mr. J needed to turn this simple configuration in something that would be aware of other NGINX+ caches, and forward the PURGE requests to the other instances.

Finally Mr. J he had a solution to his problem:

resolver consul:8600 valid=2s ipv6=off;
resolver_timeout 2s;

proxy_cache_path /tmp/nginx levels=1:2 keys_zone=default:10m max_size=50m;

upstream backends {
  zone backends 32k;
  server service.consul service=backend resolve;
}

upstream caches {
  zone caches 32k;
  server service.consul service=cache resolve;
}

lua_package_cpath '/usr/lib/x86_64-linux-gnu/lua/5.1/?.so;;';

server {
  status_zone default;

  listen 80;
  server_name _;

  root /usr/share/nginx/html;

  add_header X-Cache-Status $upstream_cache_status;

  location / {
    proxy_cache_valid 200 1m;
    proxy_cache default;
    proxy_cache_key $uri;
    proxy_pass http://backends;
  }

}

map $request_method $purge_method {
  PURGE 1;
  default 0;
}

server {
  status_zone purger;

  listen 80;
  server_name purger.local;

  allow 127.0.0.1;
  allow 172.16.0.0/24; # NGINX+ Network
  deny all;

  location /api {
    api write=on;
  }
  
  location ~* ^/proxy_to/(?<dest>[^\/]+)/ {
    resolver 1.1.1.1 ipv6=off;
    resolver_timeout 2s;
    proxy_method PURGE;
    proxy_set_header Host 'purger.local';
    proxy_pass http://$dest/;
  }

  location / {
    proxy_cache default;
    proxy_cache_key $uri;
    proxy_pass http://backends;
    proxy_cache_purge $purge_method;
  }

  location ~* ^/purger/(?<purge_uri>.*)$ {
   content_by_lua_block {
      local cjson = require("cjson")
      local caches = cjson.decode(ngx.location.capture('/api/3/http/upstreams/caches/servers').body)
      ngx.say('Purging URI: ' .. ngx.var.purge_uri)
      for k,v in pairs(caches) do
        if v['parent'] ~= nil then
          res = ngx.location.capture('/proxy_to/' .. v['server'] .. '/' .. ngx.var.purge_uri, { share_all_vars =  true })
          ngx.say('Purging server: ' .. v['server'] .. ' (' .. res.status .. ')')
        end
      end
    }
  }
}

Let’s break these into pieces and explain the important parts, first NGINX+ has an upstream called caches configuration, that’s not used by any proxy_pass:

upstream caches {
  zone caches 32k;
  server service.consul service=cache resolve;
}

This is used as a catalog to allow instances to find each other.

Another important part is to declare where the NGINX+ Lua module will find the cjson module, as Mr. J used Ubuntu, after simply doing an apt-get install lua-cjson, he added the following line to the configuration:

lua_package_cpath '/usr/lib/x86_64-linux-gnu/lua/5.1/?.so;;';

And now it comes the important part, the most complex one:

server {
  status_zone purger;

  listen 80;
  server_name purger.local;

  allow 127.0.0.1;
  allow 172.16.0.0/24; # NGINX+ Network
  deny all;

  location /api {
    api write=on;
  }
  
  location ~* ^/proxy_to/(?<dest>[^\/]+)/ {
    resolver 1.1.1.1 ipv6=off;
    resolver_timeout 2s;
    proxy_method PURGE;
    proxy_set_header Host 'purger.local';
    proxy_pass http://$dest/;
  }

  location / {
    proxy_cache default;
    proxy_cache_key $uri;
    proxy_pass http://backends;
    proxy_cache_purge $purge_method;
  }

  location ~* ^/purger/(?<purge_uri>.*)$ {
   content_by_lua_block {
      local cjson = require("cjson")
      local caches = cjson.decode(ngx.location.capture('/api/3/http/upstreams/caches/servers').body)
      ngx.say('Purging URI: ' .. ngx.var.purge_uri)
      for k,v in pairs(caches) do
        if v['parent'] ~= nil then
          res = ngx.location.capture('/proxy_to/' .. v['server'] .. '/' .. ngx.var.purge_uri, { share_all_vars =  true })
          ngx.say('Purging server: ' .. v['server'] .. ' (' .. res.status .. ')')
        end
      end
    }
  }
}

When any content needs to be purged on all nodes, a PURGE request to /purger/index.html should be issued on using the host purger.local.

This will trigger the Lua code running on this location, that will call NGINX+ API and fetch a list of servers on the upstream caches.

For each server on the upstream list, Lua will execute an internal ngx.location.capture() to a proxying location, that will then send the request to the destination server. And here it’s the solution in action:

NGINX+ register themselves to Consul as the service named cache, and they are immediately available to NGINX+ cluster to be used as servers on the upstream configuration.

With this solution, the PURGE request can be sent to any NGINX+ server, and it will forward the PURGE request to all other NGINX+ nodes in the pool.

And Mr. J lived happily ever after.

I hope that Mr. J adventure helps you solve your caching issues!

See you next time!

EDIT 2026-04-24. The Lua code above calls /api/3/http/upstreams/caches/servers. Since this post was written, NGINX+ has iterated on its API (current stable is v8+). Older version paths still work because NGINX+ keeps backward compatibility on the versioned prefix, but if you’re authoring new config you should point at the current version available on your build. Check location /api { api write=on; } output at /api for the versions it advertises.

Thinking outside of the box with NGINX series - proxy_cache_bypass command

Wed, 29 Jun 2016 12:31:23 +0000

Hello, everyone! Time to get back to our series of posts about NGINX!

This time, let’s talk about an old friend, the proxy_cache_bypass command, which we used multiple times in my examples, but I never dedicated a post to it, so it’s time to fix this error! At first glimpse, proxy_cache_bypass feels like a simple command, one where you can bypass caching when necessary, but after reading the documentation with more attention, there was a piece of it that caught my attention.

Note that the response from the back-end is still eligible for caching.

So basically proxy_cache_bypass not only allows you to bypass the cache but also will update our cache with the new file working similarly to a cache purge/refresh functionality.

If you want to not update cached files, you should use proxy_no_cache instead, which will have the desired behavior.

Let’s imagine that you want to bypass your cache when the requests are from your office, to do this you can use the geo module together with proxy_cache_bypass, and as a bonus, the cache will be updated as your office browse through your website.

geo $office_networks {
  192.168.0.0/24  1;
}

server {
  listen 80;
  location / {
    proxy_cache_bypass $office_networks;
    proxy_cache_valid any 5m;
    proxy_cache mycache;
    proxy_pass http://my_backends;
  }
}

Another really useful feature of proxy_cache_bypass is that you can pass multiple variables as an argument to it and if any is set it will enable the bypass action.

Some other posts I did that I used proxy_cache_bypass to update our cache:

See you in the next post!

Thanks!

imapfilter - cleaning up your mailbox and Gmail tricks

Sun, 19 Jun 2016 14:03:35 +0000

Hello friends, For the ones of you that do not know imapfilter, you should check it out, but basically, imapfilter is an IMAP client where you can write a set of rules and apply this rules to your mailbox.

imapfilter rules are written in Lua, a really simple and powerful programming language. To start you should create a folder in your home directory called imapfilter, to do so you use the following command:

mkdir ~/.imapfilter

The configuration file should be saved at ~/.imapfilter/config.lua, after having this configuration file in place, just by running imapfilter will be enough to have your configuration executed.

To make things a little bit more interesting, let’s dissect my imapfilter configuration, where I will explain some basic features and some Gmail particularities that you should be aware if you use it.

Let’s start with some basic options that I use, and I will explain why.

options.timeout = 1200
options.create = true
options.subscribe = true
options.expunge = true

options.timeout: will specify a timeout for imapfilter to wait for the IMAP server response, if you have huge mailboxes OR if you’re planning to use the special “All mail” folder in Gmail, it’s a good idea to have a big timeout as operations may take a while.
options.create: this will create folders that you reference in the configuration if they don’t exist.options.subscribe: this will subscribe to the created folders, basically when you create a folder does not mean that it needs to appear on the list, this will make it appear.
options.expunge: deleting messages in folders just mark this messages for deletion, moving the messages to trash, this will remove deleted messages, this behavior can be different based on IMAP server configuration, this is the most common configuration thou.

Now let’s define our account login options.

account1 = IMAP {
  server = "imap.gmail.com",
  username = "your-login@your-domain.com",
  password = "your-password",
  ssl = "auto"
}

This block will create an object called account1, which represents our mail account.

It’s a self-explanatory block, but I do have a remark if you use 2-factor authentication on google you need to generate an application password and put it here as your password will not work.

Now, let’s start to see some basic rules I use, you will need to change the examples to match your needs, as this one was made based on my personal needs.

archive_read_older = 30
print("Archiving read messages on INBOX unflagged and older than ".. archive_read_older .. " days.")
messages = account1["INBOX"]:is_seen() * account1["INBOX"]:is_unflagged() * account1["INBOX"]:is_older(archive_read_older)
messages:delete_messages()

On this block, I’ve created a code that, in the case of Gmail, archives read and unflagged messages older than a specified period, for example in this example 30 days.

For Gmail, the function delete_messages() archive instead of delete, keep this in mind while doing your configuration.

cal_delete_older  = 90
print("Removing calendar messages older than ".. cal_delete_older .. " days.")
messages = account1["[Gmail]/All Mail"]:contain_field("sender", "calendar-notification@google.com") * account1["[Gmail]/All Mail"]:is_older(cal_delete_older)
messages:move_messages(account1["[Gmail]/Trash"])

Now we will remove meeting invites older than 90 days, don’t worry if you accepted, it will be on your calendar and will not be deleted.

Note as we want to delete this messages, instead of using delete_messages() we are moving the messages to the Trash folder on Gmail.

Now let’s say we want to delete messages from some senders and based on some subjects, instead of having individual code for each, it’s simpler to use arrays to do it.

senders = {
  "spammer@spammerdomain.com", "youtube.com", "Mailer Delivery System"
}

subjects = {
  "out of office", "AFK", "Sick"
}

for sender = 1, #senders do
  print("Removing messages from " .. senders[sender])
  messages = account1["[Gmail]/All Mail"]:contain_from(senders[sender])
  messages:move_messages(account1["[Gmail]/Trash"])
end

for subject = 1, #subjects do
  print("Removing messages with subject " .. subjects[subject])
  messages = account1["[Gmail]/All Mail"]:contain_subject(subjects[subject])
  messages:move_messages(account1["[Gmail]/Trash"])
end

Again we are moving to Trash, as we want to delete this messages.

Now let’s clean up some folders where I store automated emails.

folders = {
  "Monitoring/Crons",
  "Monitoring/Nagios"
}

for folder = 1, #folders do
  print("Emptying folder " .. folders[folder])
  messages = account1[folders[folder]]:select_all()
  messages:move_messages(account1["[Gmail]/Trash"])
end

And to finish things up, we need to delete messages on our Trash by using the following code.

print("Emptying trash folder.")
messages = account1["[Gmail]/Trash"]:select_all()
messages:delete_messages()

One thing that I like to do is to move messages older than a specific period out of my INBOX to a “Cleanup” folder.

cleanup_older = 30
print("Moving messages older than ".. cleanup_older .. " on INBOX to Cleanup.")
messages = account1["INBOX"]:is_older(cleanup_older)
messages:move_messages(account1["Cleanup"])

All these examples should be put on the same file, called ~/.imapfilter/config.lua, or you can use includes if you want, but now you have a good baseline on how to clean up your mailbox using imapfilter.

EDIT 2026-04-24. Changed ssl = "tls1" to ssl = "auto" in the account block. When this post was written TLSv1.0 was still common, but Gmail and most other IMAP providers have long since required TLSv1.2+. Leaving "tls1" in a 2026 config means the connection will fail to negotiate.

Thanks!

See you on the next post!

Thinking outside of the box with NGINX series - map command

Sat, 18 Jun 2016 14:41:20 +0000

I don’t think this is thinking outside the box, but I could not do a series of posts about useful commands without talking about map, arguably one of the most useful commands on NGINX, especially that I’m sure map will be used in most of our posts. You should think about map as a “switch” statement like many programming languages have, it’s how you will be able to take advantage of it.

Basically, the syntax for map is the following:

map $variable_to_evaluate $return_variable { 
    value_to_match value_to_return; 
    default value_to_return_by_default;
}

Where the variable_to_evaluate can be ANY variable accessible by NGINX, which includes HTTP headers, Cookies, etc.

You can think of map as a good substitute for most “ifs” that you plan to use, especially considering that if is evil, basically map is a safe replacement for if in most of the situations.

Let’s review our rate limiting example that we used geo to create a whitelist, now we will use map to do the same thing, if the client sends a cookie called “whitelistrl”, he will bypass the rate limiting, but remember, this is not a good idea for rate limiting control as cookies can be easily injected to any HTTP request.

upstream production {
  server 192.168.0.1:80;
  server 192.168.0.2:80;
}

limit_req_zone $limit_var zone=limit_default:10m rate=10r/s;

map $http_cookie $limit_var {
  default $binary_remote_addr;
  ~whitelistrl "";
}

server {
  listen 80;
  location / {
    limit_req zone=limit_default burst=10;
    proxy_pass http://production;
  }
}

Another functionality is that map can be nested, one map can call another map or even combine geo/map/split_clients.

Let’s try another example, what about using map and geo to allow us to only whitelist clients from our customer network that contains the whitelistrl cookie? Sounds like fun!

upstream production {
  server 192.168.0.1:80;
  server 192.168.0.2:80;
}

limit_req_zone $limit_var zone=limit_default:10m rate=10r/s;

map $http_cookie $limit_var {
  default $binary_remote_addr;
  ~whitelistrl $network_var;
}

geo $network_var {
  default $binary_remote_addr;
  200.200.200.0/24 "";
}

server {
  listen 80;
  location / {
    limit_req zone=limit_default burst=10;
    proxy_pass http://production;
  }
}

One thing to note thou, the order of the nesting matters, map accepts nesting other commands, but this is not true for all commands, for example, if we had tried to call map from geo, it was not going to work, so always test before deploying to production!

Also, you can see examples of map usage in posts right here on my blog!

Some examples are:

See you on the next post!

If you have any question or suggestion, use the Ask-O-matic link on the top of the page.

Thanks!