<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Redis with Raphael De Lio - Medium]]></title>
        <description><![CDATA[Let&#39;s learn Redis together! - Medium]]></description>
        <link>https://medium.com/redis-with-raphael-de-lio?source=rss----a29f9dbf6d82---4</link>
        <image>
            <url>https://cdn-images-1.medium.com/proxy/1*TGH72Nnw24QL3iV9IOm4VA.png</url>
            <title>Redis with Raphael De Lio - Medium</title>
            <link>https://medium.com/redis-with-raphael-de-lio?source=rss----a29f9dbf6d82---4</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Wed, 18 Nov 2026 02:09:42 GMT</lastBuildDate>
        <atom:link href="https://medium.com/feed/redis-with-raphael-de-lio" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[OpenClaw Is Going Enterprise (RFC 27) + Redis Agent File System]]></title>
            <link>https://medium.com/redis-with-raphael-de-lio/openclaw-is-going-enterprise-rfc-27-redis-agent-file-system-dfe256c3b12f?source=rss----a29f9dbf6d82---4</link>
            <guid isPermaLink="false">https://medium.com/p/dfe256c3b12f</guid>
            <category><![CDATA[building-with-redis]]></category>
            <category><![CDATA[redis-agent-file-system]]></category>
            <category><![CDATA[redis]]></category>
            <category><![CDATA[openclaw]]></category>
            <category><![CDATA[ai-engineering]]></category>
            <dc:creator><![CDATA[Raphael De Lio]]></dc:creator>
            <pubDate>Fri, 28 Aug 2026 21:18:45 GMT</pubDate>
            <atom:updated>2026-08-28T21:18:45.170Z</atom:updated>
            <content:encoded><![CDATA[<blockquote>This blog post is also available as video. Watch it <a href="https://www.youtube.com/watch?v=LfdsN1qcekY">here</a>.</blockquote><p>As a Forward Deployed Engineer, I am working on how OpenClaw could support thousands of people inside an enterprise.</p><p>OpenClaw was originally designed around a personal assistant, where one gateway serves one person or a small trusted team. Everyone inside that environment shares the same trust boundary, so the gateway can own the runtime, connections, and state for the group.</p><p>An enterprise deployment changes those assumptions. Tenants need clear boundaries, platform changes need controlled authorization, and user state needs to survive when the compute handling a request is released.</p><p><a href="https://medium.com/redis-with-raphael-de-lio/separating-openclaws-compute-from-state-with-redis-agent-file-system-1a54824f8792">The prototype I built</a> focused on that state problem. <a href="https://github.com/redis/agent-filesystem">Redis Agent File System</a>, or AFS, kept user workspaces in Redis while Kubernetes pods were released and reused. It demonstrated that regular workspace files could remain available when a returning user received a different pod.</p><p><a href="https://github.com/openclaw/rfcs/blob/main/rfcs/0027-openclaw-enterprise.md">RFC 0027</a> describes the broader enterprise architecture around tenants, Agents, access, deployments, and audit records. AFS is not part of the RFC. I am mapping the prototype onto the boundaries proposed by the RFC to understand where persistent workspaces could fit.</p><h3>The proposed architecture</h3><p>The proposal introduces a shared management layer above isolated tenant environments. That layer is the OpenClaw Controller, or OCC. It manages OpenClaw resources and their lifecycle state, authorizes operations, coordinates deployments, selects configured integrations, and produces audit records.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*JH1duJqY-gwxGtQlciw5-w.png" /></figure><p>An OpenClaw Namespace is the tenant boundary. In the target use case, a Namespace would most likely represent a customer or team, although the RFC does not require that mapping. OCC manages a dedicated Namespace gateway for Namespace local Channel and Agent runtime traffic. A backing Kubernetes namespace provides an infrastructure boundary for the tenant workloads.</p><p>An Installation is the outer administrative boundary for an OpenClaw Enterprise deployment. A Namespace scopes tenant resources and identities. An Agent is the stable resource that an author configures and deploys. Each deployment creates an immutable AgentRevision containing the approved configuration and runtime choices for that version.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*n4mzwIsTyhvZCsNxuNNsRA.png" /></figure><p>The user ID and workspace ID used by the prototype are not a tenant model. They do not prove ownership or establish who may create, update, deploy, or inspect an Agent. Those decisions belong to the enterprise authorization layer.</p><p>The Namespace mapping also affects compute. Assigning one Namespace to every end user would retain one dedicated gateway for every user, including users who are inactive. Mapping a Namespace to a customer or team allows its users and workspaces to be authorized within a shared tenant boundary.</p><p>OCC coordinates OpenClaw resources while the surrounding systems retain their existing authority. Kubernetes schedules workloads and enforces its infrastructure controls. The identity provider authenticates callers. OCC owns OpenClaw Channel and Secret records, while the external messaging and secret systems own their provider resources, secret values, reusable credentials, APIs, and authorization decisions.</p><p>The RFC was accepted on August 1, 2026. As of August 28, 2026, its <a href="https://github.com/openclaw/rfcs/issues/57">public implementation tracker</a> remains open, and the RFC lists the OCC API contracts and implementation as future work.</p><h3>Controlled Agent deployments</h3><p>Under this model, deploying an Agent becomes a controlled platform operation. The platform separates identity verification, tenant admission, resource authorization, workload creation, isolation, and runtime routing.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ll2vIFP5EZJUuwbB-rSiHw.png" /></figure><p>A deployment follows this sequence:</p><ol><li>An external identity provider authenticates the person or API client making the request. The OpenClaw Access Gateway verifies that identity evidence and admits the exact Installation and Namespace.</li><li>OCC authorizes the requested action and every protected reference, including the Agent configuration, messaging Channels, Secrets, Harness, and SandboxPolicy.</li><li>OCC records the admitted choices as an immutable AgentRevision, including the selected compute and sandbox implementations.</li><li>The compute integration creates a nonserving candidate workload with the Agent’s stable WorkloadIdentity. Its Harness remains stopped while the sandbox integration establishes and verifies containment.</li><li>OCC prepares the Namespace gateway route, requires the previous revision’s Agent process to stop, records the candidate as active, and permits its Harness to start. The gateway sends traffic only after the active revision reports that it is ready.</li></ol><p>Authentication does not grant permission to deploy an Agent, and admission to a Namespace does not grant access to every resource inside it. OCC still checks the caller, action, resource, role bindings, restrictions, and referenced objects.</p><p>The workload identity is also separate from the identity of the person who deployed it. On Kubernetes, a dedicated ServiceAccount and short lived pod token back that identity. The workload receives the permissions assigned to the Agent and does not inherit the deployer&#39;s permissions.</p><p>Secrets follow the same authority boundary. An OpenClaw Secret is an opaque reference to data held by an external secret system. A SecretBroker mediates the authorized operation, and a selected SecretDriver communicates with the external provider without exposing its reusable backend credentials or underlying secret value to the Agent workload.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*gAcTGaWj_RfJc6wOMqct_g.png" /></figure><p>OCC records the deployment state and audit evidence. Kubernetes remains responsible for scheduling and execution, while external providers continue authorizing operations against their own resources.</p><h3>Separating the gateway from execution</h3><p>The Namespace gateway and the workloads created from Agent revisions have separate lifecycles. The gateway can continue handling Namespace local runtime traffic while Agent workloads are created, replaced, or removed.</p><p>This separation matters to the prototype because its current assignment path starts a complete OpenClaw gateway inside every assigned warm pod. In the final benchmark configuration, ten sequential assignment and release cycles produced a mean assignment time of 6.93 seconds with one small workspace and one active environment at a time. Gateway initialization averaged 5.638 seconds, making it the largest measured phase. These figures do not describe concurrent performance or production percentiles.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*3uFO_YJQEmV1Ff3UAEPeqQ.png" /></figure><p>Keeping the Namespace gateway available while assigning only remote execution could remove gateway initialization from that request path. This remains an architectural inference because the public OCC tracker remains open and OpenClaw does not ship this warm Kubernetes integration.</p><p>OpenClaw already contains two components that cover parts of this model. <a href="https://github.com/openclaw/openclaw/blob/main/docs/gateway/multi-tenant-hosting.md">Fleet</a> is an experimental supervisor that runs separate, complete gateway cells for different tenants on one trusted Docker or Podman host. It provides gateway level separation within that host and does not manage a Kubernetes warm pool.</p><p><a href="https://github.com/openclaw/openclaw/blob/main/docs/gateway/cloud-workers.md">Cloud Workers</a> provide the relevant execution boundary. The gateway retains the transcript, provider credentials, model connection, routing, and last reconciled workspace state while a remote worker runs the Agent loop and its tools. The bundled provider provisions remote compute and synchronizes eligible, size bounded files through a managed Git worktree. It does not assign an existing warm Kubernetes pod or provide a live AFS mount.</p><p>A custom Cloud Worker provider could use that execution boundary to select a compatible pod from the warm pool. This provider does not exist today. A warm pod also cannot change its Kubernetes Namespace or ServiceAccount after creation, so the provider would need a pod already compatible with the target tenant and workload identity, an explicit delegation design, or a change to the proposed compute contract.</p><h3>Why AFS still fits</h3><p>The RFC leaves workspace storage and directory synchronization unspecified. It does not select or require AFS, and it does not define a Workspace resource. That open storage boundary allows the target architecture to use AFS as its persistent workspace layer.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*IrAWlc_YyTDOeRHlc-cw2w.png" /></figure><p>AFS stores directory metadata and file contents in Redis, then exposes the workspace through a live FUSE mount. OpenClaw continues using ordinary filesystem operations while the workspace remains independent of the pod running the Agent.</p><p>When a user becomes active, the pool can select a compatible warm pod and mount the authorized workspace into it. When the assignment ends, the workspace is unmounted, disposable state is cleaned, and the pod returns to the pool. The files remain in Redis, so another compatible pod can mount the same workspace later.</p><p>Selecting the workspace at assignment time also keeps user storage outside the pod lifecycle. The pod does not need a user specific volume declared when it is created, and Kubernetes does not need to manage one PersistentVolume and PersistentVolumeClaim for every user. The live mount also avoids copying the complete workspace into the pod before OpenClaw can access it.</p><p>The prototype demonstrated this behavior for regular workspace files. OpenClaw read and wrote them through normal file operations, and those files survived release and reassignment between pods. That result is scoped to the prototype and does not establish general production behavior for AFS.</p><p>Connecting this storage layer to OCC requires an explicit workspace contract. OCC would need a protected reference that maps an authorized Agent or session to an AFS workspace. OCC could then authorize the reference, while AFS provides the approved filesystem to the selected workload. The mutable workspace contents would remain outside the immutable AgentRevision.</p><p>The production integration also needs to align the mount with the RFC security model. The prototype runs a privileged FUSE process beside OpenClaw and gives that process reusable Redis credentials. A production design would need containment that the sandbox integration can verify and credentials scoped to the authorized workspace. Filesystem durability, locking, atomic rename, fsync(), SQLite behavior, cache coherence, concurrent mounts, tenant isolation, and scale still require validation.</p><p>AFS has a clear role in this architecture for persistent regular workspace files. OCC would provide governance and authorization, the worker integration would provide execution, and AFS would keep the authorized files available independently of the selected worker.</p><p>Under the combined design, OCC would coordinate tenant gateways and Agent deployments, a custom Cloud Worker provider would select compatible Kubernetes workers, and AFS would keep user workspaces available independently of those workers.</p><p>RFC 0027 is an accepted architecture. The specific integration of OCC, warm Kubernetes workers, and AFS remains a prototype concept that still requires implementation and production validation.</p><p><strong>Stay curious!</strong></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*bx693jvrfFbOBB9j-0Rb6Q.png" /></figure><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=dfe256c3b12f" width="1" height="1" alt=""><hr><p><a href="https://medium.com/redis-with-raphael-de-lio/openclaw-is-going-enterprise-rfc-27-redis-agent-file-system-dfe256c3b12f">OpenClaw Is Going Enterprise (RFC 27) + Redis Agent File System</a> was originally published in <a href="https://medium.com/redis-with-raphael-de-lio">Redis with Raphael De Lio</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Separating OpenClaw’s Compute from State with Redis Agent File System]]></title>
            <link>https://medium.com/redis-with-raphael-de-lio/separating-openclaws-compute-from-state-with-redis-agent-file-system-1a54824f8792?source=rss----a29f9dbf6d82---4</link>
            <guid isPermaLink="false">https://medium.com/p/1a54824f8792</guid>
            <category><![CDATA[redis]]></category>
            <category><![CDATA[openclaw]]></category>
            <category><![CDATA[building-with-redis]]></category>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[ai-engineering]]></category>
            <dc:creator><![CDATA[Raphael De Lio]]></dc:creator>
            <pubDate>Mon, 24 Aug 2026 09:57:23 GMT</pubDate>
            <atom:updated>2026-08-24T09:58:04.520Z</atom:updated>
            <content:encoded><![CDATA[<blockquote>This blog post is also available as video. Watch it <a href="https://youtu.be/adolZPF1ZgA?si=jYEsQTHCRWhoksRk">here</a>.</blockquote><p>As part of my first engagement as a Forward Deployed Engineer, I was assigned to a project where thousands of users would each receive an OpenClaw environment.</p><p>OpenClaw is a stateful application. It writes the information it needs between sessions to its home directory. This includes user instructions, skills, artifacts, configuration, session data, identity files, and SQLite databases.</p><p>Keeping one OpenClaw instance running for every user would preserve those files, but it would also reserve compute while most users were inactive. We needed to stop inactive environments and later give returning users access to the same state.</p><h4>Starting with Kubernetes storage</h4><p>The environments were going to run on Kubernetes, with OpenClaw running inside pods. The first storage option to consider was one PersistentVolume for each user, attached to the user’s pod through a PersistentVolumeClaim.</p><p>The volume would survive the pod, so a replacement pod could access the files. The lifecycle created two problems.</p><p>First, the cluster would need a PersistentVolume and PersistentVolumeClaim for every user workspace. At the expected scale, Kubernetes would have to manage a large number of storage objects.</p><p>Second, a pod declares its volumes when it is created. Kubernetes cannot replace one user’s PersistentVolumeClaim with another user’s claim while the pod remains running.</p><p>We could keep a pod and volume reserved for every user, which would retain the idle compute. We could also create a new pod for each active session, which would put pod scheduling, container startup, and storage attachment in the user’s request path.</p><p>The prototype tested another model: a shared pool of running pods with persistent workspaces that could be mounted and unmounted as users became active or inactive.</p><h4>Defining disposable compute</h4><p>This model separates the lifecycle of the OpenClaw process from the lifecycle of the user’s files.</p><p>The environment running OpenClaw can be replaced. The persistent workspace remains available independently from it. When the user returns, another environment mounts the workspace and starts a new OpenClaw process.</p><p>A request in progress, an open connection, a child process, and anything held only in memory disappear when the environment stops. The replacement process can reconstruct only the state that was persisted.</p><p>The prototype therefore had two requirements:</p><p><strong>1.</strong> The workspace had to survive after an OpenClaw environment stopped.<br><strong>2. </strong>A replacement OpenClaw process had to access that workspace through a regular filesystem path.</p><h4>Introducing Redis Agent File System</h4><p>Redis Agent File System, or AFS, is a filesystem layer backed by Redis. It stores directory structure, file metadata, and file contents in Redis, then exposes them through filesystem operations such as open, read, write, rename, and readdir.</p><p>These are POSIX style operations. That describes the interface presented to applications. It does not establish that every POSIX guarantee involving locking, atomicity, cache coherence, and durability has been validated.</p><p>The main unit in AFS is a workspace. Each workspace has an identifier and its own directory tree. The prototype assigned one workspace to each user.</p><pre>user: raphael<br>workspace: ws_9f84653cd1b563af<br><br>workspace/<br>  AGENTS.md<br>  skills/<br>  artifacts/<br>  project/</pre><p>The workspace ID tells AFS which filesystem to open. It does not prove that the requesting user owns the workspace. The application assigning environments still needs authentication, ownership checks, and scoped credentials.</p><p>AFS also supports checkpoints, workspace forks, file history, and configurable file versioning. It exposes an MCP server for agents that access files through tools. I used its filesystem mount because OpenClaw already expects local paths.</p><h4>Mounting AFS through FUSE</h4><p>The prototype ran on Google Kubernetes Engine. Each pod could be assigned to a user, released after inactivity, and reused for a later assignment.</p><p>AFS exposes a live Linux filesystem through FUSE. FUSE allows a user space process to implement a mounted filesystem. OpenClaw can continue using ordinary paths and file operations while the AFS process translates them into reads and writes against Redis.</p><p>The mount does not copy the complete workspace into the container before OpenClaw starts. When OpenClaw lists a directory or reads a file, the operation passes through FUSE. AFS retrieves the required metadata or content and can cache it locally.</p><p>Each pod uses an emptyDir as the local mountpoint:</p><pre>securityContext:<br>  privileged: true<br>volumeMounts:<br>  - name: fuse<br>    mountPath: /dev/fuse<br>  - name: home<br>    mountPath: /home/node/.openclaw<br>volumes:<br>  - name: fuse<br>    hostPath:<br>      path: /dev/fuse<br>      type: CharDevice<br>  - name: home<br>    emptyDir: {}</pre><p>The emptyDir contains the mountpoint and disposable local files. Persistent user files live in AFS. No Kubernetes PersistentVolume is attached for the user workspace.</p><p>The container needs access to /dev/fuse and permission to create the mount. The prototype uses a privileged container. This expands the pod’s security boundary and requires further evaluation for tenant isolation.</p><h4>The resulting architecture</h4><p>The system contains a pool control plane, an AFS control plane, OpenClaw pods, and two Redis Cloud databases.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*k-Ql0NVeVT9HO6OzW1zy3A.png" /></figure><p>The OpenClaw Pool Control Plane is the application built for this prototype. It assigns pods, tracks leases, and releases inactive environments.</p><p>The AFS Control Plane comes from the AFS project. It creates workspaces and manages their metadata. A separate Redis database stores the AFS filesystem data.</p><p>Each OpenClaw pod contains the OpenClaw runtime, the AFS mount executable, and a small mount manager. The mount manager remains running while the pod is available. OpenClaw starts only after a user is assigned and the workspace is ready.</p><p>The second Redis database stores pool state. The pods run in Kubernetes. Redis stores records describing their availability, assignments, and leases.</p><h4>Reserving a pod</h4><p>The Pool Control Plane must prevent two requests from reserving the same pod. The prototype uses a Redis List for the available queue, a Set to prevent duplicate queue entries, Hashes for pod and instance records, a Sorted Set for lease deadlines, and a Stream for lifecycle events.</p><p>An atomic Lua script removes a pod from the available queue and creates its assignment.</p><p>Each instance moves through this state machine:</p><pre>AVAILABLE<br>  to ASSIGNING<br>  to ACTIVE<br>  to RELEASING<br>  to AVAILABLE<br><br>Lifecycle error<br>  to FAILED</pre><p>The Redis reservation and the HTTP call to the mount manager are separate operations. Redis may reserve a pod even if the subsequent mount fails. The ASSIGNING and FAILED states make incomplete lifecycle operations visible to reconciliation.</p><p>The control plane periodically compares its Redis records with the Ready pods reported by Kubernetes. It removes stale queue entries and assignments after pod replacement or pool resizing.</p><h4>Assigning an environment</h4><p>After reserving a pod, the Pool Control Plane sends its mount manager a workspace ID and an instance ID:</p><pre>{<br>  &quot;workspaceId&quot;: &quot;ws_example&quot;,<br>  &quot;instanceId&quot;: &quot;7d0c8dd0-2b94-4f53-88a1-3c62650ca835&quot;<br>}</pre><p>The mount manager performs the assignment in this order:</p><p>1. Lock the pod against another lifecycle operation.<br>2. Confirm that the pod is not already assigned.<br>3. Create the OpenClaw home mountpoint.<br>4. Start the AFS mount process for the selected workspace.<br>5. Wait for Linux to report that the mount is ready.<br>6. Start OpenClaw as an unprivileged user.<br>7. Wait for the OpenClaw readiness endpoint.<br>8. Record the identifiers and process information needed during release.</p><p>The AFS executable is built into the image from a pinned source revision. Its invocation is equivalent to:</p><pre>agent-filesystem-mount \<br>  --redis &quot;$AFS_REDIS_ADDR&quot; \<br>  --user &quot;$AFS_REDIS_USERNAME&quot; \<br>  --password &quot;$AFS_REDIS_PASSWORD&quot; \<br>  --db &quot;${AFS_REDIS_DB:-0}&quot; \<br>  --allow-other \<br>  &quot;$WORKSPACE_ID&quot; \<br>  /home/node/.openclaw</pre><p>Once the mount and OpenClaw readiness check succeed, the control plane marks the assignment as ACTIVE.</p><h4>Releasing an environment</h4><p>Release follows the reverse lifecycle. The mount manager verifies the instance ID, stops OpenClaw, persists the selected state, unmounts AFS, and removes disposable runtime files.</p><p>The Pool Control Plane returns the pod to the available queue only after cleanup succeeds. A failed unmount quarantines the pod so another user cannot inherit the previous workspace.</p><p>Each assignment has a lease deadline in the Redis Sorted Set. Activity extends the deadline. A scheduled process releases expired instances through the same cleanup path as an explicit release.</p><p>The activity signal must represent OpenClaw use. A browser heartbeat proves only that the browser remains connected. A deployment with a custom client should derive activity from authenticated OpenClaw requests or task execution.</p><h4>Deciding what belongs in AFS</h4><p>For the prototype, I mounted the complete ~/.openclaw directory through AFS. This made it possible to test whether OpenClaw’s file state could follow a user between pods.</p><p>The files do not all have the same persistence requirements.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/711/1*CpQDKjoPlmRY4e-j3zTzTQ.png" /></figure><p>Regular files are the clearest fit for AFS. SQLite requires more investigation. It depends on file locking, atomic rename, and fsync() behavior. Storing a SQLite database on the mount does not prove that AFS provides every guarantee SQLite expects during a pod crash, network interruption, or Redis failure.</p><p>The remaining SQLite state needs to be classified. Some data may be disposable or reconstructable. Data that must survive needs storage with the required locking and durability behavior.</p><p>Redis Agent Memory can replace OpenClaw’s long term and session memory capabilities. It does not replace all SQLite backed runtime state. Its coverage and recovery behavior need a separate evaluation.</p><p>The prototype also allows only one active assignment for a workspace. This reduces concurrent writers. It does not validate every cache coherence or failure scenario involving multiple mounts.</p><h4>What the prototype demonstrated</h4><p>I created files through one OpenClaw instance, released the environment, mounted the same workspace into another pod, and read the files again.</p><p>The prototype demonstrated that:</p><ol><li>A workspace can be mounted into an existing OpenClaw pod.</li><li>OpenClaw can use the workspace through normal filesystem operations.</li><li>Files survive release and reassignment to another pod.</li><li>An inactive environment can be released automatically.</li><li>A cleaned pod can serve another user.</li><li>User workspaces do not require individual Kubernetes PersistentVolumes or PersistentVolumeClaims.</li></ol><p>The test did not establish SQLite correctness, safe concurrent mounts, tenant isolation, or operation at the expected production scale. It also did not preserve active requests when a pod stopped.</p><h3>What I will test next</h3><p>The next performance tests should cover concurrent assignment and release across 100 or 1,000 pods. Measurements should separate AFS mount time, OpenClaw startup, control plane work, and release so each source of latency remains visible.</p><p>OpenClaw state should be classified by persistence requirement. SQLite needs tests covering locking, journal modes, atomic rename, and fsync() during pod, node, network, and Redis failures.</p><p>Redis Agent Memory should be evaluated against OpenClaw’s complete long term and session memory behavior. This includes retrieval quality, session continuity, migration, and recovery.</p><p>The security evaluation should cover user authentication, workspace ownership, scoped Redis credentials, cleanup between tenants, and whether privileged FUSE mounts provide an acceptable isolation boundary.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*BZBL4XcMsi2xl5dVB6TcQA.png" /></figure><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=1a54824f8792" width="1" height="1" alt=""><hr><p><a href="https://medium.com/redis-with-raphael-de-lio/separating-openclaws-compute-from-state-with-redis-agent-file-system-1a54824f8792">Separating OpenClaw’s Compute from State with Redis Agent File System</a> was originally published in <a href="https://medium.com/redis-with-raphael-de-lio">Redis with Raphael De Lio</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Reflection on my first year as a Developer Advocate (at Redis)]]></title>
            <link>https://medium.com/redis-with-raphael-de-lio/reflection-on-my-first-year-as-a-developer-advocate-at-redis-8087ae4c2132?source=rss----a29f9dbf6d82---4</link>
            <guid isPermaLink="false">https://medium.com/p/8087ae4c2132</guid>
            <category><![CDATA[developer-advocacy]]></category>
            <category><![CDATA[public-speaking]]></category>
            <category><![CDATA[redis]]></category>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[developer-relations]]></category>
            <dc:creator><![CDATA[Raphael De Lio]]></dc:creator>
            <pubDate>Mon, 03 Nov 2025 22:40:44 GMT</pubDate>
            <atom:updated>2025-11-03T22:42:41.366Z</atom:updated>
            <content:encoded><![CDATA[<p>Today I complete my first year as a developer advocate and to celebrate I&#39;d like to explore one question many have asked me: <strong>What does a developer advocate do?</strong></p><p>It’s a question I asked myself many times over the past year and one I asked countless fellow dev advocates too. Truth is that the answers are never the same. After a year, though, I’m starting to grasp what being a DevRel actually means. At least for me, and at least at Redis.</p><p>If you attended one of my sessions or watched one of my videos this year, you possibly realized that, besides saying my name, I don’t introduce myself. <strong>I don’t tell the crowd who I am, what I’ve worked with, or any other reason they should listen to what I have to say.</strong></p><p><strong>The reason for that is best summarized by three of the most meaningful compliments I received this year:</strong></p><p>1. At Devoxx UK, after hours of chatting at the after-party, someone I’d been talking to realized I was the speaker behind “Rediscovering the Apollo 11 Mission using Spring AI.” He said he hadn’t recognized me but that it was one of the best talks he’d seen at the conference.</p><p>2. At KotlinConf in Copenhagen, during my “Building a Bluesky AI Agent” talk, a few real-time demos failed on stage. Afterward, an attendee told me, “Dude, I could see you’re a real dev and that the talk was very technical.”</p><p>3. At J-Fall in Utrecht, after my talk on probabilistic data structures, someone said that even though it was clear I worked for Redis, the talk wasn’t “selling” Redis at all.</p><p><strong>These moments summarize the three principles that guide everything I do as a DevRel:</strong></p><p>1. <strong>Impact over recognition</strong>: I’m not on stage to talk about myself. People don’t attend my sessions because of who I am. They come to learn something useful. My job is to help engineers solve problems by sharing the lessons I’ve learned while solving my own.</p><p>2. <strong>Expertise shows itself</strong>: I’m a software engineer. That’s my background, my mindset, and my audience. I’ve spent the past decade building software across countries, companies, and industries. That’s the lens through which I connect with other devs.</p><p>3. <strong>Honesty builds trust</strong>: I’m not selling Redis or calling it the perfect solution. I’m here to explore real problems and share real solutions with the community.</p><p>Becoming a DevRel wasn’t something I planned. It evolved naturally. It started in 2022, when I began sharing my knowledge on YouTube and Medium. I didn’t know where it would lead.</p><p>That’s why I rarely talk about developer advocacy or about myself. It’s never been the goal. I’m a software engineer who happens to be a developer advocate, not the other way around.</p><p>This first year taught me that advocacy is about curiosity, empathy, and sharing what you love. Everything I was already doing and can’t wait to keep doing for many years to come. With or without a title.</p><p>Truth is that I don’t talk about Redis because I work for Redis. I was hired by Redis because I talked about Redis. That’s what I’m most proud and grateful for.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Wsm2yNVGtwhMfX547onhMA.png" /></figure><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=8087ae4c2132" width="1" height="1" alt=""><hr><p><a href="https://medium.com/redis-with-raphael-de-lio/reflection-on-my-first-year-as-a-developer-advocate-at-redis-8087ae4c2132">Reflection on my first year as a Developer Advocate (at Redis)</a> was originally published in <a href="https://medium.com/redis-with-raphael-de-lio">Redis with Raphael De Lio</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Semantic Caching with Spring AI & Redis]]></title>
            <link>https://medium.com/redis-with-raphael-de-lio/semantic-caching-with-spring-ai-redis-1bf0db4473d1?source=rss----a29f9dbf6d82---4</link>
            <guid isPermaLink="false">https://medium.com/p/1bf0db4473d1</guid>
            <category><![CDATA[generative-ai-tools]]></category>
            <category><![CDATA[spring-boot]]></category>
            <category><![CDATA[spring-ai]]></category>
            <category><![CDATA[redis]]></category>
            <category><![CDATA[ai]]></category>
            <dc:creator><![CDATA[Raphael De Lio]]></dc:creator>
            <pubDate>Thu, 31 Jul 2025 07:35:33 GMT</pubDate>
            <atom:updated>2025-07-31T07:46:53.449Z</atom:updated>
            <content:encoded><![CDATA[<blockquote><strong>TL;DR:</strong> You’re building a semantic caching system using Spring AI and Redis to improve LLM application performance.</blockquote><blockquote>Unlike traditional caching that requires exact query matches, semantic caching understands the meaning behind queries and can return cached responses for semantically similar questions.</blockquote><blockquote>It works by storing query-response pairs as vector embeddings in Redis, allowing your application to retrieve cached answers for similar questions without calling the expensive LLM, reducing both latency and costs.</blockquote><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*f0R9gBDSJQk8872lh2QMDQ.png" /></figure><h3>The Problem with Traditional LLM Applications</h3><p>LLMs are powerful but expensive. Every API call costs money and takes time. When users ask similar questions like “What beer goes with grilled meat?” and “Which beer pairs well with barbecue?”, traditional systems would make separate LLM calls even though these queries are essentially asking the same thing.</p><p>Traditional exact-match caching only works if users ask the identical question word-for-word. But in real applications, users phrase questions differently while seeking the same information.</p><h3>How Semantic Caching Works</h3><blockquote>Video: <a href="https://www.youtube.com/watch?v=AtVTT_s8AGc&amp;t=1s">What is a semantic cache?</a></blockquote><p>Semantic caching solves this by understanding the <strong><em>meaning</em></strong> behind queries rather than matching exact text. When a user asks a question:</p><ol><li>The system converts the query into a vector embedding</li><li>It searches for semantically similar cached queries using vector similarity</li><li>If a similar query exists above a certain threshold, it returns the cached response</li><li>If not, it calls the LLM, gets a response, and caches both the query and response for future use</li></ol><p>Behind the scenes, this works thanks to vector similarity search. It turns text into vectors (embeddings) — lists of numbers — stores them in a vector database, and then finds the ones closest to your query when checking for cached responses.</p><p>Today, we’re gonna build a semantic caching system for a beer recommendation assistant. It will remember previous responses to similar questions, dramatically improving response times and reducing API costs.</p><p>To do that, we’ll build a Spring Boot app from scratch and use Redis as our semantic cache store. It’ll handle vector embeddings for similarity matching, enabling our application to provide lightning-fast responses for semantically similar queries.</p><h3>Redis as a Semantic Cache for AI Applications</h3><blockquote>Video: <a href="https://www.youtube.com/watch?v=Yhv19le0sBw&amp;t=1s">What&#39;s a vector database</a></blockquote><p>Redis Open Source 8 not only turns the community version of Redis into a Vector Database, but also makes it the fastest and most scalable database in the market today. Redis 8 allows you to scale to one billion vectors without penalizing latency.</p><p>For semantic caching, Redis serves as:</p><ul><li>A vector store using Redis JSON and the Redis Query Engine for storing query embeddings</li><li>A metadata store for cached responses and additional context</li><li>A high-performance search engine for finding semantically similar queries</li></ul><h3>Spring AI and Redis</h3><blockquote>Video: <a href="https://www.youtube.com/watch?v=0U1S0WSsPuE&amp;t=1s">What’s an embedding model?</a></blockquote><p>Spring AI provides a unified API for working with various AI models and vector stores. Combined with Redis, it allows developers to easily build semantic caching systems that can:</p><ul><li>Store and retrieve vector embeddings for semantic search</li><li>Cache LLM responses with semantic similarity matching</li><li>Reduce API costs by avoiding redundant LLM calls</li><li>Improve response times for similar queries</li></ul><h3>Building the Application</h3><p>Our application will be built using Spring Boot with Spring AI and Redis. It will implement a beer recommendation assistant that caches responses semantically, providing fast answers to similar questions about beer pairings.</p><h4>0. GitHub Repository</h4><p>The full application can be found on GitHub</p><p><a href="https://github.com/redis-developer/redis-springboot-resources/tree/main/artificial-intelligence/semantic-caching-with-spring-ai">redis-springboot-resources/artificial-intelligence/semantic-caching-with-spring-ai at main · redis-developer/redis-springboot-resources</a></p><h4>1. Add the required dependencies</h4><p>From a Spring Boot application, add the following dependencies to your Maven or Gradle file:</p><pre>implementation(&quot;org.springframework.ai:spring-ai-transformers:1.0.0&quot;)<br>implementation(&quot;org.springframework.ai:spring-ai-starter-vector-store-redis&quot;)<br>implementation(&quot;org.springframework.ai:spring-ai-starter-model-openai&quot;)</pre><h4>2. Configure the Semantic Cache Vector Store</h4><p>We’ll use Spring AI’s RedisVectorStore to store and search vector embeddings of cached queries and responses:</p><pre>@Configuration<br>class SemanticCacheConfig {<br><br>    @Bean<br>    fun semanticCachingVectorStore(<br>        embeddingModel: TransformersEmbeddingModel,<br>        jedisPooled: JedisPooled<br>    ): RedisVectorStore {<br>        return RedisVectorStore.builder(jedisPooled, embeddingModel)<br>            .indexName(&quot;semanticCachingIdx&quot;)<br>            .contentFieldName(&quot;content&quot;)<br>            .embeddingFieldName(&quot;embedding&quot;)<br>            .metadataFields(<br>                RedisVectorStore.MetadataField(&quot;answer&quot;, Schema.FieldType.TEXT)<br>            )<br>            .prefix(&quot;semantic-caching:&quot;)<br>            .initializeSchema(true)<br>            .vectorAlgorithm(RedisVectorStore.Algorithm.HSNW)<br>            .build()<br>    }<br>}</pre><p>Let’s break this down:</p><ul><li><strong>Index Name</strong>: semanticCachingIdx — Redis will create an index with this name for searching cached responses</li><li><strong>Content Field</strong>: content — The raw prompt that will be embedded</li><li><strong>Embedding Field</strong>: embedding — The field that will store the resulting vector embedding</li><li><strong>Metadata Fields</strong>:</li><li>answer: TEXT field for storing the LLM&#39;s response</li><li><strong>Prefix</strong>: semantic-caching: — All keys in Redis will be prefixed with this to organize the data</li><li><strong>Vector Algorithm</strong>: HSNW — Hierarchical Navigable Small World algorithm for efficient approximate nearest neighbor search</li></ul><h4>3. Implement the Semantic Caching Service</h4><p>The SemanticCachingService handles storing and retrieving cached responses from Redis:</p><pre>@Service<br>class SemanticCachingService(<br>    private val semanticCachingVectorStore: RedisVectorStore<br>) {<br>    private val logger = LoggerFactory.getLogger(SemanticCachingService::class.java)<br><br>    fun storeInCache(prompt: String, answer: String) {<br>        // Create a document for the vector store<br>        val document = Document(<br>            prompt,<br>            mapOf(&quot;answer&quot; to answer)<br>        )<br><br>        // Store the document in the vector store<br>        semanticCachingVectorStore.add(listOf(document))<br>        <br>        logger.info(&quot;Stored response in semantic cache for prompt: ${prompt.take(50)}...&quot;)<br>    }<br><br>    fun getFromCache(prompt: String, similarityThreshold: Double = 0.8): String? {<br>        // Execute similarity search<br>        val results = semanticCachingVectorStore.similaritySearch(<br>            SearchRequest.builder()<br>                .query(prompt)<br>                .topK(1)<br>                .build()<br>        )<br><br>        // Check if we found a semantically similar query above threshold<br>        if (results?.isNotEmpty() == true) {<br>            val score = results[0].score ?: 0.0<br>            if (similarityThreshold &lt; score) {<br>                logger.info(&quot;Cache hit! Similarity score: $score&quot;)<br>                return results[0].metadata[&quot;answer&quot;] as String<br>            } else {<br>                logger.info(&quot;Similar query found but below threshold. Score: $score&quot;)<br>            }<br>        }<br><br>        logger.info(&quot;No cached response found for prompt&quot;)<br>        return null<br>    }<br>}</pre><p>Key features of the semantic caching service:</p><ul><li>Stores query-response pairs as vector embeddings in Redis</li><li>Retrieves cached responses using vector similarity search</li><li>Configurable similarity threshold for cache hits</li><li>Comprehensive logging for debugging and monitoring</li></ul><h4>4. Integrate with the RAG Service</h4><p>The RagService orchestrates the semantic caching with the standard RAG pipeline:</p><pre>@Service<br>class RagService(<br>    private val chatModel: ChatModel,<br>    private val vectorStore: RedisVectorStore,<br>    private val semanticCachingService: SemanticCachingService<br>) {<br>    private val logger = LoggerFactory.getLogger(RagService::class.java)<br><br>    fun retrieve(message: String): RagResult {<br>        // Check semantic cache first<br>        val startCachingTime = System.currentTimeMillis()<br>        val cachedAnswer = semanticCachingService.getFromCache(message, 0.8)<br>        val cachingTimeMs = System.currentTimeMillis() - startCachingTime<br><br>        if (cachedAnswer != null) {<br>            logger.info(&quot;Returning cached response&quot;)<br>            return RagResult(<br>                generation = Generation(AssistantMessage(cachedAnswer)),<br>                metrics = RagMetrics(<br>                    embeddingTimeMs = 0,<br>                    searchTimeMs = 0,<br>                    llmTimeMs = 0,<br>                    cachingTimeMs = cachingTimeMs,<br>                    fromCache = true<br>                )<br>            )<br>        }<br><br>        // Standard RAG process if no cache hit<br>        logger.info(&quot;No cache hit, proceeding with RAG pipeline&quot;)<br>        <br>        // Retrieve relevant documents<br>        val startEmbeddingTime = System.currentTimeMillis()<br>        val searchResults = vectorStore.similaritySearch(<br>            SearchRequest.builder()<br>                .query(message)<br>                .topK(5)<br>                .build()<br>        )<br>        val embeddingTimeMs = System.currentTimeMillis() - startEmbeddingTime<br><br>        // Create context from retrieved documents<br>        val context = searchResults.joinToString(&quot;\n&quot;) { it.text }<br>        <br>        // Generate response using LLM<br>        val startLlmTime = System.currentTimeMillis()<br>        val prompt = createPromptWithContext(message, context)<br>        val response = chatModel.call(prompt)<br>        val llmTimeMs = System.currentTimeMillis() - startLlmTime<br><br>        // Store the response in semantic cache for future use<br>        val responseText = response.result.output.text ?: &quot;&quot;<br>        semanticCachingService.storeInCache(message, responseText)<br><br>        return RagResult(<br>            generation = response.result,<br>            metrics = RagMetrics(<br>                embeddingTimeMs = embeddingTimeMs,<br>                searchTimeMs = 0, // Combined with embedding time<br>                llmTimeMs = llmTimeMs,<br>                cachingTimeMs = 0,<br>                fromCache = false<br>            )<br>        )<br>    }<br><br>    private fun createPromptWithContext(query: String, context: String): Prompt {<br>        val systemMessage = SystemMessage(&quot;&quot;&quot;<br>            You are a beer recommendation assistant. Use the provided context to answer <br>            questions about beer pairings, styles, and recommendations.<br>            <br>            Context: $context<br>        &quot;&quot;&quot;.trimIndent())<br>        <br>        val userMessage = UserMessage(query)<br>        <br>        return Prompt(listOf(systemMessage, userMessage))<br>    }<br>}</pre><p>Key features of the integrated RAG service:</p><ul><li>Checks semantic cache before expensive LLM calls</li><li>Falls back to standard RAG pipeline for cache misses</li><li>Automatically caches new responses for future use</li><li>Provides detailed performance metrics including cache hit indicators</li></ul><h3>Running the Demo</h3><p>The easiest way to run the demo is with Docker Compose, which sets up all required services in one command.</p><h4>Step 1: Clone the repository</h4><pre>git clone https://github.com/redis-developer/redis-springboot-resources.git<br>cd redis-springboot-resources/artificial-intelligence/semantic-caching-with-spring-ai</pre><h4>Step 2: Configure your environment</h4><p>Create a .env file with your OpenAI API key:</p><pre>OPENAI_API_KEY=sk-your-api-key</pre><h4>Step 3: Start the services</h4><pre>docker compose up --build</pre><p>This will start:</p><ul><li><strong>redis</strong>: for storing both vector embeddings and cached responses</li><li><strong>redis-insight</strong>: a UI to explore the Redis data</li><li><strong>semantic-caching-app</strong>: the Spring Boot app that implements the semantic caching system</li></ul><h4>Step 4: Use the application</h4><p>When all services are running, go to localhost:8080 to access the demo. You&#39;ll see a beer recommendation interface:</p><figure><img alt="Screenshot of a web app titled “Semantic Caching with Spring AI.” It features a Beer Knowledge Assistant chat interface with a welcome message, input box, and “Start New Chat” and “Clear Chat” buttons. The footer displays “Powered by Redis." src="https://cdn-images-1.medium.com/max/1024/0*Fiq0hLEwAAh-Raij.png" /></figure><p>If you click on Start Chat, it may be that the embeddings are still being created, and you get a message asking for this operation to complete. This is the operation where the documents we&#39;ll search through will be turned into vectors and then stored in the database. It is done only the first time the app starts up and is required regardless of the vector database you use.</p><figure><img alt="Popup message stating that embeddings are still being created (14,472 of 20,000 completed), with an estimated duration of three minutes and a “Close” button." src="https://cdn-images-1.medium.com/max/554/0*Q31EboPeCOEkT8hB.png" /></figure><p>Once all the embeddings have been created, you can start asking your chatbot questions. It will semantically search through the documents we have stored, try to find the best answer for your questions, and cache the responses semantically in Redis:</p><figure><img alt="Animated screen recording of a user typing “What kind of beer goes well with smoked meat?” into the Beer Knowledge Assistant in the Semantic Caching with Spring AI demo. The interface shows the question being sent, demonstrating semantic search in action." src="https://cdn-images-1.medium.com/max/800/0*6H8Qyn7gZW-fI-dE.gif" /></figure><p>If you ask something similar to a question had already been asked, your chatbot will retrieve it from the cache instead of sending the query to the LLM. Retrieving an answer much faster now.</p><figure><img alt="Animated screen recording showing a user asking a similar follow-up question, “What type of beer is a good combination with smoked beef?” The assistant instantly retrieves a cached answer from Redis, demonstrating faster response through semantic caching." src="https://cdn-images-1.medium.com/max/800/0*qe0eDWFW6VoJHQvM.gif" /></figure><h3>Exploring the Data in Redis Insight</h3><p>RedisInsight provides a visual interface for exploring the cached data in Redis. Access it at localhost:5540 to see:</p><ol><li><strong>Semantic Cache Entries</strong>: Stored as JSON documents with vector embeddings</li><li><strong>Vector Index Schema</strong>: The schema used for similarity search</li><li><strong>Performance Metrics</strong>: Monitor cache hit rates and response times</li></ol><figure><img alt="RedisInsight displaying semantic caching JSON document with cached beer pairing response for “What kind of beer goes well with smoked meat?” query" src="https://cdn-images-1.medium.com/max/1024/1*mXjME1KfaR6i1ZCDpI9wdA.png" /></figure><p>If you run the FT.INFO semanticCachingIdx command in the RedisInsight workbench, you&#39;ll see the details of the vector index schema that enables efficient semantic matching.</p><figure><img alt="RedisInsight showing FT.INFO semanticCachingIdx command results with vector index schema including content, embedding, and answer fields for semantic caching" src="https://cdn-images-1.medium.com/max/1024/1*eCSGHnfvU1obVePLTjQDuA.png" /></figure><h3>Wrapping up</h3><p>And that’s it — you now have a working semantic caching system using Spring Boot and Redis.</p><p>Instead of making expensive LLM calls for every similar question, your application can now intelligently cache and retrieve responses based on semantic meaning. Redis handles the vector storage and similarity search with the performance and scalability Redis is known for.</p><p>With Spring AI and Redis, you get an easy way to integrate semantic caching into your Java applications. The combination of vector similarity search for semantic matching and efficient caching gives you a powerful foundation for building cost-effective, high-performance AI applications.</p><p>Whether you’re building chatbots, recommendation engines, or question-answering systems, this semantic caching architecture gives you the tools to dramatically reduce costs while maintaining response quality and improving user experience.</p><p>Try it out, experiment with different similarity thresholds, explore other embedding models, and see how much you can save on LLM costs while delivering faster responses!</p><h4><strong>Stay Curious!</strong></h4><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=1bf0db4473d1" width="1" height="1" alt=""><hr><p><a href="https://medium.com/redis-with-raphael-de-lio/semantic-caching-with-spring-ai-redis-1bf0db4473d1">Semantic Caching with Spring AI &amp; Redis</a> was originally published in <a href="https://medium.com/redis-with-raphael-de-lio">Redis with Raphael De Lio</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Agent Memory with Spring AI & Redis]]></title>
            <link>https://medium.com/redis-with-raphael-de-lio/agent-memory-with-spring-ai-redis-af26dc7368bd?source=rss----a29f9dbf6d82---4</link>
            <guid isPermaLink="false">https://medium.com/p/af26dc7368bd</guid>
            <category><![CDATA[spring-ai]]></category>
            <category><![CDATA[jvm]]></category>
            <category><![CDATA[spring-boot]]></category>
            <category><![CDATA[redis]]></category>
            <category><![CDATA[kotlin]]></category>
            <dc:creator><![CDATA[Raphael De Lio]]></dc:creator>
            <pubDate>Wed, 16 Jul 2025 20:23:55 GMT</pubDate>
            <atom:updated>2025-09-05T09:57:45.305Z</atom:updated>
            <content:encoded><![CDATA[<h3>Agent Long-term Memory with Spring AI &amp; Redis</h3><blockquote>TL;DR:<br>You’re building an AI agent with memory using Spring AI and Redis.<br><br>Unlike traditional chatbots that forget previous interactions, memory-enabled agents can recall past conversations and facts.<br><br>It works by storing two types of memory in Redis: short-term (conversation history) and long-term (facts and experiences as vectors), allowing agents to provide personalized, context-aware responses.</blockquote><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*PhhkowsmgJOhqac3hrUyeg.png" /></figure><p>LLMs respond to each message in isolation, treating every interaction as if it’s the first time they’ve spoken with a user. They lack the ability to remember previous conversations, preferences, or important facts.</p><p>Memory-enabled AI agents, on the other hand, can maintain context across multiple interactions. They remember who you are, what you’ve told them before, and can use that information to provide more personalized, relevant responses.</p><p>In a travel assistant scenario, for example, if a user mentions “I’m allergic to shellfish” in one conversation, and later asks for restaurant recommendations in Boston, a memory-enabled agent would recall the allergy information and filter out inappropriate suggestions, creating a much more helpful and personalized experience.</p><blockquote>Video: <a href="https://youtu.be/0U1S0WSsPuE">What is an embedding model?</a></blockquote><p>Behind the scenes, this works thanks to vector similarity search. It turns text into vectors (embeddings) — lists of numbers — stores them in a vector database, and then finds the ones closest to your query when relevant information needs to be recalled.</p><blockquote>Video: <a href="https://youtu.be/o3XN4dImESE">What is semantic search?</a></blockquote><p>Today, we’re gonna build a memory-enabled AI agent that helps users plan travel. It will remember user preferences, past trips, and important details across multiple conversations — even if the user leaves and comes back later.</p><p>To do that, we’ll build a Spring Boot app from scratch and use Redis as our memory store. It’ll handle both short-term memory (conversation history) and long-term memory (facts and preferences as vector embeddings), enabling our agent to provide truly personalized assistance.</p><h3>Redis as a Memory Store for AI Agents</h3><blockquote>Video: <a href="https://youtu.be/Yhv19le0sBw">What is a vector database?</a></blockquote><p>In the last 15 years, Redis became the foundational infrastructure for realtime applications. Today, with Redis Open Source 8, it’s committed to becoming the foundational infrastructure for AI applications as well.</p><p>Redis Open Source 8 not only turns the community version of Redis into a Vector Database, but also makes it the fastest and most scalable database in the market today. Redis 8 allows you to scale to one billion vectors without penalizing latency.</p><p>Learn more: <a href="https://redis.io/blog/searching-1-billion-vectors-with-redis-8/">https://redis.io/blog/searching-1-billion-vectors-with-redis-8/</a></p><p>For AI agents, Redis serves as both:</p><ol><li>A short-term memory store using Redis Lists to maintain conversation history</li><li>A long-term memory store using Redis JSON and the Redis Query Engine that enables vector search to store and retrieve facts and experiences</li></ol><h3>Spring AI and Redis</h3><p>Spring AI provides a unified API for working with various AI models and vector stores. Combined with Redis, it allows our users to easily build memory-enabled AI agents that can:</p><ol><li>Store and retrieve vector embeddings for semantic search</li><li>Maintain conversation context across sessions</li><li>Extract and deduplicate memories from conversations</li><li>Summarize long conversations to prevent context window overflow</li></ol><h3>Building the Application</h3><p>Our application will be built using Spring Boot with Spring AI and Redis. It will implement a travel assistant that remembers user preferences and past trips, providing personalized recommendations based on this memory.</p><h4>0. GitHub Repository</h4><p>The full application can be found on GitHub:</p><p><a href="https://github.com/redis-developer/redis-springboot-resources/tree/main/artificial-intelligence/agent-long-term-memory-with-spring-ai">https://github.com/redis-developer/redis-springboot-resources/tree/main/artificial-intelligence/agent-long-term-memory-with-spring-ai</a></p><h4>1. Add the required dependencies</h4><p>From a Spring Boot application, add the following dependencies to your Maven or Gradle file:</p><pre>implementation(“org.springframework.ai:spring-ai-transformers:1.0.0”)<br>implementation(“org.springframework.ai:spring-ai-starter-vector-store-redis”)<br>implementation(“org.springframework.ai:spring-ai-starter-model-openai”)<br><br>implementation(&quot;com.redis.om:redis-om-spring:1.0.0&quot;)</pre><h4>2. Define the Memory model</h4><p>The core of our implementation is the Memory class that represents items stored in long-term memory:</p><pre>data class Memory(<br>  val id: String? = null,<br>  val content: String,<br>  val memoryType: MemoryType,<br>  val userId: String,<br>  val metadata: String = “{}”,<br>  val createdAt: LocalDateTime = LocalDateTime.now()<br>)<br><br>enum class MemoryType {<br>  EPISODIC, // Personal experiences and preferences<br>  SEMANTIC // General knowledge and facts<br>}</pre><h4>3. Configure the Vector Store</h4><p>We’ll use Spring AI’s RedisVectorStore to store and search vector embeddings of memories:</p><pre>@Configuration<br>class MemoryVectorStoreConfig {<br><br>@Bean<br>fun memoryVectorStore(<br>  embeddingModel: EmbeddingModel,<br>  jedisPooled: JedisPooled<br>): RedisVectorStore {<br>  return RedisVectorStore.builder(jedisPooled, embeddingModel)<br>        .indexName(&quot;longTermMemoryIdx&quot;)<br>        .contentFieldName(&quot;content&quot;)<br>        .embeddingFieldName(&quot;embedding&quot;)<br>        .metadataFields(<br>            RedisVectorStore.MetadataField(&quot;memoryType&quot;, Schema.FieldType.TAG),<br>            RedisVectorStore.MetadataField(&quot;metadata&quot;, Schema.FieldType.TEXT),<br>            RedisVectorStore.MetadataField(&quot;userId&quot;, Schema.FieldType.TAG),<br>            RedisVectorStore.MetadataField(&quot;createdAt&quot;, Schema.FieldType.TEXT)<br>        )<br>        .prefix(&quot;long-term-memory:&quot;)<br>        .initializeSchema(true)<br>        .vectorAlgorithm(RedisVectorStore.Algorithm.HSNW)<br>        .build()<br>  }<br>}</pre><p>Let’s break this down:</p><ul><li><strong>Index Name</strong>: longTermMemoryIdx — Redis will create an index with this name for searching memories</li><li><strong>Content Field</strong>: content — The raw memory content that will be embedded</li><li><strong>Embedding Field</strong>: embedding — The field that will store the resulting vector embedding</li><li><strong>Metadata Fields:</strong><br> — memoryType: TAG field for filtering by memory type (EPISODIC or SEMANTIC)<br> — metadata: TEXT field for storing additional context about the memory<br> — userId: TAG field for filtering by user ID<br> — createdAt: TEXT field for storing the creation timestamp</li><li>memoryType: TAG field for filtering by memory type (EPISODIC or SEMANTIC)<br> — metadata: TEXT field for storing additional context about the memory<br> — userId: TAG field for filtering by user ID<br> — createdAt: TEXT field for storing the creation timestamp</li></ul><h4>4. Implement the Memory Service</h4><p>The MemoryService handles storing and retrieving memories from Redis:</p><pre>@Service<br>class MemoryService(<br>    private val memoryVectorStore: RedisVectorStore<br>) {<br>    private val systemUserId = &quot;system&quot;<br><br>    fun storeMemory(<br>        content: String,<br>        memoryType: MemoryType,<br>        userId: String? = null,<br>        metadata: String = &quot;{}&quot;<br>    ): StoredMemory {<br>        // Check if a similar memory already exists to avoid duplicates<br>        if (similarMemoryExists(content, memoryType, userId)) {<br>            return StoredMemory(<br>                Memory(<br>                    content = content,<br>                    memoryType = memoryType,<br>                    userId = userId ?: systemUserId,<br>                    metadata = metadata,<br>                    createdAt = LocalDateTime.now()<br>                )<br>            )<br>        }<br><br>        // Create a document for the vector store<br>        val document = Document(<br>            content,<br>            mapOf(<br>                &quot;memoryType&quot; to memoryType.name,<br>                &quot;metadata&quot; to metadata,<br>                &quot;userId&quot; to (userId ?: systemUserId),<br>                &quot;createdAt&quot; to LocalDateTime.now().toString()<br>            )<br>        )<br><br>        // Store the document in the vector store<br>        memoryVectorStore.add(listOf(document))<br><br>        return StoredMemory(<br>            Memory(<br>                content = content,<br>                memoryType = memoryType,<br>                userId = userId ?: systemUserId,<br>                metadata = metadata,<br>                createdAt = LocalDateTime.now()<br>            )<br>        )<br>    }<br><br>    fun retrieveMemories(<br>        query: String,<br>        memoryType: MemoryType? = null,<br>        userId: String? = null,<br>        limit: Int = 5,<br>        distanceThreshold: Float = 0.9f<br>    ): List&lt;StoredMemory&gt; {<br>        // Build filter expression<br>        val b = FilterExpressionBuilder()<br>        val filterList = mutableListOf&lt;FilterExpressionBuilder.Op&gt;()<br><br>        // Add user filter<br>        val effectiveUserId = userId ?: systemUserId<br>        filterList.add(b.or(b.eq(&quot;userId&quot;, effectiveUserId), b.eq(&quot;userId&quot;, systemUserId)))<br><br>        // Add memory type filter if specified<br>        if (memoryType != null) {<br>            filterList.add(b.eq(&quot;memoryType&quot;, memoryType.name))<br>        }<br><br>        // Combine filters<br>        val filterExpression = when (filterList.size) {<br>            0 -&gt; null<br>            1 -&gt; filterList[0]<br>            else -&gt; filterList.reduce { acc, expr -&gt; b.and(acc, expr) }<br>        }?.build()<br><br>        // Execute search<br>        val searchResults = memoryVectorStore.similaritySearch(<br>            SearchRequest.builder()<br>                .query(query)<br>                .topK(limit)<br>                .filterExpression(filterExpression)<br>                .build()<br>        )<br><br>        // Transform results to StoredMemory objects<br>        return searchResults.mapNotNull { result -&gt;<br>            if (distanceThreshold &lt; (result.score ?: 1.0)) {<br>                val metadata = result.metadata<br>                val memoryObj = Memory(<br>                    id = result.id,<br>                    content = result.text ?: &quot;&quot;,<br>                    memoryType = MemoryType.valueOf(metadata[&quot;memoryType&quot;] as String? ?: MemoryType.SEMANTIC.name),<br>                    metadata = metadata[&quot;metadata&quot;] as String? ?: &quot;{}&quot;,<br>                    userId = metadata[&quot;userId&quot;] as String? ?: systemUserId,<br>                    createdAt = try {<br>                        LocalDateTime.parse(metadata[&quot;createdAt&quot;] as String?)<br>                    } catch (_: Exception) {<br>                        LocalDateTime.now()<br>                    }<br>                )<br>                StoredMemory(memoryObj, result.score)<br>            } else {<br>                null<br>            }<br>        }<br>    }<br>}</pre><p>Key features of the memory service:</p><ul><li>Stores memories as vector embeddings in Redis</li><li>Retrieves memories using vector similarity search</li><li>Filters memories by user ID and memory type</li><li>Prevents duplicate memories through similarity checking</li></ul><h4>5. Implement Spring AI Advisors</h4><p>We’re going to rely on the Spring AI Advisors API. Advisors are a way to intercept, modify, and enhance AI-driven interactions.</p><p>We will implement two advisors: one for retrieval and another for recorder. These advisors will be plugged in our ChatClient and intercept every interaction with the LLM.</p><p>The retrieval advisor runs before your LLM call. It takes the user’s current message, performs a vector similarity search over Redis, and injects the most relevant memories into the system portion of the prompt so the model can ground its answer.</p><h4>5.1 Advisor for Long-term memory retrieval</h4><p>The retrieval advisor runs before LLM calls. It takes the user’s current message, performs a vector similarity search over Redis, and injects the most relevant memories into the system portion of the prompt so the model can ground its answer.</p><pre>@Component<br>class LongTermMemoryRetrievalAdvisor(<br>  private val memoryService: MemoryService,<br>) : CallAdvisor, Ordered {<br><br>  companion object {<br>    const val USER_ID = &quot;ltm_user_id&quot;   <br>    const val TOP_K = &quot;ltm_top_k&quot;      <br>  }<br><br>  override fun getOrder() = Ordered.HIGHEST_PRECEDENCE + 40<br>  override fun getName() = &quot;LongTermMemoryRetrievalAdvisor&quot;<br><br>  override fun adviseCall(req: ChatClientRequest, chain: CallAdvisorChain): ChatClientResponse {<br>    val userId = (req.context()[USER_ID] as? String) ?: &quot;system&quot;<br>    val k = (req.context()[TOP_K] as? Int) ?: 5<br><br>    val query = req.prompt().userMessage.text<br>    val memories = memoryService.retrieveRelevantMemories(query, userId = userId)<br>      .take(k)<br><br>    val memoryBlock = buildString {<br>      appendLine(&quot;Use the MEMORY below if relevant. Keep answers factual and concise.&quot;)<br>      appendLine(&quot;----- MEMORY -----&quot;)<br>      memories.forEachIndexed { i, m -&gt; appendLine(&quot;${i+1}. ${m.memory.content}&quot;) }<br>      appendLine(&quot;------------------&quot;)<br>    }<br><br>    val enrichedPrompt = req.prompt().augmentSystemMessage { sys -&gt;<br>      val existing = sys.text<br>      sys.mutate()<br>        .text(<br>          buildString {<br>            appendLine(memoryBlock)<br>            if (existing.isNotBlank()) {<br>              appendLine()<br>              append(existing)<br>            }<br>          }<br>        ).build()<br>    }<br><br>    val enrichedReq = req.mutate()<br>      .prompt(enrichedPrompt)<br>      .build()<br><br>    return chain.nextCall(enrichedReq)<br>  }<br>}</pre><h4>5.2 Advisor for Long-term memory recording</h4><p>The recorder advisor runs after the assistant responds. It looks at the last user message and the assistant’s reply, asks the model to extract atomic, useful facts (episodic or semantic), deduplicates them, and stores them in Redis.</p><pre>@Component<br>class LongTermMemoryRecorderAdvisor(<br>  private val memoryService: MemoryService,<br>  private val chatModel: ChatModel<br>) : CallAdvisor, Ordered {<br><br>  data class MemoryCandidate(val content: String, val type: MemoryType, val userId: String?)<br>  data class ExtractionResult(val memories: List&lt;MemoryCandidate&gt; = emptyList())<br><br>  private val extractorConverter = BeanOutputConverter(ExtractionResult::class.java)<br><br>  override fun getOrder(): Int = Ordered.HIGHEST_PRECEDENCE + 60<br>  override fun getName(): String = &quot;LongTermMemoryRecorderAdvisor&quot;<br><br>  override fun adviseCall(req: ChatClientRequest, chain: CallAdvisorChain): ChatClientResponse {<br>    // 1) Proceed with the normal call (other advisors may have enriched the prompt)<br>    val res = chain.nextCall(req)<br><br>    // 2) Build extraction prompt (user + assistant text of *this* turn)<br>    val userText = req.prompt().userMessage.text<br>    val assistantText = res.chatResponse()?.result?.output?.text<br><br>    // 3) Ask the model to extract long-term memories as structured JSON<br>    val schemaHint = extractorConverter.jsonSchema // JSON schema string for the POJO<br>    val extractSystem = &quot;&quot;&quot;<br>            You extract LONG-TERM MEMORIES from a dialogue turn.<br><br>            A memory is either:<br><br>            1. EPISODIC MEMORIES: Personal experiences and user-specific preferences<br>               Examples: &quot;User prefers Delta airlines&quot;, &quot;User visited Paris last year&quot;<br><br>            2. SEMANTIC MEMORIES: General domain knowledge and facts<br>               Examples: &quot;Singapore requires passport&quot;, &quot;Tokyo has excellent public transit&quot;<br><br>            Only extract clear, factual information. Do not make assumptions or infer information that isn&#39;t explicitly stated.<br>            If no memories can be extracted, return an empty array.<br>            <br>            The instance must conform to this JSON Schema (for validation, do not output it):<br>              $schemaHint<br><br>            Do not include code fences, schema, or properties. Output a single-line JSON object.<br>        &quot;&quot;&quot;.trimIndent()<br><br>    val extractUser = &quot;&quot;&quot;<br>            USER SAID:<br>            $userText<br><br>            ASSISTANT REPLIED:<br>            $assistantText<br><br>            Extract up to 5 memories with correct type; set userId if present/known.<br>        &quot;&quot;&quot;.trimIndent()<br><br>    val options: ChatOptions = OpenAiChatOptions.builder()<br>      .responseFormat(ResponseFormat.builder().type(ResponseFormat.Type.JSON_OBJECT).build())<br>      .build()<br><br>    val extraction = chatModel.call(<br>      Prompt(<br>        listOf(<br>          UserMessage(extractUser),<br>          SystemMessage(extractSystem)<br>        ),<br>        options<br>      ),<br>    )<br><br>    val parsed = extractorConverter.convert(extraction.result.output.text ?: &quot;&quot;)<br>      ?: ExtractionResult()<br><br>    // 4) Persist memories (MemoryService handles dedupe/thresholding)<br>    val userId = (req.context[&quot;ltm_user_id&quot;] as? String) // optional per-call param<br>    parsed.memories.forEach { m -&gt;<br>      val owner = m.userId ?: userId<br>      memoryService.storeMemory(<br>        content = m.content,<br>        memoryType = m.type,<br>        userId = owner<br>      )<br>    }<br><br>    return res<br>  }<br>}</pre><h4>6. Plugging the advisors in our ChatClient</h4><p>In our ChatConfig class, we will configure our ChatClient as:</p><pre>    @Bean<br>    fun chatClient(<br>        chatModel: ChatModel,<br>        // chatMemory: ChatMemory, (Necessary for short-term memory)<br>        longTermRecorder: LongTermMemoryRecorderAdvisor,<br>        longTermMemoryRetrieval: LongTermMemoryRetrievalAdvisor<br>    ): ChatClient {<br>        return ChatClient.builder(chatModel)<br>            .defaultAdvisors(<br>                // MessageChatMemoryAdvisor.builder(chatMemory).build(),<br>                longTermRecorder,<br>                longTermMemoryRetrieval<br>            ).build()<br>    }</pre><h4>7. Implement the Chat Service</h4><p>Since the advisors have been plugged in the ChatClient itself, we don’t need to worry about managing memory ourselves when interacting with the LLM. The only thing we need to make sure is that with every interaction we send the expected parameters, namely the session or user ID, so that the advisors know which history to look at.</p><pre>@Service<br>class ChatService(<br>    private val chatClient: ChatClient,<br>    private val shortTermMemoryRepository: ShortTermMemoryRepository,<br>    private val travelAgentSystemPrompt: Message,<br>    private val chatMemoryRepository: ChatMemoryRepository<br>) {<br>    private val log = LoggerFactory.getLogger(ChatService::class.java)<br><br>    fun sendMessage(<br>        message: String,<br>        userId: String,<br>    ): ChatResult {<br>        // Use userId as the key for conversation history and long-term memory<br>        log.info(&quot;Processing message from user $userId: $message&quot;)<br>        val response = chatClient<br>            .prompt(<br>                Prompt(<br>                    travelAgentSystemPrompt,<br>                    UserMessage(message)<br>                )<br>            )<br>            .advisors { it<br>                .param(ChatMemory.CONVERSATION_ID, userId)<br>                .param(&quot;ltm_user_id&quot;, userId)<br>            }<br>            .call()<br><br>        return ChatResult(<br>            response = response.chatResponse()!!<br>        )<br>    }<br><br><br>    fun getConversationHistory(userId: String): List&lt;Message?&gt; {<br>        return chatMemoryRepository.findByConversationId(userId)<br>    }<br><br>    fun clearConversationHistory(userId: String) {<br>        shortTermMemoryRepository.deleteById(userId)<br>        log.info(&quot;Cleared conversation history for user $userId from Redis&quot;)<br>    }<br>}</pre><h4>8. Configure the Agent System Prompt</h4><p>The agent is configured with a system prompt that explains its capabilities and access to different types of memory:</p><pre>@Bean<br>fun travelAgentSystemPrompt(): Message {<br>    val promptText = &quot;&quot;&quot;<br>        You are a travel assistant helping users plan their trips. You remember user preferences<br>        and provide personalized recommendations based on past interactions.<br><br>        You have access to the following types of memory:<br>        1. Short-term memory: The current conversation thread<br>        2. Long-term memory:<br>           - Episodic: User preferences and past trip experiences (e.g., &quot;User prefers window seats&quot;)<br>           - Semantic: General knowledge about travel destinations and requirements<br><br>        Always be helpful, personal, and context-aware in your responses.<br><br>        Always answer in text format. No markdown or special formatting.<br>    &quot;&quot;&quot;.trimIndent()<br><br>    return SystemMessage(promptText)<br>}</pre><h3>Running the Demo</h3><p>The easiest way to run the demo is with Docker Compose, which sets up all required services in one command.</p><h4>Step 1: Clone the repository</h4><pre>git clone https://github.com/redis/redis-springboot-recipes.git<br>cd redis-springboot-recipes/artificial-intelligence/agent-long-term-memory-with-spring-ai</pre><h4>Step 2: Configure your environment</h4><p>Create a .env file with your OpenAI API key:</p><pre>OPENAI_API_KEY=sk-your-api-key</pre><h4>Step 3: Start the services</h4><pre><br>docker compose up — build</pre><p>This will start:</p><ul><li>redis: for storing both vector embeddings and chat history</li><li>redis-insight: a UI to explore the Redis data</li><li>agent-memory-app: the Spring Boot app that implements the memory-aware AI agent</li></ul><h4>Step 4: Use the application</h4><p>When all services are running, go to localhost:8080 to access the demo. You’ll see a travel assistant interface with a chat panel and a memory management sidebar:</p><figure><img alt="Screenshot of the Redis Agent Memory demo web interface. The interface is titled “Travel Agent with Redis Memory” and features two main panels: a “Memory Management” section on the left with tabs for Episodic and Semantic memories (currently showing “No episodic memories yet”), and a “Travel Assistant” chat on the right displaying a welcome message. At the top right, there’s a field to enter a user ID and buttons to start or clear the chat. The interface is clean and styled with Redis branding." src="https://cdn-images-1.medium.com/max/1024/0*klsu9euWPe_R9PMF.png" /></figure><ol><li>Enter a user ID and click “Start Chat”:</li></ol><figure><img alt="Close-up screenshot of the user ID input and chat controls. The label “User ID:” appears on the left with a text input field containing the value “raphael”. To the right are two red buttons labeled “Start Chat” and “Clear Chat”." src="https://cdn-images-1.medium.com/max/363/0*N7NlzI3cb0E4_M73.png" /></figure><p>2. Send a message like: “Hi, my name’s Raphael. I went to Paris back in 2009 with my wife for our honeymoon and we had a lovely time. For our 10-year anniversary we’re planning to go back. Help us plan the trip!”</p><figure><img alt="Animated screen recording of a user sending a message in the Redis Agent Memory demo. The user, identified as “raphael”, types a detailed message into the chat input box: “Hi, my name’s Raphael. I went to Paris back in 2009 with my wife for our honeymoon and we had a lovely time. For our 10-year anniversary we’re planning to go back. Help us plan the trip!” The cursor then clicks the red “Send” button, initiating the interaction with the AI travel assistant." src="https://cdn-images-1.medium.com/max/800/0*U8XvyzKQzrAjO9-0.gif" /></figure><p>The system will reply with the response to your message and, in case it identifies potential memories to be stored, they will be stored either as semantic or episodic memories. You can see the stored memories on the “Memory Management” sidebar.</p><p>On top of that, with each message, the system will also return performance metrics.</p><p>If you refresh the page, you will see that all memories and the chat history are gone.</p><p>If you reenter the same user ID, the long-term memories will be reloaded on the sidebar and the short-term memory (the chat history) will be reloaded as well:</p><figure><img alt="Animated screen recording of the Redis Agent Memory demo after sending a message. The sidebar under “Episodic Memories” now shows two stored entries: one noting that the user went to Paris in 2009 for their honeymoon, and another about planning a return for their 10-year anniversary. The chat assistant responds with a personalized message suggesting activities and asking follow-up questions. The browser page is then refreshed, clearing both the chat history and memory display. After re-entering" src="https://cdn-images-1.medium.com/max/800/0*-sf8JZu--FDNWfzu.gif" /></figure><p>5. If you refresh the page and enter the same user ID, your memories and conversation history will be reloaded</p><figure><img alt="Animated screen recording of a cleared chat session in the Redis Agent Memory demo. The “Episodic Memories” panel still shows two past memories about a trip to Paris. In the chat panel, the message “Conversation cleared. How can I assist you today?” appears, indicating that the short-term memory has been reset. The user is about to start a new conversation. This demonstrates that although the short-term context is gone, the agent retains access to long-term memories, allowing it to respond with" src="https://cdn-images-1.medium.com/max/800/0*U1MH4sjwWI6TRB0g.gif" /></figure><h4>Exploring the Data in Redis Insight</h4><p>RedisInsight provides a visual interface for exploring the data stored in Redis. Access it at localhost:5540 to see:</p><ol><li>Short-term memory (conversation history) stored in Redis Lists</li></ol><figure><img alt="Screenshot of RedisInsight displaying the contents of the conversation:raphael key. The selected key is a Redis list representing a conversation history. On the right panel, the list shows four indexed elements: system prompts defining the assistant’s role and memory access, a user message asking “Where did I go back in 2009?”, and the assistant’s reply recalling a previous trip to Paris. Below this, several memory entries stored as JSON keys are also visible. This illustrates how short-term cha" src="https://cdn-images-1.medium.com/max/1024/0*0TD7r-Yi7vlHOjGs.png" /></figure><p>2. Long-term memory (facts and experiences) stored as JSON documents with vector embeddings</p><figure><img alt="Screenshot of RedisInsight showing a semantic memory stored in Redis. The selected key is a JSON object with the name memory:04d04…. The right panel displays the memory’s fields: createdAt timestamp, empty metadata, memoryType set to “SEMANTIC”, an embedding vector (collapsed), userId set to “system”, and the memory content: “Paris is a beautiful city known for celebrating love”. This illustrates how general knowledge is stored as semantic memory in the AI agent." src="https://cdn-images-1.medium.com/max/1024/0*s3RjoUZyUABVdLDq.png" /></figure><p>3. The vector index schema used for similarity search</p><p>If you run the FT.INFO memoryIdx command in the RedisInsight workbench, you’ll see the details of the vector index schema that enables efficient memory retrieval.</p><figure><img alt="Screenshot of RedisInsight Workbench showing the schema details of the memoryIdx vector index. The result of the FT.INFO memoryIdx command displays an index on JSON documents prefixed with memory:. The schema includes: • $.content as a TEXT field named content • $.embedding as a VECTOR field using HNSW with 384-dimension FLOAT32 vectors and COSINE distance • $.memoryType and $.userId as TAG fields • $.metadata and $.createdAt as TEXT fields This shows how memory data is structured and searchable" src="https://cdn-images-1.medium.com/max/1024/0*fDFErXCAOyqUN8U1.png" /></figure><h4>Wrapping up</h4><p>And that’s it — you now have a working AI agent with memory using Spring Boot and Redis.</p><p>Instead of forgetting everything between conversations, your agent can now remember user preferences, past experiences, and important facts. Redis handles both short-term memory (conversation history) and long-term memory (vector embeddings) — all with the performance and scalability Redis is known for.</p><p>With Spring AI and Redis, you get an easy way to integrate this into your Java applications. The combination of vector similarity search for semantic retrieval and traditional data structures for conversation history gives you a powerful foundation for building truly intelligent agents.</p><p>Whether you’re building customer service bots, personal assistants, or domain-specific experts, this memory architecture gives you the tools to create more helpful, personalized, and context-aware AI experiences.</p><p>Try it out, experiment with different memory types, explore other embedding models, and see how far you can push the boundaries of AI agent capabilities!</p><p>Stay Curious!</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=af26dc7368bd" width="1" height="1" alt=""><hr><p><a href="https://medium.com/redis-with-raphael-de-lio/agent-memory-with-spring-ai-redis-af26dc7368bd">Agent Memory with Spring AI &amp; Redis</a> was originally published in <a href="https://medium.com/redis-with-raphael-de-lio">Redis with Raphael De Lio</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Semantic Search with Spring Boot & Redis]]></title>
            <link>https://medium.com/redis-with-raphael-de-lio/semantic-search-with-spring-boot-redis-ef376bbdb106?source=rss----a29f9dbf6d82---4</link>
            <guid isPermaLink="false">https://medium.com/p/ef376bbdb106</guid>
            <category><![CDATA[semantic-search]]></category>
            <category><![CDATA[database]]></category>
            <category><![CDATA[spring-boot]]></category>
            <category><![CDATA[redis]]></category>
            <category><![CDATA[building-with-redis]]></category>
            <dc:creator><![CDATA[Raphael De Lio]]></dc:creator>
            <pubDate>Tue, 29 Apr 2025 08:41:12 GMT</pubDate>
            <atom:updated>2025-04-30T12:47:31.713Z</atom:updated>
            <content:encoded><![CDATA[<blockquote><strong>TL;DR:<br></strong>You’re building a <strong>semantic search app</strong> using <strong>Spring Boot</strong> and <strong>Redis</strong>.</blockquote><blockquote>Instead of matching exact words, semantic search finds <strong>meaning</strong> using <strong>Vector Similarity Search (VSS)</strong>.</blockquote><blockquote>It works by turning movie synopses into <strong>vectors</strong> with <strong>embedding models</strong>, storing them in <strong>Redis</strong> (as a vector database), and finding the closest matches to user queries.</blockquote><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*AN8WuaKZYxukOJ-o3vKddQ.png" /></figure><blockquote>Video: <a href="https://www.youtube.com/watch?v=o3XN4dImESE">What is semantic search?</a></blockquote><p>A traditional searching system works by matching the words a user types with the words stored in a database or document collection. It usually looks for exact or partial matches without understanding the meaning behind the words.</p><p>Semantic searching, on the other hand, shines because instead of just matching words, it tries to understand the meaning behind what the user is asking. It focuses on the concepts, not just the keywords, making it much easier for users to find what they really want.</p><p>In a movie streaming service, for example, if a movie’s synopsis is stored in a database as <strong>“A cowboy doll feels threatened when a new space toy becomes his owner’s favorite,”</strong> but the user searches for<strong> “jealous toy struggles with new rival,”</strong> a traditional search system might not find the movie because the exact words don’t line up.</p><p>But a semantic a semantic search system can still connect the two ideas and bring up the right movie. It understands the <em>meaning</em> behind your query — not just the exact words.</p><p>Behind the scenes, this works thanks to <strong>vector similarity search</strong>. It turns text (or images, or audio) into vectors — lists of numbers —store them in a vector database and then finds the ones closest to your query.</p><p>Today, <strong>we’re gonna build a vector similarity search app that lets users find movies based on the <em>meaning</em> of their synopsis — not just exact keyword matches</strong>. So that even if they don’t know the title, they can still get the right movie based on a generic description of the synopsis.</p><p>To do that, we’ll build a Spring Boot app from scratch and plug in <strong>Redis OM Spring</strong>. It’ll handle turning our data into vectors, storing them in Redis, and running fast vector searches when users send a query.</p><h4>Redis as a Vector Database</h4><blockquote>Video: <a href="https://www.youtube.com/watch?v=Yhv19le0sBw">What is a vector database?</a></blockquote><p>In the last 15 years, Redis became the foundational infrastructure for realtime applications. Today, with Redis 8, it’s commited to becoming the foundational infrastructure for AI applications as well.</p><p>Redis 8 not only turns the community version of Redis into a Vector Database, but also makes it the fastest and most scalable database in the market today. <strong>Redis 8 allows you to scale to one billion vectors without penalizing latency.</strong></p><p>Learn more: <a href="https://redis.io/blog/searching-1-billion-vectors-with-redis-8/">https://redis.io/blog/searching-1-billion-vectors-with-redis-8/</a></p><h4><strong>Redis OM Spring</strong></h4><p>To allow our users and customers to take full advantage of everything Redis can do — with the speed Redis is known for — we decided to implement <strong>Redis OM Spring</strong>, a library built on top of Spring Data Redis.</p><p>Redis OM Spring allows our users to easily communicate with Redis, model their entities as <strong>JSONs</strong> or Hashes, efficiently query them by levaraging the <strong>Redis Query Engine</strong> and even take advantage of probabilistic data structures such as <strong>Count-min Sketch, Bloom Filters, Cuckoo Filters</strong>, and more.</p><p>Redis OM Spring on GitHub: <a href="https://github.com/redis/redis-om-spring">https://github.com/redis/redis-om-spring</a></p><h4>Dataset</h4><p>The dataset we’ll be looking is a catalog of thousands of movies. Each of these movies has metadata such as its <strong>title</strong>, <strong>cast</strong>, <strong>genre</strong>, <strong>year</strong>, and <strong>synopsis</strong>. The JSON file representing this dataset can be found in the repository that accompanies this article.</p><p>Sample:</p><pre>{<br>  &quot;title&quot;: &quot;Toy Story&quot;,<br>  &quot;year&quot;: 1995,<br>  &quot;cast&quot;: [<br>   &quot;Tim Allen&quot;,<br>   &quot;Tom Hanks&quot;,<br>   &quot;Don Rickles&quot;<br>  ],<br>  &quot;genres&quot;: [<br>   &quot;Animated&quot;,<br>   &quot;Comedy&quot;<br>  ],<br>  &quot;href&quot;: &quot;Toy_Story&quot;,<br>  &quot;extract&quot;: &quot;Toy Story is a 1995 American computer-animated comedy film directed by John Lasseter, produced by Pixar Animation Studios and released by Walt Disney Pictures. The first installment in the  Toy Story franchise, it was the first entirely computer-animated feature film, as well as the first feature film from Pixar. It was written by Joss Whedon, Andrew Stanton, Joel Cohen, and Alec Sokolow from a story by Lasseter, Stanton, Pete Docter, and Joe Ranft. The film features music by Randy Newman, was produced by Bonnie Arnold and Ralph Guggenheim, and was executive-produced by Steve Jobs and Edwin Catmull. The film features the voices of Tom Hanks, Tim Allen, Don Rickles, Jim Varney, Wallace Shawn, John Ratzenberger, Annie Potts, R. Lee Ermey, John Morris, Laurie Metcalf, and Erik von Detten.&quot;,<br>  &quot;thumbnail&quot;: &quot;https://upload.wikimedia.org/wikipedia/en/1/13/Toy_Story.jpg&quot;,<br>  &quot;thumbnail_width&quot;: 250,<br>  &quot;thumbnail_height&quot;: 373<br>}</pre><h3>Building the Application</h3><p>Our application will be built using Spring Boot with Redis OM Spring. <strong>It will allow movies to be searched by their synopsis based on semantic search rather than keyword matching. </strong>Besides that, our application will also allow its users to perform <strong>hybrid search</strong>, <strong>a technique that combines vector similarity with traditional filtering and sorting.</strong></p><h4>0. GitHub Repository</h4><p><strong>The full application can be found on GitHub: </strong><a href="https://github.com/redis/redis-om-spring/tree/main/demos/roms-vss-movies/src">https://github.com/redis/redis-om-spring/tree/main/demos/roms-vss-movies/</a></p><h4>1. Add the required dependencies</h4><p>From a Spring Boot application, add the following dependencies to your Maven or Gradle file:</p><pre>&lt;!-- Redis OM Spring for Redis object mapping and vector search --&gt;<br>&lt;dependency&gt;<br>    &lt;groupId&gt;com.redis.om.spring&lt;/groupId&gt;<br>    &lt;artifactId&gt;redis-om-spring&lt;/artifactId&gt;<br>    &lt;version&gt;0.9.11&lt;/version&gt;<br>&lt;/dependency&gt;<br><br>&lt;!-- Redis OM Spring uses Spring AI for creating embeddings (vectors) --&gt;<br>&lt;dependency&gt;<br>    &lt;groupId&gt;org.springframework.ai&lt;/groupId&gt;<br>    &lt;artifactId&gt;spring-ai-openai&lt;/artifactId&gt;<br>    &lt;version&gt;1.0.0-M6&lt;/version&gt;<br>&lt;/dependency&gt;<br>&lt;dependency&gt;<br>    &lt;groupId&gt;org.springframework.ai&lt;/groupId&gt;<br>    &lt;artifactId&gt;spring-ai-transformers&lt;/artifactId&gt;<br>    &lt;version&gt;1.0.0-M6&lt;/version&gt;<br>&lt;/dependency&gt;</pre><h4>2. Define the Movie entity</h4><p>Redis OM Spring provides two annotations that makes it easy to vectorize data and perform vector similarity search from within Spring Boot.</p><ul><li>@Vectorize: Automatically generates vector embeddings from the text field</li><li>@Indexed: Enables vector indexing on a field for efficient search</li></ul><p>The core of the implementation is the Movie class with Redis vector indexing annotations:</p><pre>@RedisHash // This annotation is used by Redis OM Spring to store the entity as a hash in Redis<br>public class Movie {<br><br>    @Id // IDs are automatically generated by Redis OM Spring as ULID<br>    private String title;<br><br>    @Indexed(sortable = true) // This annotation enables indexing on the field for filtering and sorting<br>    private int year;<br><br>    @Indexed<br>    private List&lt;String&gt; cast;<br><br>    @Indexed<br>    private List&lt;String&gt; genres;<br><br>    private String href;<br><br>    // This annotation automatically generates vector embeddings from the text<br>    @Vectorize(<br>            destination = &quot;embeddedExtract&quot;, // The field where the embedding will be stored<br>            embeddingType = EmbeddingType.SENTENCE, // Type of embedding to generate (Sentence, Image, face, or word)<br>            provider = EmbeddingProvider.OPENAI, // The provider for generating embeddings (OpenAI, Transformers, VertexAI, etc.)<br>            openAiEmbeddingModel = OpenAiApi.EmbeddingModel.TEXT_EMBEDDING_3_LARGE // The specific OpenAI model to use for embeddings<br>    )<br>    private String extract;<br><br>    // This defines the vector field that will store the embeddings<br>    // The indexed annotation enables vector search on this field<br>    @Indexed(<br>            schemaFieldType = SchemaFieldType.VECTOR, // Defines the field type as a vector<br>            algorithm = VectorField.VectorAlgorithm.FLAT, // The algorithm used for vector search (FLAT or HNSW)<br>            type = VectorType.FLOAT32,<br>            dimension = 3072, // The dimension of the vector (must match the embedding model)<br>            distanceMetric = DistanceMetric.COSINE, // The distance metric used for similarity search (Cosine or Euclidean)<br>            initialCapacity = 10<br>    )<br>    private byte[] embeddedExtract;<br><br>    private String thumbnail;<br>    private int thumbnailWidth;<br>    private int thumbnailHeight;<br><br>    // Getters and setters...<br>}</pre><p>In this example we&#39;re using OpenAI&#39;s embedding model that requires an <strong>OpenAI API Key</strong> to be set in the application.properties file of your application:</p><pre>redis.om.spring.ai.open-ai.api-key=${OPEN_AI_KEY}</pre><blockquote>If an embedding model is not specified, Redis OM Spring will use a Hugging Face’s Transformers model all-MiniLM-L6-v2 by default. In this case, make sure you match the number of dimensions in the indexed annotation to 384 which is the number of dimensions created by the default embedding model.</blockquote><h4>3. Repository Interface</h4><p>A simple repository interface that extends RedisEnhancedRepository. This will be used to load the data into Redis using the saveAll() method:</p><pre>public interface MovieRepository extends RedisEnhancedRepository&lt;Movie, String&gt; {}</pre><p>This provides basic CRUD operations for Movie entities, with the first generic parameter being the entity type and the second being the ID type.</p><h4><strong>4. Search Service</strong></h4><p>The search service uses two beans provided by Redis OM Spring:</p><ul><li>EntityStream: For creating a stream of entities to perform searches. <strong>The Entity Stream must not be confused with the Java Streams API.</strong> The Entity Stream will generate a Redis Command that will be sent to Redis so that Redis can perform the searching, filtering and sorting efficiently on its side.</li><li>Embedder: Used for generating the embedding for the query sent by the user. It will be generated following the configuration of the @Vectorize annotation defined in the Movie class.</li></ul><p>The search functionality is implemented in the SearchService:</p><pre>@Service<br>public class SearchService {<br><br>    private static final Logger logger = LoggerFactory.getLogger(SearchService.class);<br>    private final EntityStream entityStream;<br>    private final Embedder embedder;<br><br>    public SearchService(EntityStream entityStream, Embedder embedder) {<br>        this.entityStream = entityStream;<br>        this.embedder = embedder;<br>    }<br><br>    public List&lt;Pair&lt;Movie, Double&gt;&gt; search(<br>            String query,<br>            Integer yearMin,<br>            Integer yearMax,<br>            List&lt;String&gt; cast,<br>            List&lt;String&gt; genres,<br>            Integer numberOfNearestNeighbors) {<br>        logger.info(&quot;Received text: {}&quot;, query);<br>        logger.info(&quot;Received yearMin: {} yearMax: {}&quot;, yearMin, yearMax);<br>        logger.info(&quot;Received cast: {}&quot;, cast);<br>        logger.info(&quot;Received genres: {}&quot;, genres);<br><br>        if (numberOfNearestNeighbors == null) numberOfNearestNeighbors = 3;<br>        if (yearMin == null) yearMin = 1900;<br>        if (yearMax == null) yearMax = 2100;<br><br>        // Convert query text to vector embedding<br>        byte[] embeddedQuery = embedder.getTextEmbeddingsAsBytes(List.of(query), Movie$.EXTRACT).getFirst();<br><br>        // Perform vector search with additional filters<br>        SearchStream&lt;Movie&gt; stream = entityStream.of(Movie.class);<br>        return stream<br>                // KNN search for nearest vectors<br>                .filter(Movie$.EMBEDDED_EXTRACT.knn(numberOfNearestNeighbors, embeddedQuery))<br>                // Additional metadata filters (hybrid search)<br>                .filter(Movie$.YEAR.between(yearMin, yearMax))<br>                .filter(Movie$.CAST.eq(cast))<br>                .filter(Movie$.GENRES.eq(genres))<br>                // Sort by similarity score<br>                .sorted(Movie$._EMBEDDED_EXTRACT_SCORE)<br>                // Return both the movie and its similarity score<br>                .map(Fields.of(Movie$._THIS, Movie$._EMBEDDED_EXTRACT_SCORE))<br>                .collect(Collectors.toList());<br>    }<br>}</pre><p>Key features of the search service:</p><ul><li>Uses EntityStream to create a search stream for Movie entities</li><li>Converts the text query into a vector embedding</li><li>Uses K-nearest neighbors (KNN) search to find similar vectors</li><li>Applies additional filters for hybrid search (combining vector and traditional search)</li><li>Returns pairs of movies and their similarity scores</li></ul><h4>5. Movie Service for Data Loading</h4><p>The MovieService handles loading movie data into Redis. It reads a JSON file containing movie date and save the movies into Redis.</p><blockquote>It may take one or two minutes to load the data for the thousands of movies in the file because the embedding generation is done in the background. The @Vectorize annotation will generate the embeddings for the extract field before the movie is saved into Redis.</blockquote><pre>@Service<br>public class MovieService {<br><br>    private static final Logger log = LoggerFactory.getLogger(MovieService.class);<br>    private final ObjectMapper objectMapper;<br>    private final ResourceLoader resourceLoader;<br>    private final MovieRepository movieRepository;<br><br>    public MovieService(ObjectMapper objectMapper, ResourceLoader resourceLoader, MovieRepository movieRepository) {<br>        this.objectMapper = objectMapper;<br>        this.resourceLoader = resourceLoader;<br>        this.movieRepository = movieRepository;<br>    }<br><br>    public void loadAndSaveMovies(String filePath) throws Exception {<br>        Resource resource = resourceLoader.getResource(&quot;classpath:&quot; + filePath);<br>        try (InputStream is = resource.getInputStream()) {<br>            List&lt;Movie&gt; movies = objectMapper.readValue(is, new TypeReference&lt;&gt;() {});<br>            List&lt;Movie&gt; unprocessedMovies = movies.stream()<br>                    .filter(movie -&gt; !movieRepository.existsById(movie.getTitle()) &amp;&amp;<br>                            movie.getYear() &gt; 1980<br>                    ).toList();<br>            long systemMillis = System.currentTimeMillis();<br>            movieRepository.saveAll(unprocessedMovies);<br>            long elapsedMillis = System.currentTimeMillis() - systemMillis;<br>            log.info(&quot;Saved &quot; + movies.size() + &quot; movies in &quot; + elapsedMillis + &quot; ms&quot;);<br>        }<br>    }<br><br>    public boolean isDataLoaded() {<br>        return movieRepository.count() &gt; 0;<br>    }<br>}</pre><h4>5. Search Controller</h4><p>The REST controller exposes the search endpoint:</p><pre>@RestController<br>public class SearchController {<br><br>    private final SearchService searchService;<br><br>    public SearchController(SearchService searchService) {<br>        this.searchService = searchService;<br>    }<br><br>    @GetMapping(&quot;/search&quot;)<br>    public Map&lt;String, Object&gt; search(<br>            @RequestParam(required = false) String text,<br>            @RequestParam(required = false) Integer yearMin,<br>            @RequestParam(required = false) Integer yearMax,<br>            @RequestParam(required = false) List&lt;String&gt; cast,<br>            @RequestParam(required = false) List&lt;String&gt; genres,<br>            @RequestParam(required = false) Integer numberOfNearestNeighbors<br>    ) {<br>        List&lt;Pair&lt;Movie, Double&gt;&gt; matchedMovies = searchService.search(<br>                text,<br>                yearMin,<br>                yearMax,<br>                cast,<br>                genres,<br>                numberOfNearestNeighbors<br>        );<br>        return Map.of(<br>                &quot;matchedMovies&quot;, matchedMovies,<br>                &quot;count&quot;, matchedMovies.size()<br>        );<br>    }<br>}</pre><h4>6. Application Bootstrap</h4><p>The main application class initializes Redis OM Spring and loads data. The @EnableRedisEnhancedRepositories annotation activates Redis OM Spring&#39;s repository support:</p><pre>@SpringBootApplication<br>@EnableRedisEnhancedRepositories(basePackages = {&quot;com.redis.om.vssmovies*&quot;})<br>public class Redis8DemoVectorSimilaritySearchApplication {<br><br>    public static void main(String[] args) {<br>        SpringApplication.run(Redis8DemoVectorSimilaritySearchApplication.class, args);<br>    }<br><br>    @Bean<br>    CommandLineRunner loadData(MovieService movieService) {<br>        return args -&gt; {<br>            if (movieService.isDataLoaded()) {<br>                System.out.println(&quot;Data already loaded. Skipping data load.&quot;);<br>                return;<br>            }<br>            movieService.loadAndSaveMovies(&quot;movies.json&quot;);<br>        };<br>    }<br>}</pre><h4>7. Sample Requests</h4><p>You can make requests to the search endpoint:</p><pre>GET http://localhost:8082/search?text=A movie about a young boy who goes to a wizardry school<br><br>GET http://localhost:8082/search?numberOfNearestNeighbors=1&amp;yearMin=1970&amp;yearMax=1990&amp;text=A movie about a kid and a scientist who go back in time<br><br>GET http://localhost:8082/search?cast=Dee Wallace,Henry Thomas&amp;text=A boy who becomes friend with an alien</pre><p><strong>Sample request:</strong></p><pre>GET http://localhost:8082/search?numberOfNearestNeighbors=1&amp;yearMin=1970&amp;yearMax=1990&amp;text=A movie about a kid and a scientist who go back in time</pre><p><strong>Sample response:</strong></p><pre>{<br>  &quot;count&quot;: 1,<br>  &quot;matchedMovies&quot;: [<br>    {<br>      &quot;first&quot;: { // matched movie<br>        &quot;title&quot;: &quot;Back to the Future&quot;,<br>        &quot;year&quot;: 1985,<br>        &quot;cast&quot;: [<br>          &quot;Michael J. Fox&quot;,<br>          &quot;Christopher Lloyd&quot;<br>        ],<br>        &quot;genres&quot;: [<br>          &quot;Science Fiction&quot;<br>        ],<br>        &quot;extract&quot;: &quot;Back to the Future is a 1985 American science fiction film directed by Robert Zemeckis and written by Zemeckis, and Bob Gale. It stars Michael J. Fox, Christopher Lloyd, Lea Thompson, Crispin Glover, and Thomas F. Wilson. Set in 1985, it follows Marty McFly (Fox), a teenager accidentally sent back to 1955 in a time-traveling DeLorean automobile built by his eccentric scientist friend Emmett \&quot;Doc\&quot; Brown (Lloyd), where he inadvertently prevents his future parents from falling in love – threatening his own existence – and is forced to reconcile them and somehow get back to the future.&quot;,<br>        &quot;thumbnail&quot;: &quot;https://upload.wikimedia.org/wikipedia/en/d/d2/Back_to_the_Future.jpg&quot;<br>      },<br>      &quot;second&quot;: 0.463297247887 // similarity score (the lowest the closest)<br>    }<br>  ]<br>}</pre><h4>Wrapping up</h4><p>And that’s it — you now have a working semantic search app using Spring Boot and Redis.</p><p>Instead of relying on exact keyword matches, your app understands the meaning behind the query. Redis handles the heavy part: embedding storage, similarity search, and even traditional filters — all at lightning speed.</p><p>With Redis OM Spring, you get an easy way to integrate this into your Java apps. You only need two annotations: @Vectorize and @Indexed and two Beans: EntityStream and Embedder.</p><p>Whether you’re building search, recommendations, or AI-powered assistants, this setup gives you a solid and scalable foundation.</p><p>Try it out, tweak the filters, explore other models, and see how far you can go!</p><h4>More AI Resources</h4><p>The best way to stay on the path of learning AI is by following the recipes available on the Redis AI Resources GitHub repository. There you can find dozens of recipes that will get you to start building AI apps, fast!</p><p><a href="https://github.com/redis-developer/redis-ai-resources/tree/main">GitHub - redis-developer/redis-ai-resources: ✨ A curated list of awesome community resources, integrations, and examples of Redis in the AI ecosystem.</a></p><h4>Stay Curious!</h4><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=ef376bbdb106" width="1" height="1" alt=""><hr><p><a href="https://medium.com/redis-with-raphael-de-lio/semantic-search-with-spring-boot-redis-ef376bbdb106">Semantic Search with Spring Boot &amp; Redis</a> was originally published in <a href="https://medium.com/redis-with-raphael-de-lio">Redis with Raphael De Lio</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Sliding Window Counter Rate Limiter (Redis & Java)]]></title>
            <link>https://medium.com/redis-with-raphael-de-lio/sliding-window-counter-rate-limiter-redis-java-1ba8901c02e5?source=rss----a29f9dbf6d82---4</link>
            <guid isPermaLink="false">https://medium.com/p/1ba8901c02e5</guid>
            <category><![CDATA[java]]></category>
            <category><![CDATA[architecture]]></category>
            <category><![CDATA[building-with-redis]]></category>
            <category><![CDATA[design-systems]]></category>
            <category><![CDATA[redis]]></category>
            <dc:creator><![CDATA[Raphael De Lio]]></dc:creator>
            <pubDate>Mon, 24 Feb 2025 12:09:59 GMT</pubDate>
            <atom:updated>2025-02-24T12:09:59.621Z</atom:updated>
            <content:encoded><![CDATA[<blockquote>This content is also available on YouTube. <a href="https://youtu.be/Wvm_u0IR69M"><strong>Check it out!</strong></a></blockquote><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*tri7BjAachsaG5z4L61w9g.png" /></figure><p>The <strong>Sliding Window Counter</strong> offers a more efficient way to handle rate limiting compared to the <strong>Sliding Window Log</strong>. While the Sliding Window Log keeps an exact log of timestamps for each request, allowing precise tracking over a rolling time period, this precision comes at the cost of higher memory usage and computational overhead as the number of requests increases.</p><p>In contrast, the Sliding Window Counter approximates the request rate by dividing time into smaller intervals and counting requests within each interval. By maintaining these interval counts and using weighted averages to estimate the rolling window, it provides a balance between accuracy and efficiency.</p><p>Though not as precise as the Sliding Window Log, the Sliding Window Counter requires significantly less memory since it avoids storing individual timestamps. This makes it better suited for scenarios with high traffic or resource constraints while still enforcing rate limits smoothly and without abrupt resets.</p><h4>Index</h4><ul><li><strong>Introduction</strong></li><li><strong>How the Sliding Window Counter Rate Limiter Works</strong></li><li><strong>Implementation with Redis and Java</strong></li><li><strong>Testing with TestContainers and AssertJ</strong></li><li><strong>Conclusion (GitHub Repo)</strong></li></ul><h3>How It Works</h3><figure><img alt="This image illustrates the Sliding Window Counter rate-limiting algorithm. The x-axis represents time, segmented into 1-minute windows, further divided into 20-second subwindows. The y-axis represents the number of requests received. The current window (3:06–3:07) is highlighted in red, showing the active time frame for counting requests. The subsequent time windows (3:07, 3:08, etc.) follow the same structure, demonstrating how the sliding window moves forward over time. The rate-limiting r" src="https://cdn-images-1.medium.com/max/1024/1*XLeoFFYwU1uzvLuMFu-tAw.gif" /></figure><h4>1. Define a Time Window</h4><p>Choose a rolling time window, such as the last 1 second, 1 minute, or 1 hour.</p><h4>2. Track Requests</h4><p>Divide the time window into smaller sub-intervals (e.g., 1-second intervals) and maintain a counter for each sub-interval. Increment the counter for the current sub-interval as each request comes in.</p><h4>3. Remove Expired Intervals</h4><p>Continuously clean up expired sub-intervals that fall outside the current rolling time window to keep memory usage efficient.</p><h4>4. Rate Limit Check</h4><p>Calculate the total number of requests within the current rolling window by summing the counters for the active sub-intervals. If the total exceeds the allowed limit, reject new requests; otherwise, allow them.</p><h3>How to Implement It with Redis</h3><p>Implementing the <strong>Sliding Window Counter</strong> with Redis involves maintaining counts for smaller sub-intervals within the rolling window and calculating the total to enforce rate limits. Here’s how to do it:</p><h4>1. <strong>Track Requests by Sub-Interval</strong></h4><p>Use a Redis hash (HSET) to store the count of requests for each sub-interval within the rolling window. The sub-intervals are identified by their start times (e.g., Unix timestamps rounded to the nearest second).</p><pre>HINCRBY client-1 &lt;sub_interval_start&gt; 1  </pre><p>Each request increments the counter for the current sub-interval.</p><h4><strong>2. Remove Expired Intervals</strong></h4><p>Clean up entries that fall outside the rolling time window. Use the new HEXPIRE command to let Redis remove automatically fields representing sub-intervals older than the current window duration:</p><pre>HEXPIRE client-1 subWindowSize NX FIELDS 1 sub-counter</pre><p>This ensures the hash only contains counts for active sub-intervals within the rolling window.</p><h4><strong>3. Sum Counts for the Active Window</strong></h4><p>Use the HGETALL command to retrieve all counts for the sub-intervals currently in the hash. Sum these counts to calculate the total number of requests within the rolling window:</p><pre>HGETALL my_counter  </pre><p>Compare the total count to the allowed limit.<strong> If it exceeds the limit, reject the new request; otherwise, allow it and update the counter.</strong></p><p>Cool! Now that we understand the steps, let’s implement this in Java with Jedis!</p><h3>Implementing it with Jedis</h3><p><strong>Jedis</strong> is a popular library that makes it easy to work with Redis in Java applications. Its simple and intuitive API is perfect for implementing a rate limiter, allowing us to efficiently manage requests and enforce limits.</p><h4><strong>Add Jedis to Your Maven File</strong></h4><p>Check the latest version <a href="https://redis.io/docs/latest/develop/clients/jedis/">here</a>.</p><pre>&lt;dependency&gt;<br>    &lt;groupId&gt;redis.clients&lt;/groupId&gt;<br>    &lt;artifactId&gt;jedis&lt;/artifactId&gt;<br>    &lt;version&gt;5.2.0&lt;/version&gt;<br>&lt;/dependency&gt;</pre><h4>Create a <strong>SlidingWindowCounterRateLimiter</strong> class:</h4><p>The rate limiter will:</p><p>1. Use a <strong>Redis hash</strong> to store request counts for each time sub-window.</p><p>2. Allow requests if the total count across the sliding window is within the limit.</p><p>3. Automatically clean up expired sub-windows.</p><p>Here’s the basic structure:</p><pre>package io.redis;<br><br>import redis.clients.jedis.Jedis;<br>import redis.clients.jedis.Transaction;<br><br>import java.util.ArrayList;<br>import java.util.List;<br><br>public class SlidingWindowCounterRateLimiter {<br><br>    private final Jedis jedis;<br>    private final int limit;<br>    private final long windowSize; // Total sliding window size in seconds<br>    private final long subWindowSize; // Size of each sub-window in seconds<br><br>    public SlidingWindowCounterRateLimiter(Jedis jedis, int limit, long windowSize, long subWindowSize) {<br>        this.jedis = jedis;<br>        this.limit = limit;<br>        this.windowSize = windowSize;<br>        this.subWindowSize = subWindowSize;<br>    }<br>}</pre><h4>Validate the Requests</h4><p>The core task of the rate limiter is to determine whether a client’s request is within the allowed limit. If it is, the request is allowed, and the count for the current sub-window is updated. If it isn’t, the request is denied.</p><p><strong>Step 1: Generate a key<br></strong>Our isAllowed method receives a client id, used for identifying different clients independently. We then start by defining the key space in which this key will be stored in Redis, allowing us to keep our data organized within the database.</p><pre>public boolean isAllowed(String clientId) {<br>    String key = &quot;rate_limit:&quot; + clientId;<br>}</pre><p>For example, if the client ID is user123, and the keyspace is rate_ limit, their key would be rate_limit:user123.</p><p><strong>Step 2: Check the number of active requests and if the new one is allowed to be processed<br></strong>We will do it by using the hgetAll command. This command will receive the key of our hash and return all the fields and their respective values.</p><p>The values are the actual counter of the sub windows. We will sum them to get the total count. Then, we will compare the total count to the limit and decide whether this request is allowed to proceed.</p><pre>Map&lt;String, String&gt; subWindowCounts = jedis.hgetAll(key);<br>long totalCount = subWindowCounts.values().stream()<br>        .mapToLong(Long::parseLong)<br>        .sum();<br><br>boolean isAllowed = totalCount &lt; limit;</pre><p><strong>Step 3: Track Requests by Sub-Window<br></strong>If the request is allowed to be processed, we’ll determine the actual current sub window in which the request falls into and that will be used to separate counters within our hash.</p><pre>if (isAllowed) {<br>    // Calculate the current sub-window index based on the time<br>    long currentTime = System.currentTimeMillis();<br>    long subWindowSizeMillis = subWindowSize * 1000;<br>    long currentSubWindow = currentTime / subWindowSizeMillis;<br><br>    // Start a transaction to increment the current sub-window count and set TTL<br>    Transaction transaction = jedis.multi();<br>    transaction.hincrBy(key, Long.toString(currentSubWindow), 1);<br>    transaction.hexpire(key, windowSize, NX, String.valueOf(currentSubWindow));<br>    List&lt;Object&gt; result = transaction.exec();<br><br>    if (result == null || result.isEmpty()) {<br>        throw new IllegalStateException(&quot;Empty result from Redis transaction&quot;);<br>    }<br>}<br><br>return isAllowed;</pre><p>Here, we’ll start a transaction to ensure that our operation is going to be atomic and that all of our commands are going to be sent at once to the database. This will allow us to achieve even a better performance by avoiding unnecessary network trips.</p><p>Then, we will call the hincrBy function to increment the current counter, the current sub window we calculated before. The key is the key to the hash. The currentSubWindow is the field key within this hash and 1 is the value by which this field will be increment by.</p><p>If the actual hash doesn’t exist yet, don’t worry, Redis will create it for us.</p><p>After that, we’ll set an expiration for this field using the new Redis HEXPIRE command.</p><p>This function receives the key to the hash, the expiration time, which is our subWindowSize, the expiration option, and the fields which we want the expiration to be set for.</p><p>The NX expiration option is important here because it tells Redis to only set the expiration to our field if it hadn’t been set before. If we don’t do this, we’ll reset the expiration everytime a new request comes in and end up extending the sub window for longer than it should exist.</p><p>After we run the transaction, Redis will return the response of all commands we sent. To make sure our operation succeeded, we need to make sure the response isn’t empty.</p><p>And finally, we return if the request is able to proceed</p><h4>Full Implementation</h4><p>Here’s the full code for the SlidingWindowCounterRateLimiter class:</p><pre>package io.redis;<br><br>import redis.clients.jedis.Jedis;<br>import redis.clients.jedis.Transaction;<br><br>import java.util.ArrayList;<br>import java.util.List;<br><br>public class SlidingWindowCounterRateLimiter {<br><br>    private final Jedis jedis;<br>    private final int limit;<br>    private final long windowSize; // Total sliding window size in seconds<br>    private final long subWindowSize; // Size of each sub-window in seconds<br><br>    public SlidingWindowCounterRateLimiter(Jedis jedis, int limit, long windowSize, long subWindowSize) {<br>        this.jedis = jedis;<br>        this.limit = limit;<br>        this.windowSize = windowSize;<br>        this.subWindowSize = subWindowSize;<br>    }<br><br>    public boolean isAllowed(String clientId) {<br>        String key = &quot;rate_limit:&quot; + clientId;<br>        Map&lt;String, String&gt; subWindowCounts = jedis.hgetAll(key);<br>        long totalCount = subWindowCounts.values().stream()<br>                .mapToLong(Long::parseLong)<br>                .sum();<br><br>        boolean isAllowed = totalCount &lt; limit;<br><br>        if (isAllowed) {<br>            // Calculate the current sub-window index based on the time<br>            long currentTime = System.currentTimeMillis();<br>            long subWindowSizeMillis = subWindowSize * 1000;<br>            long currentSubWindow = currentTime / subWindowSizeMillis;<br><br>            // Start a transaction to increment the current sub-window count and set TTL<br>            Transaction transaction = jedis.multi();<br>            transaction.hincrBy(key, Long.toString(currentSubWindow), 1);<br>            transaction.hexpire(key, windowSize, NX, String.valueOf(currentSubWindow));<br>            List&lt;Object&gt; result = transaction.exec();<br><br>            if (result == null || result.isEmpty()) {<br>                throw new IllegalStateException(&quot;Empty result from Redis transaction&quot;);<br>            }<br>        }<br><br>        return isAllowed;<br>    }<br>}</pre><p>And we’re ready to start testing its behavior!</p><h3>Testing our Rate Limiter</h3><p>To ensure our Sliding Window Counter Rate Limiter behaves as expected, we’ll write tests for various scenarios. For this, we’ll use three tools:</p><p>1. <strong>Redis TestContainers</strong>: This library spins up an isolated Redis container for testing. This means we don’t need to rely on an external Redis server during our tests. Once the tests are done, the container is stopped, leaving no leftover data.</p><p>2. <strong>JUnit 5</strong>: Our main testing framework, which helps us define and structure tests with lifecycle methods like @BeforeEach and @AfterEach.</p><p>3. <strong>AssertJ</strong>: A library that makes assertions readable and expressive, like assertThat(result).isTrue().</p><p>Let’s begin by adding the necessary dependencies to our pom.xml.</p><h4>Adding Dependencies</h4><p>Here’s what you’ll need in your Maven pom.xml file:</p><pre>&lt;dependency&gt;<br>    &lt;groupId&gt;org.junit.jupiter&lt;/groupId&gt;<br>    &lt;artifactId&gt;junit-jupiter-engine&lt;/artifactId&gt;<br>    &lt;version&gt;5.10.0&lt;/version&gt;<br>    &lt;scope&gt;test&lt;/scope&gt;<br>&lt;/dependency&gt;<br>&lt;dependency&gt;<br>    &lt;groupId&gt;com.redis&lt;/groupId&gt;<br>    &lt;artifactId&gt;testcontainers-redis&lt;/artifactId&gt;<br>    &lt;version&gt;2.2.2&lt;/version&gt;<br>    &lt;scope&gt;test&lt;/scope&gt;<br>&lt;/dependency&gt;<br>&lt;dependency&gt;<br>    &lt;groupId&gt;org.assertj&lt;/groupId&gt;<br>    &lt;artifactId&gt;assertj-core&lt;/artifactId&gt;<br>    &lt;version&gt;3.11.1&lt;/version&gt;<br>    &lt;scope&gt;test&lt;/scope&gt;<br>&lt;/dependency&gt;</pre><p>Once you’ve added these dependencies, you’re ready to start writing your test class.</p><h4>Setting Up the Test Class</h4><p>The first step is to create a test class named SlidingWindowCounterRateLimiterTest. Inside, we’ll define three main components:</p><p>1. <strong>Redis Test Container</strong>: This launches a Redis instance in a Docker container.</p><p>2. <strong>Jedis Instance</strong>: This connects to the Redis container for sending commands.</p><p>3. <strong>Rate Limiter</strong>: The actual SlidingWindowCounterRateLimiterTest instance we’re testing.</p><p>Here’s how the skeleton of our test class looks:</p><pre>public class SlidingWindowCounterRateLimiterTest {<br>    private static final RedisContainer redisContainer = new RedisContainer(&quot;redis:latest&quot;)<br>            .withExposedPorts(6379);<br>    private Jedis jedis;<br>    private SlidingWindowCounterRateLimiterTest rateLimiter;<br><br>    static {<br>        redisContainer.start();<br>    }<br>}</pre><h4>Preparing the Environment Before Each Test</h4><p>Before running any test, we need to ensure a clean Redis environment. Here’s what we’ll do:</p><p>1. <strong>Connect to Redis</strong>: Use a Jedis instance to connect to the Redis container.</p><p>2. <strong>Flush Data</strong>: Clear any leftover data in Redis to ensure consistent results for each test.</p><p>We’ll set this up in a method annotated with @BeforeEach, which runs before every test case.</p><pre>@BeforeEach<br>public void setup() {<br>    jedis = new Jedis(redisContainer.getHost(), redisContainer.getFirstMappedPort());<br>    jedis.flushAll();<br>}</pre><blockquote>FLUSHALL is an actual Redis command that deletes all the keys of all the existing databases. <a href="https://redis.io/docs/latest/commands/flushall/">Read more about it in the official documentation</a>.</blockquote><h4>Cleaning Up After Each Test</h4><p>After each test, we need to close the Jedis connection to free up resources. This ensures no lingering connections interfere with subsequent tests.</p><pre>@AfterEach<br>public void tearDown() {<br>    jedis.close();<br>}</pre><h4>Full Setup</h4><p>Here’s how the complete test class looks with everything in place:</p><pre>public class SlidingWindowCounterRateLimiterTest {<br><br>    private static final RedisContainer redisContainer = new RedisContainer(&quot;redis:latest&quot;)<br>            .withExposedPorts(6379)<br>            .withReuse(true);<br><br>    static {<br>        redisContainer.start();<br>    }<br><br>    private Jedis jedis;<br>    private SlidingWindowCounterRateLimiter rateLimiter;<br><br>    @BeforeEach<br>    public void setup() {<br>        jedis = new Jedis(redisContainer.getHost(), redisContainer.getFirstMappedPort());<br>        jedis.flushAll();<br>    }<br><br>    @AfterEach<br>    public void tearDown() {<br>        jedis.close();<br>    }<br>}</pre><h4>Verifying Requests Within the Limit</h4><p>This test ensures the Sliding Window Counter rate limiter allows requests within the defined limit.</p><p>We configure it with a limit of 5 requests, a 10-second window, and 1-second sub-windows. We then call isAllowed(“client-1”) 5 times. Each call should return true, confirming the rate limiter correctly tracks and permits requests under the limit.</p><pre>@Test<br>public void shouldAllowRequestsWithinLimit() {<br>    rateLimiter = new SlidingWindowCounterRateLimiter(jedis, 5, 10, 1);<br>    for (int i = 1; i &lt;= 5; i++) {<br>        assertThat(rateLimiter.isAllowed(&quot;client-1&quot;))<br>                .withFailMessage(&quot;Request %d should be allowed&quot;, i)<br>                .isTrue();<br>    }<br>}</pre><h4>Verifying Requests Beyond the Limit</h4><p>This test ensures the Sliding Window Counter rate limiter correctly denies requests once the defined limit is exceeded.</p><p>We configure it with a limit of 5 requests, a 60-second window, and 1-second sub-windows. We then call isAllowed(“client-1”) 5 times and expect all to return true. On the 6th call, it should return false, verifying the rate limiter blocks requests beyond the allowed limit.</p><pre>@Test<br>public void shouldDenyRequestsOnceLimitIsExceeded() {<br>    rateLimiter = new SlidingWindowCounterRateLimiter(jedis, 5, 60, 1);<br>    for (int i = 1; i &lt;= 5; i++) {<br>        assertThat(rateLimiter.isAllowed(&quot;client-1&quot;))<br>                .withFailMessage(&quot;Request %d should be allowed&quot;, i)<br>                .isTrue();<br>    }<br><br>    assertThat(rateLimiter.isAllowed(&quot;client-1&quot;))<br>            .withFailMessage(&quot;Request beyond limit should be denied&quot;)<br>            .isFalse();<br>}</pre><h4>Verifying Requests After Sliding Window Resets</h4><p>This test ensures that the Sliding Window Counter rate limiter correctly resets the sliding window and allows requests after the window duration has passed.</p><p>We configure it with a limit of 5 requests, a 2-second window, and 1-second sub-windows. We first call isAllowed(“client-1”) 5 times and expect all to return true. On the 6th call, the rate limiter should return false, indicating that the limit has been reached.</p><p>After waiting for the sliding window to reset (2 seconds + a buffer), the next request is allowed. This verifies that the sliding window correctly clears expired entries and permits new requests.</p><pre>@Test<br>public void shouldAllowRequestsAgainAfterSlidingWindowResets() throws InterruptedException {<br>    int limit = 5;<br>    String clientId = &quot;client-1&quot;;<br>    long windowSize = 2L;<br>    long subWindowSize = 1L;<br><br>    rateLimiter = new SlidingWindowCounterRateLimiter(jedis, limit, windowSize, subWindowSize);<br><br>    for (int i = 1; i &lt;= limit; i++) {<br>        assertThat(rateLimiter.isAllowed(clientId))<br>                .withFailMessage(&quot;Request %d should be allowed&quot;, i)<br>                .isTrue();<br>    }<br><br>    assertThat(rateLimiter.isAllowed(clientId))<br>            .withFailMessage(&quot;Request beyond limit should be denied&quot;)<br>            .isFalse();<br><br>    Thread.sleep((windowSize + 1) * 1000);<br><br>    assertThat(rateLimiter.isAllowed(clientId))<br>            .withFailMessage(&quot;Request after window reset should be allowed&quot;)<br>            .isTrue();<br>}</pre><h4>Verifying Independent Handling of Multiple Clients</h4><p>This test ensures that the Sliding Window Counter rate limiter handles multiple clients independently.</p><p>We configure it with a limit of 5 requests, a 10-second window, and 1-second sub-windows. The first 5 requests from client-1 are allowed (true), while the 6th request is denied (false). Simultaneously, all 5 requests from client-2 are allowed (true), confirming that the rate limiter maintains separate counters for each client.</p><pre>@Test<br>public void shouldHandleMultipleClientsIndependently() {<br>    int limit = 5;<br>    String clientId1 = &quot;client-1&quot;;<br>    String clientId2 = &quot;client-2&quot;;<br>    long windowSize = 10L;<br>    long subWindowSize = 1L;<br><br>    rateLimiter = new SlidingWindowCounterRateLimiter(jedis, limit, windowSize, subWindowSize);<br><br>    for (int i = 1; i &lt;= limit; i++) {<br>        assertThat(rateLimiter.isAllowed(clientId1))<br>                .withFailMessage(&quot;Client 1 request %d should be allowed&quot;, i)<br>                .isTrue();<br>    }<br><br>    assertThat(rateLimiter.isAllowed(clientId1))<br>            .withFailMessage(&quot;Client 1 request beyond limit should be denied&quot;)<br>            .isFalse();<br><br>    for (int i = 1; i &lt;= limit; i++) {<br>        assertThat(rateLimiter.isAllowed(clientId2))<br>                .withFailMessage(&quot;Client 2 request %d should be allowed&quot;, i)<br>                .isTrue();<br>    }<br>}</pre><h4>Verifying Gradual Request Allowance in Sliding Window</h4><p>This test ensures that the Sliding Window Counter rate limiter gradually allows requests as older requests expire from the window.</p><p>We configure it with a limit of 3 requests, a 4-second window, and 1-second sub-windows. Initially, we call isAllowed(“client-1”) 3 times, each 1 second apart, and expect all to return true. On the 4th call, the request is denied (false), confirming the limit has been reached.</p><p>After waiting 2 seconds, enough older requests have expired to allow one new request. This verifies that the sliding window dynamically adjusts and permits requests as the window progresses.</p><pre>@Test<br>public void shouldAllowRequestsAgainGraduallyInSlidingWindow() throws InterruptedException {<br>    int limit = 3;<br>    long windowSize = 4L;<br>    long subWindowSize = 1L;<br>    String clientId = &quot;client-1&quot;;<br><br>    rateLimiter = new SlidingWindowCounterRateLimiter(jedis, limit, windowSize, subWindowSize);<br><br>    for (int i = 1; i &lt;= limit; i++) {<br>        assertThat(rateLimiter.isAllowed(clientId))<br>                .withFailMessage(&quot;Request %d should be allowed&quot;, i)<br>                .isTrue();<br>        Thread.sleep(1000);<br>    }<br><br>    assertThat(rateLimiter.isAllowed(clientId))<br>            .withFailMessage(&quot;Request beyond limit should be denied&quot;)<br>            .isFalse();<br><br>    Thread.sleep(2000);<br><br>    assertThat(rateLimiter.isAllowed(clientId))<br>            .withFailMessage(&quot;Request should be allowed in a sliding window&quot;)<br>            .isTrue();<br>}</pre><p>Is there any other behavior we should verify? Let me know in the comments!</p><p>The Sliding Window Counter Rate Limiter is a great way to manage request rates with a balance of precision and efficiency. Unlike simpler methods, it ensures rate limits are applied smoothly as the window progresses, without abrupt resets.</p><p>Thanks to Redis’s speed and reliability, and using straightforward commands like HINCRBY and HEXPIRE, we built a dynamic solution that tracks requests within a rolling time window. The implementation in Java with Jedis made the process intuitive, and testing it with Redis TestContainers, JUnit 5, and AssertJ helped ensure it works as expected in real-world scenarios.</p><p>This setup is not only easy to implement but also flexible enough to grow with your needs. Whether you’re just managing basic request limits or scaling up for more complex requirements, this is a solid foundation to start from.</p><h4>GitHub Repo</h4><p>You can find this implementation in <strong>Java</strong> and <strong>Kotlin</strong>:</p><ul><li>Java (<a href="https://github.com/raphaeldelio/redis-rate-limiter-java-example/blob/main/src/main/java/io/redis/SlidingWindowCounterRateLimiter.java">Implementation</a>, <a href="https://github.com/raphaeldelio/redis-rate-limiter-java-example/blob/main/src/test/java/io/redis/SlidingWindowCounterRateLimiterTest.java">Test</a>)</li><li>Kotlin (<a href="https://github.com/raphaeldelio/redis-rate-limiter-kotlin-example/blob/main/src/main/kotlin/org/example/SlidingWindowCounterRateLimiter.kt">Implementation</a>, <a href="https://github.com/raphaeldelio/redis-rate-limiter-kotlin-example/blob/main/src/test/kotlin/org/example/SlidingWindowCounterRateLimiterTest.kt">Test</a>)</li></ul><h4>Stay Curious!</h4><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=1ba8901c02e5" width="1" height="1" alt=""><hr><p><a href="https://medium.com/redis-with-raphael-de-lio/sliding-window-counter-rate-limiter-redis-java-1ba8901c02e5">Sliding Window Counter Rate Limiter (Redis &amp; Java)</a> was originally published in <a href="https://medium.com/redis-with-raphael-de-lio">Redis with Raphael De Lio</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Sliding Window Log Rate Limiter (Redis & Java)]]></title>
            <link>https://medium.com/redis-with-raphael-de-lio/sliding-window-log-rate-limiter-redis-java-ba189940da9e?source=rss----a29f9dbf6d82---4</link>
            <guid isPermaLink="false">https://medium.com/p/ba189940da9e</guid>
            <category><![CDATA[design-systems]]></category>
            <category><![CDATA[redis]]></category>
            <category><![CDATA[java]]></category>
            <category><![CDATA[building-with-redis]]></category>
            <category><![CDATA[architecture]]></category>
            <dc:creator><![CDATA[Raphael De Lio]]></dc:creator>
            <pubDate>Wed, 22 Jan 2025 11:29:19 GMT</pubDate>
            <atom:updated>2025-01-22T11:29:19.721Z</atom:updated>
            <content:encoded><![CDATA[<blockquote><a href="https://youtu.be/bCYzRg0oQjY">This article is also available on YouTube. Check it out!</a></blockquote><figure><img alt="A smiling person wearing glasses, set against a purple background, with large text reading “RATE LIMITING WITH PRECISION” and a Redis logo." src="https://cdn-images-1.medium.com/max/1024/1*wJVaCxUtPiIgBRhKphM-tw.png" /></figure><p>The <strong>Sliding Window Log</strong> is a <em>more precise</em> way to handle rate limiting. Instead of splitting time into fixed intervals like the <a href="https://medium.com/redis-with-raphael-de-lio/fixed-window-counter-rate-limiter-redis-java-b7da0adfa79b">Fixed Window Counter</a> , it keeps a log of timestamps for each request. This allows it to track requests over a rolling time period, like the last second or minute, without abrupt resets at the end of an interval.</p><p>By checking how many requests were made within that time frame, it ensures limits are enforced more smoothly. If the log shows too many requests, new ones are denied.</p><h4>Index</h4><ul><li><strong>Introduction</strong></li><li><strong>How the Sliding Window Log Rate Limiter Works</strong></li><li><strong>Implementation with Redis and Java</strong></li><li><strong>Testing with TestContainers and AssertJ</strong></li><li><strong>Conclusion (GitHub Repo)</strong></li></ul><h3>How It Works</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*tmaCfNHgzaAJNop4Aa2afA.gif" /></figure><h4>1. <strong>Define a Time Window</strong></h4><p>Choose a rolling time window, such as the last 1 second, 1 minute, or 1 hour.</p><h4>2. <strong>Track Requests</strong></h4><p>Log each request with a precise timestamp as it comes in.</p><h4>3. <strong>Remove Expired Entries</strong></h4><p>Continuously clean up the log by removing entries older than the current time window.</p><h4>4. <strong>Rate Limit Check</strong></h4><p>Count the remaining entries in the log. If the count exceeds the allowed limit, reject new requests; otherwise, allow them.</p><h3>How to Implement It with Redis and Java</h3><p>Implementing the <strong>Sliding Window Log</strong> with <strong>Redis</strong> involves logging each request with a timestamp and checking how many requests fall within the defined time window.</p><p>With Redis 8 and the introduction of the command HEXPIRE this process became easier and more efficient. The HEXPIRE command allows us to set expiration for specific fields in a hash. Before that, we could only set expiration to the hash as a whole.</p><p>Here’s how to do it:</p><h4>1. <strong>Log Each Request (If Allowed)</strong></h4><p>Use a Redis <strong>hash</strong> (HSET) to track each request. The hash key can represent something unique, like an IP address or client ID. Each field in the hash will represent a successful request.</p><pre>HSET bucket_name &lt;timestamp&gt; &quot;&quot;</pre><p>The HSET command creates a hash where the key (bucket_name) identifies the client, and the field (&lt;timestamp&gt;) marks the exact time of the request. The value related to this field is left empty since only the timestamp matters.</p><h4>2. <strong>Remove Expired Entries</strong></h4><p>To make sure only requests within a specific time window are kept, we can set a time-to-live for each field when adding it to the hash.</p><pre>HEXPIRE bucket_name 3600 FIELDS 1 &lt;timestamp&gt;</pre><p>This example sets the field to expire after 3600 seconds (1 hour). This way, only recent requests stay in the hash, ensuring the bucket reflects activity within the chosen time window.</p><h4>3. <strong>Count Requests in the Time Window</strong></h4><p>Use HLEN bucket_name to count the existing fields in the hash. This gives you the number of requests within the time window.</p><pre>HLEN bucket_name</pre><p>Compare this count to the allowed limit. <strong>If it’s over the limit, reject the new request. Otherwise, add the request to the bucket and allow it.</strong></p><p>Cool! Now that we understand the steps, let’s implement this in Java with Jedis!</p><h3>Implementing it with Jedis</h3><p><strong>Jedis</strong> is a popular library that makes it easy to work with <strong>Redis</strong> from <strong>Java</strong> applications.</p><p>Its API is simple and intuitive, which is perfect for implementing our rate limiter. We’ll use it to interact with Redis and handle all the commands we need for managing requests and enforcing limits.</p><h4>Start by adding the Jedis library to your Maven file:</h4><p>Check the latest version <a href="https://redis.io/docs/latest/develop/clients/jedis/">here</a>.</p><pre>&lt;dependency&gt;<br>    &lt;groupId&gt;redis.clients&lt;/groupId&gt;<br>    &lt;artifactId&gt;jedis&lt;/artifactId&gt;<br>    &lt;version&gt;5.2.0&lt;/version&gt;<br>&lt;/dependency&gt;</pre><h4>Create a SlidingWindowLogRateLimiter class:</h4><p>The class will take:</p><p>1. A Jedis instance.</p><p>2. A time window size (e.g., 60 seconds).</p><p>3. The maximum number of allowed requests.</p><pre>package io.redis;<br><br>import redis.clients.jedis.Jedis;<br>import redis.clients.jedis.Transaction;<br>import redis.clients.jedis.args.ExpiryOption;<br><br>public class SlidingWindowLogRateLimiter {<br>    private final Jedis jedis;<br>    private final int windowSize;<br>    private final int limit;<br><br>    public SlidingWindowLogRateLimiter(Jedis jedis, long windowSize, int limit) {<br>        this.jedis = jedis;<br>        this.limit = limit;<br>        this.windowSize = windowSize;<br>    }<br>}</pre><h4>Validate the Requests</h4><p>The main task of this rate limiter is to determine whether a client’s request falls within their allowed limit. If it does, the request is permitted, and the log is updated to include it. If it doesn’t, the request is denied without updating the log.</p><p><strong>Step 1: Generate a key<br></strong>We’ll store each client’s request count as a Redis key. To make keys unique for each client, we’ll format them like this:</p><pre>public boolean isAllowed(String clientId) {<br>    String key = &quot;rate_limit:&quot; + clientId;<br>}</pre><p>For example, if the client ID is user123, their key would be rate_limit:user123.</p><p><strong>Step 2: Fetch the current count and determine if the request is allowed<br></strong>To fetch the current count, we’ll use the HLEN that will return the number of fields in our hash or 0 when if the hash doesn’t exist yet.</p><p>To determine if the request is allowed to proceed, we’ll simply check if the current count is lower than the limit:</p><pre>long requestCount = jedis.hlen(key);<br>boolean isAllowed = requestCount &lt; limit;</pre><p><strong>Step 4: Update the bucket and return the result<br></strong>If the request is allowed, the next step is to add it to our Redis hash:</p><pre>if (isAllowed) {<br>    String fieldKey = UUID.randomUUID().toString();<br>    Transaction transaction = jedis.multi();<br>    transaction.hset(key, fieldKey, &quot;&quot;);<br>    transaction.hexpire(key, windowSize, fieldKey);<br>    var result = transaction.exec();<br>}</pre><p>We’ll do this in a <strong>transaction</strong> to ensure that:<br>- Both HSET and HEXPIRE happen together, avoiding race conditions.<br>- Both HSET and HEXPIRE are pipelined (sent in a batch to Redis) to reduce the number of network trips, improving performance.</p><p>Besides that, to make sure there are no duplicate entries even if multiple requests arrive at the same millisecond, we’ll generate a random UUID to serve as a unique key.</p><p>A new Redis transaction is then started to handle the logging operations atomically. First, the HSET command adds the new request to the hash with the random UUID as its field.</p><p>Next, the HEXPIRE command sets a time-to-live (TTL) on the field key. This ensures the field is automatically cleaned up once the time window has passed, preventing unnecessary storage of stale data and keeping the bucket updated with all valid requests within the time window.</p><p>If the execution of the transaction returns an empty result, it means that something went wrong on Redis and that the operations didn’t succeed. For the sake of simplicity, we’ll handle such cases by throwing an exception:</p><pre>if (result.isEmpty()) {<br>     throw new IllegalStateException(&quot;Empty result from Redis transaction&quot;);<br>}</pre><p>Finally, the transaction is executed, and the result of isAllowed is returned.</p><pre>return isAllowed;</pre><h4>Complete Implementation</h4><p>Here’s the full code for the SlidingWindowLogRateLimiter class:</p><pre>public boolean isAllowed(String clientId) {<br>    String key = &quot;rate_limit:&quot; + clientId;<br>    long requestCount = jedis.hlen(key);<br>    boolean isAllowed = requestCount &lt; limit;<br><br>    if (isAllowed) {<br>        String fieldKey = UUID.randomUUID().toString();<br>        Transaction transaction = jedis.multi();<br>        transaction.hset(key, fieldKey, &quot;&quot;);<br>        transaction.hexpire(key, windowSize, fieldKey);<br>        var result = transaction.exec();<br><br>        if (result.isEmpty()) {<br>            throw new IllegalStateException(&quot;Empty result from Redis transaction&quot;);<br>        }<br>    }<br><br>    return isAllowed;<br>}</pre><p>And we’re ready to start testing its behavior!</p><h3>Testing our Rate Limiter</h3><p>To ensure our Sliding Window Log Rate Limiter behaves as expected, we’ll write tests for various scenarios. For this, we’ll use three tools:</p><p>1. <strong>Redis TestContainers</strong>: This library spins up an isolated Redis container for testing. This means we don’t need to rely on an external Redis server during our tests. Once the tests are done, the container is stopped, leaving no leftover data.</p><p>2. <strong>JUnit 5</strong>: Our main testing framework, which helps us define and structure tests with lifecycle methods like @BeforeEach and @AfterEach.</p><p>3. <strong>AssertJ</strong>: A library that makes assertions readable and expressive, like assertThat(result).isTrue().</p><p>Let’s begin by adding the necessary dependencies to our pom.xml.</p><h4>Adding Dependencies</h4><p>Here’s what you’ll need in your Maven pom.xml file:</p><pre>&lt;dependency&gt;<br>    &lt;groupId&gt;org.junit.jupiter&lt;/groupId&gt;<br>    &lt;artifactId&gt;junit-jupiter-engine&lt;/artifactId&gt;<br>    &lt;version&gt;5.10.0&lt;/version&gt;<br>    &lt;scope&gt;test&lt;/scope&gt;<br>&lt;/dependency&gt;<br>&lt;dependency&gt;<br>    &lt;groupId&gt;com.redis&lt;/groupId&gt;<br>    &lt;artifactId&gt;testcontainers-redis&lt;/artifactId&gt;<br>    &lt;version&gt;2.2.2&lt;/version&gt;<br>    &lt;scope&gt;test&lt;/scope&gt;<br>&lt;/dependency&gt;<br>&lt;dependency&gt;<br>    &lt;groupId&gt;org.assertj&lt;/groupId&gt;<br>    &lt;artifactId&gt;assertj-core&lt;/artifactId&gt;<br>    &lt;version&gt;3.11.1&lt;/version&gt;<br>    &lt;scope&gt;test&lt;/scope&gt;<br>&lt;/dependency&gt;</pre><p>Once you’ve added these dependencies, you’re ready to start writing your test class.</p><h4>Setting Up the Test Class</h4><p>The first step is to create a test class named SlidingWindowLogRateLimiterTest. Inside, we’ll define three main components:</p><p>1. <strong>Redis Test Container</strong>: This launches a Redis instance in a Docker container.</p><p>2. <strong>Jedis Instance</strong>: This connects to the Redis container for sending commands.</p><p>3. <strong>Rate Limiter</strong>: The actual SlidingWindowLogRateLimiterTest instance we’re testing.</p><p>Here’s how the skeleton of our test class looks:</p><pre>public class SlidingWindowLogRateLimiterTest {<br>    private static final RedisContainer redisContainer = new RedisContainer(&quot;redis:latest&quot;)<br>            .withExposedPorts(6379);<br>    private Jedis jedis;<br>    private SlidingWindowLogRateLimiterTest rateLimiter;<br><br>    // Start Redis container once before any tests run<br>    static {<br>        redisContainer.start();<br>    }<br>}</pre><h4>Preparing the Environment Before Each Test</h4><p>Before running any test, we need to ensure a clean Redis environment. Here’s what we’ll do:</p><p>1. <strong>Connect to Redis</strong>: Use a Jedis instance to connect to the Redis container.</p><p>2. <strong>Flush Data</strong>: Clear any leftover data in Redis to ensure consistent results for each test.</p><p>We’ll set this up in a method annotated with @BeforeEach, which runs before every test case.</p><pre>@BeforeEach<br>public void setup() {<br>    jedis = new Jedis(redisContainer.getHost(), redisContainer.getFirstMappedPort());<br>    jedis.flushAll();<br>}</pre><blockquote>FLUSHALL is an actual Redis command that deletes all the keys of all the existing databases. <a href="https://redis.io/docs/latest/commands/flushall/">Read more about it in the official documentation</a>.</blockquote><h4>Cleaning Up After Each Test</h4><p>After each test, we need to close the Jedis connection to free up resources. This ensures no lingering connections interfere with subsequent tests.</p><pre>@AfterEach<br>public void tearDown() {<br>    jedis.close();<br>}</pre><h4>Full Setup</h4><p>Here’s how the complete test class looks with everything in place:</p><pre>public class FixedWindowRateLimiterTest {<br>    private static final RedisContainer redisContainer = new RedisContainer(&quot;redis:latest&quot;)<br>            .withExposedPorts(6379);<br>    private Jedis jedis;<br>    private FixedWindowRateLimiter rateLimiter;<br><br>    static {<br>        redisContainer.start();<br>    }<br><br>    @BeforeEach<br>    public void setup() {<br>        jedis = new Jedis(redisContainer.getHost(), redisContainer.getFirstMappedPort());<br>        jedis.flushAll();<br>    }<br><br>    @AfterEach<br>    public void tearDown() {<br>        jedis.close();<br>    }<br>}</pre><h4>Verifying Requests Within the Limit</h4><p>This test ensures the rate limiter allows requests within the defined limit.</p><p>We configure it with a<strong> limit of</strong> <strong>5 requests</strong> and a <strong>10-second window</strong>, then call isAllowed(“client-1”) <strong>5 times</strong>. Each call should return true, confirming the rate limiter correctly tracks and permits requests under the limit.</p><pre>@Test<br>public void shouldAllowRequestsWithinLimit() {<br>    rateLimiter = new SlidingWindowLogRateLimiter(jedis, 5, 10);<br>    for (int i = 1; i &lt;= 5; i++) {<br>        assertThat(rateLimiter.isAllowed(&quot;client-1&quot;))<br>                .withFailMessage(&quot;Request &quot; + i + &quot; should be allowed&quot;)<br>                .isTrue();<br>    }<br>}</pre><h4>Verifying Requests Beyond the Limit</h4><p>This test ensures the rate limiter correctly denies requests once the defined limit is exceeded.</p><p>Configured with a <strong>limit of</strong> <strong>5 requests</strong> in a <strong>60-second window</strong>, we call isAllowed(“client-1”) <strong>5 times</strong> and expect all to return true. On the 6th call, it should return false, verifying the rate limiter blocks requests beyond the allowed limit.</p><pre>@Test<br>public void shouldDenyRequestsOnceLimitIsExceeded() {<br>    rateLimiter = new SlidingWindowLogRateLimiter(jedis, 5, 60);<br>    for (int i = 1; i &lt;= 5; i++) {<br>        assertThat(rateLimiter.isAllowed(&quot;client-1&quot;))<br>                .withFailMessage(&quot;Request &quot; + i + &quot; should be allowed&quot;)<br>                .isTrue();<br>    }<br><br>    assertThat(rateLimiter.isAllowed(&quot;client-1&quot;))<br>            .withFailMessage(&quot;Request beyond limit should be denied&quot;)<br>            .isFalse();<br>}</pre><h4><strong>Verifying Requests After Sliding Window Resets</strong></h4><p>This test ensures that the rate limiter correctly resets the sliding window and allows requests after the window duration has passed.</p><p>Configured with a <strong>limit of 5 requests</strong> and a <strong>1-second window</strong>, we first call isAllowed(“client-1”) 5 times and expect all to return true. On the 6th call, the rate limiter should return false, indicating that the limit has been reached.</p><p>After waiting for the sliding window to reset (1 second + a buffer), the next request is allowed, verifying that the sliding window correctly clears expired entries and permits new requests.</p><pre>@Test<br>public void shouldAllowRequestsAgainAfterSlidingWindowResets() throws InterruptedException {<br>    int limit = 5;<br>    String clientId = &quot;client-1&quot;;<br>    long windowSize = 1L;<br>    rateLimiter = new SlidingWindowLogRateLimiter(jedis, limit, windowSize);<br><br>    for (int i = 1; i &lt;= limit; i++) {<br>        assertThat(rateLimiter.isAllowed(clientId))<br>                .withFailMessage(&quot;Request &quot; + i + &quot; should be allowed&quot;)<br>                .isTrue();<br>    }<br><br>    assertThat(rateLimiter.isAllowed(clientId))<br>            .withFailMessage(&quot;Request beyond limit should be denied&quot;)<br>            .isFalse();<br><br>    Thread.sleep((windowSize + 1) * 1000);<br><br>    assertThat(rateLimiter.isAllowed(clientId))<br>            .withFailMessage(&quot;Request after window reset should be allowed&quot;)<br>            .isTrue();<br>}</pre><h4>Verifying Independent Handling of Multiple Clients</h4><p>This test ensures the rate limiter handles multiple clients independently.</p><p>Configured with a<strong> limit of 5 requests</strong> and a <strong>10-second window</strong>, the first 5 requests from <strong>client-1</strong> are allowed (true), while the 6th is denied (false).</p><p>Simultaneously, all 5 requests from <strong>client-2</strong> are allowed (true), confirming the rate limiter maintains separate counters for each client.</p><pre>@Test<br>public void shouldHandleMultipleClientsIndependently() {<br>    int limit = 5;<br>    String clientId1 = &quot;client-1&quot;;<br>    String clientId2 = &quot;client-2&quot;;<br>    long windowSize = 10L;<br>    rateLimiter = new SlidingWindowLogRateLimiter(jedis, limit, windowSize);<br><br>    for (int i = 1; i &lt;= limit; i++) {<br>        assertThat(rateLimiter.isAllowed(clientId1))<br>                .withFailMessage(&quot;Client 1 request &quot; + i + &quot; should be allowed&quot;)<br>                .isTrue();<br>    }<br><br>    assertThat(rateLimiter.isAllowed(clientId1))<br>            .withFailMessage(&quot;Client 1 request beyond limit should be denied&quot;)<br>            .isFalse();<br><br>    for (int i = 1; i &lt;= limit; i++) {<br>        assertThat(rateLimiter.isAllowed(clientId2))<br>                .withFailMessage(&quot;Client 2 request &quot; + i + &quot; should be allowed&quot;)<br>                .isTrue();<br>    }<br>}</pre><h4><strong>Verifying Gradual Request Allowance in Sliding Window</strong></h4><p>This test ensures that the sliding window rate limiter gradually allows requests as old requests expire from the window.</p><p>Configured with a<strong> limit of 3 requests</strong> and a <strong>4-second window</strong>, we initially call isAllowed(“client-1”) 3 times, each 1 second apart, and expect all to return true.</p><p>On the 4th call, the request is denied, confirming the limit has been reached.</p><p>After waiting 2 seconds, enough of the older requests have expired to allow one new request, verifying that the sliding window behaves dynamically and permits requests as the window progresses.</p><pre>    @Test<br>    public void shouldAllowRequestsAgainGraduallyInSlidingWindow() throws InterruptedException {<br>        int limit = 3;<br>        long windowSize = 4L;<br>        String clientId = &quot;client-1&quot;;<br>        rateLimiter = new SlidingWindowLogRateLimiter(jedis, limit, windowSize);<br><br>        for (int i = 1; i &lt;= limit; i++) {<br>            assertThat(rateLimiter.isAllowed(clientId))<br>                    .withFailMessage(&quot;Request &quot; + i + &quot; should be allowed&quot;)<br>                    .isTrue();<br>            Thread.sleep(1000);<br>        }<br><br>        assertThat(rateLimiter.isAllowed(clientId))<br>                .withFailMessage(&quot;Request beyond limit should be denied&quot;)<br>                .isFalse();<br><br>        Thread.sleep(2000);<br><br>        assertThat(rateLimiter.isAllowed(clientId))<br>                .withFailMessage(&quot;Request should be allowed in a sliding window&quot;)<br>                .isTrue();<br>    }</pre><h4>Verifying Denied Requests Are Not Counted</h4><p>This test ensures that requests denied by the rate limiter are not included in the request count.</p><p>Configured with a limit of <strong>3 requests </strong>and a <strong>5-second window</strong>, the first 3 requests (isAllowed(“client-1”)) are allowed (true), while the 4th is denied (false).</p><p>Afterward, the Redis key for the client is checked to confirm the stored count equals the limit (3), ensuring denied requests do not increase the counter.</p><pre>@Test<br>public void testRateLimitDeniedRequestsAreNotCounted() {<br>    int limit = 3;<br>    long windowSize = 4L;<br>    String clientId = &quot;client-1&quot;;<br>    rateLimiter = new SlidingWindowLogRateLimiter(jedis, limit, windowSize);<br><br>    for (int i = 1; i &lt;= limit; i++) {<br>        assertThat(rateLimiter.isAllowed(clientId))<br>                .withFailMessage(&quot;Request &quot; + i + &quot; should be allowed&quot;)<br>                .isTrue();<br>    }<br><br>    assertThat(rateLimiter.isAllowed(clientId))<br>            .withFailMessage(&quot;This request should be denied&quot;)<br>            .isFalse();<br><br>    String key = &quot;rate_limit:&quot; + clientId;<br>    long requestCount = jedis.zcard(key);<br>    assertThat((long) limit)<br>            .withFailMessage(&quot;The count (&quot; + requestCount + &quot;) should be equal to the limit (&quot; + limit + &quot;), not counting the denied request&quot;)<br>            .isEqualTo(requestCount);<br>}</pre><p>Is there any other behavior we should verify? Let me know in the comments!</p><p>The Sliding Window Log Rate Limiter is a smarter way to manage request rates, offering more precision compared to simpler methods. It takes advantage of <strong>Redis’s</strong> speed and reliability to keep things efficient.</p><p>Using commands like ZADD, ZREMRANGEBYSCORE, and ZCARD, we created a solution that tracks requests dynamically within a rolling time window. This ensures rate limits are applied smoothly without abrupt resets when the window changes.</p><p>We implemented the limiter in Java using Jedis, making it straightforward and easy to work with. To make sure it’s reliable, we tested it with Redis TestContainers, JUnit 5, and AssertJ in various scenarios.</p><p>This setup is a strong and flexible starting point for managing request limits and can be easily adapted to handle more advanced needs as they come up.</p><h4>GitHub Repo</h4><p>You can find this implementation in <strong>Java</strong> and <strong>Kotlin</strong>:</p><ul><li>Java (<a href="https://github.com/raphaeldelio/redis-rate-limiter-java-example/blob/main/src/main/java/io/redis/SlidingWindowLogRateLimiter.java">Implementation</a>, <a href="https://github.com/raphaeldelio/redis-rate-limiter-java-example/blob/main/src/test/java/io/redis/SlidingWindowLogHashAlternativeRateLimiterTest.java">Test</a>)</li><li>Kotlin (<a href="https://github.com/raphaeldelio/redis-rate-limiter-kotlin-example/blob/main/src/main/kotlin/org/example/SlidingWindowLogRateLimiter.kt">Implementation</a>, <a href="https://github.com/raphaeldelio/redis-rate-limiter-kotlin-example/blob/main/src/test/kotlin/io/redis/SlidingWindowLogHashAlternativeRateLimiterTest.kt">Test</a>)</li></ul><h4>Stay Curious!</h4><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=ba189940da9e" width="1" height="1" alt=""><hr><p><a href="https://medium.com/redis-with-raphael-de-lio/sliding-window-log-rate-limiter-redis-java-ba189940da9e">Sliding Window Log Rate Limiter (Redis &amp; Java)</a> was originally published in <a href="https://medium.com/redis-with-raphael-de-lio">Redis with Raphael De Lio</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Token Bucket Rate Limiter (Redis & Java)]]></title>
            <link>https://medium.com/redis-with-raphael-de-lio/token-bucket-rate-limiter-redis-java-8cd42f3f8a34?source=rss----a29f9dbf6d82---4</link>
            <guid isPermaLink="false">https://medium.com/p/8cd42f3f8a34</guid>
            <category><![CDATA[design-systems]]></category>
            <category><![CDATA[building-with-redis]]></category>
            <category><![CDATA[software-architecture]]></category>
            <category><![CDATA[redis]]></category>
            <category><![CDATA[java]]></category>
            <dc:creator><![CDATA[Raphael De Lio]]></dc:creator>
            <pubDate>Mon, 13 Jan 2025 14:06:16 GMT</pubDate>
            <atom:updated>2025-01-13T14:06:16.406Z</atom:updated>
            <content:encoded><![CDATA[<blockquote><a href="https://youtu.be/cfF6nXIpDwE">This article is also available on YouTube!</a></blockquote><figure><img alt="Bright yellow background with hexagonal patterns featuring a smiling person in glasses and text that reads ‘Maximum Burst Flexibility’ alongside the Redis logo, emphasizing Redis’s scalability and performance benefits." src="https://cdn-images-1.medium.com/max/1024/1*BBIoU40lHKnpyO3nNYIlKQ.png" /></figure><p>The <strong>Token Bucket</strong> algorithm is a flexible and efficient rate-limiting mechanism. It works by filling a bucket with tokens at a fixed rate (e.g., one token per second). Each request consumes a token, and if no tokens are available, the request is rejected. The bucket has a maximum capacity, so it can handle bursts of traffic as long as the burst doesn’t exceed the number of tokens in the bucket.</p><blockquote>Looking for a different rate limiter algorithm? <a href="https://raphaeldelio.medium.com/rate-limiting-with-redis-an-essential-guide-df798b1c63db?source=user_profile_page---------1-------------17e03c232bd9---------------">Check the essential guide.</a></blockquote><h4>Index</h4><ul><li><strong>Introduction</strong></li><li><strong>How the Token Bucket Rate Limiter Works</strong></li><li><strong>Implementation with Redis and Java</strong></li><li><strong>Testing with TestContainers and AssertJ</strong></li><li><strong>Conclusion (GitHub Repo)</strong></li></ul><h3>How It Works</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*7cDKq5yh5RD0ygvb3mVwfQ.gif" /></figure><h4>1. <strong>Define a Token Refill Rate</strong></h4><p>Set a rate at which tokens are added to the bucket, such as 1 token per second or 10 tokens per minute.</p><h4>2. <strong>Track Token Consumption</strong></h4><p>For each incoming request, deduct one token from the bucket.</p><h4>3. <strong>Refill Tokens</strong></h4><p>Continuously refill the bucket at the defined rate, up to its maximum capacity, ensuring unused tokens can accumulate for future bursts.</p><h4>4. <strong>Rate Limit Check</strong></h4><p>Before processing a request, check if there are enough tokens in the bucket. If the bucket is empty, reject the request until tokens are replenished.</p><h3>How to Implement It with Redis and Java</h3><p>For the <strong>Token Bucket Rate Limiter</strong>, Redis provides an efficient way to track tokens and implement the algorithm. Here’s how to do it:</p><h4>1. Retrieve current token count and last refill time</h4><p>First, retrieve the current token count and the last refill time:</p><pre>GET rate_limit:&lt;clientId&gt;:count  <br>GET rate_limit:&lt;clientId&gt;:lastRefill  </pre><p>If these keys don’t exist, initialize the token count to the bucket’s maximum capacity and set the current time as the last refill time using SET.</p><h4>2. Refill tokens if necessary and update the bucket</h4><p>Update the token count and last refill date time after processing each request:</p><pre>SET rate_limit:&lt;clientId&gt;:count &lt;new_token_count&gt;  <br>SET rate_limit:&lt;clientId&gt;:lastRefill &lt;current_time&gt;  </pre><h4>3. Allow or reject the request</h4><p>If tokens are available, allow the request and decrement the count by one using:</p><pre>DECR rate_limit:&lt;clientId&gt;:count</pre><h3>Implementing it with Jedis</h3><p><strong>Jedis</strong> is a popular Java library used to interact with <strong>Redis </strong>and we will use it for implementing our rate limiter because it provides a simple and intuitive API for executing Redis commands from JVM applications.</p><h4><strong>Add Jedis to Your Maven File</strong>:</h4><p>Check the latest version <a href="https://redis.io/docs/latest/develop/clients/jedis/">here</a>.</p><pre>&lt;dependency&gt;<br>    &lt;groupId&gt;redis.clients&lt;/groupId&gt;<br>    &lt;artifactId&gt;jedis&lt;/artifactId&gt;<br>    &lt;version&gt;5.2.0&lt;/version&gt;<br>&lt;/dependency&gt;</pre><h4>Create a <strong>TokenBucketRateLimiter</strong> class:</h4><p>The class will take:</p><p>1. Accept a Jedis instance.</p><p>2. Define the maximum capacity of the token bucket.</p><p>3. Specify the token refill rate (tokens per second).</p><pre>package io.redis;<br><br>import redis.clients.jedis.Jedis;<br>import redis.clients.jedis.Transaction;<br><br>public class TokenBucketRateLimiter {<br>    private final Jedis jedis;<br>    private final int bucketCapacity; // Maximum tokens the bucket can hold<br>    private final double refillRate; // Tokens refilled per second<br><br>    public TokenBucketRateLimiter(Jedis jedis, int bucketCapacity, double refillRate) {<br>        this.jedis = jedis;<br>        this.bucketCapacity = bucketCapacity;<br>        this.refillRate = refillRate;<br>    }<br>}</pre><h4>Validate the Requests</h4><p>The main task of this rate limiter is to determine whether a client has sufficient tokens to process their request. If yes, the request is allowed, and tokens are deducted. If not, the request is blocked.</p><p><strong>Step 1: Generate the keys<br></strong>We’ll store each client’s token count and last refill time in Redis using unique keys. The keys will look like this:</p><pre>public boolean isAllowed(String clientId) {<br>    String keyCount = &quot;rate_limit:&quot; + clientId + &quot;:count&quot;;<br>    String keyLastRefill = &quot;rate_limit:&quot; + clientId + &quot;:lastRefill&quot;;<br>}</pre><p>For example, if the client ID is user123, their keys would be rate_limit:user123:count and rate_limit:user123:lastRefill.</p><p><strong>Step 2: Fetch Current State<br></strong>We use Redis’s GET command to retrieve the current token count and the last refill time. If the keys don’t exist, we assume the bucket is full, and the last refill time is the current timestamp.</p><pre>public boolean isAllowed(String clientId) {<br>    String keyCount = &quot;rate_limit:&quot; + clientId + &quot;:count&quot;;<br>    String keyLastRefill = &quot;rate_limit:&quot; + clientId + &quot;:lastRefill&quot;;<br><br>    Transaction transaction = jedis.multi();<br>    transaction.get(keyLastRefill);<br>    transaction.get(keyCount);<br>    var results = transaction.exec();<br><br>    long currentTime = System.currentTimeMillis();<br>    long lastRefillTime = results.get(0) != null ? Long.parseLong((String) results.get(0)) : currentTime;<br>    int tokenCount = results.get(1) != null ? Integer.parseInt((String) results.get(1)) : bucketCapacity;<br>}</pre><p><strong>Step 3: Refill Tokens<br></strong>Calculate how many tokens should be added based on the time elapsed since the last refill. Ensure the bucket doesn’t exceed its maximum capacity.</p><pre>long elapsedTimeMs = currentTime - lastRefillTime;<br>double elapsedTimeSecs = elapsedTimeMs / 1000.0;<br>int tokensToAdd = (int) (elapsedTimeSecs * refillRate);<br><br>tokenCount = Math.min(bucketCapacity, tokenCount + tokensToAdd);</pre><p><strong>Step 4: Check Token Availability<br></strong>Compare the current token count to determine if the request can be allowed.<strong> If tokens are available, deduct one token; otherwise, block the request.</strong></p><pre>boolean isAllowed = tokenCount &gt; 0;<br><br>if (isAllowed) {<br>    tokenCount--;<br>}</pre><p><strong>Step 5: Update Redis<br></strong>We update the token count and last refill time in Redis. Use a transaction to ensure atomic updates:</p><pre>Transaction transaction = jedis.multi();<br>transaction.set(keyLastRefill, String.valueOf(currentTime)); // Update last refill time<br>transaction.set(keyCount, String.valueOf(tokenCount));       // Update token count<br>transaction.exec();</pre><h4>Complete Implementation</h4><p>Here’s the full code for the FixedWindowRateLimiter class:</p><pre>package io.redis;<br><br>import redis.clients.jedis.Jedis;<br>import redis.clients.jedis.Transaction;<br><br>public class TokenBucketRateLimiter {<br>    private final Jedis jedis;<br>    private final int bucketCapacity; // Maximum tokens the bucket can hold<br>    private final double refillRate; // Tokens refilled per second<br><br>    public TokenBucketRateLimiter(Jedis jedis, int bucketCapacity, double refillRate) {<br>        this.jedis = jedis;<br>        this.bucketCapacity = bucketCapacity;<br>        this.refillRate = refillRate;<br>    }<br><br>    public boolean isAllowed(String clientId) {<br>        String keyCount = &quot;rate_limit:&quot; + clientId + &quot;:count&quot;;<br>        String keyLastRefill = &quot;rate_limit:&quot; + clientId + &quot;:lastRefill&quot;;<br><br>        long currentTime = System.currentTimeMillis();<br><br>        // Fetch current state<br>        Transaction transaction = jedis.multi();<br>        transaction.get(keyLastRefill);<br>        transaction.get(keyCount);<br>        var results = transaction.exec();<br><br>        long lastRefillTime = results.get(0) != null ? Long.parseLong((String) results.get(0)) : currentTime;<br>        int tokenCount = results.get(1) != null ? Integer.parseInt((String) results.get(1)) : bucketCapacity;<br><br>        // Refill tokens<br>        long elapsedTimeMs = currentTime - lastRefillTime;<br>        double elapsedTimeSecs = elapsedTimeMs / 1000.0;<br>        int tokensToAdd = (int) (elapsedTimeSecs * refillRate);<br>        tokenCount = Math.min(bucketCapacity, tokenCount + tokensToAdd);<br><br>        // Check if the request is allowed<br>        boolean isAllowed = tokenCount &gt; 0;<br><br>        if (isAllowed) {<br>            tokenCount--; // Consume one token<br>        }<br><br>        // Update Redis state<br>        transaction = jedis.multi();<br>        transaction.set(keyLastRefill, String.valueOf(currentTime));<br>        transaction.set(keyCount, String.valueOf(tokenCount));<br>        transaction.exec();<br><br>        return isAllowed;<br>    }<br>}</pre><p>And we’re ready to start testing it’s behavior!</p><h3>Testing our Rate Limiter</h3><p>To ensure our Token Bucket Rate Limiter behaves as expected, we’ll write tests for various scenarios. For this, we’ll use three tools:</p><p>1. <strong>Redis TestContainers</strong>: This library spins up an isolated Redis container for testing. This means we don’t need to rely on an external Redis server during our tests. Once the tests are done, the container is stopped, leaving no leftover data.</p><p>2. <strong>JUnit 5</strong>: Our main testing framework, which helps us define and structure tests with lifecycle methods like @BeforeEach and @AfterEach.</p><p>3. <strong>AssertJ</strong>: A library that makes assertions readable and expressive, like assertThat(result).isTrue().</p><p>Let’s begin by adding the necessary dependencies to our pom.xml.</p><h4>Adding Dependencies</h4><p>Here’s what you’ll need in your Maven pom.xml file:</p><pre>&lt;dependency&gt;<br>    &lt;groupId&gt;org.junit.jupiter&lt;/groupId&gt;<br>    &lt;artifactId&gt;junit-jupiter-engine&lt;/artifactId&gt;<br>    &lt;version&gt;5.10.0&lt;/version&gt;<br>    &lt;scope&gt;test&lt;/scope&gt;<br>&lt;/dependency&gt;<br>&lt;dependency&gt;<br>    &lt;groupId&gt;com.redis&lt;/groupId&gt;<br>    &lt;artifactId&gt;testcontainers-redis&lt;/artifactId&gt;<br>    &lt;version&gt;2.2.2&lt;/version&gt;<br>    &lt;scope&gt;test&lt;/scope&gt;<br>&lt;/dependency&gt;<br>&lt;dependency&gt;<br>    &lt;groupId&gt;org.assertj&lt;/groupId&gt;<br>    &lt;artifactId&gt;assertj-core&lt;/artifactId&gt;<br>    &lt;version&gt;3.11.1&lt;/version&gt;<br>    &lt;scope&gt;test&lt;/scope&gt;<br>&lt;/dependency&gt;</pre><p>Once you’ve added these dependencies, you’re ready to start writing your test class.</p><h4>Setting Up the Test Class</h4><p>The first step is to create a test class named FixedWindowRateLimiterTest. Inside, we’ll define three main components:</p><p>1. <strong>Redis Test Container</strong>: This launches a Redis instance in a Docker container.</p><p>2. <strong>Jedis Instance</strong>: This connects to the Redis container for sending commands.</p><p>3. <strong>Rate Limiter</strong>: The actual TokenBucketRateLimiter instance we’re testing.</p><p>Here’s how the skeleton of our test class looks:</p><pre>public class TokenBucketRateLimiterTest {<br><br>    private static RedisContainer redisContainer;<br>    private Jedis jedis;<br>    private TokenBucketRateLimiter rateLimiter;</pre><h4>Preparing the Environment Before Each Test</h4><p>Before running any test, we need to ensure a clean Redis environment. Here’s what we’ll do:</p><p>1. <strong>Connect to Redis</strong>: Use a Jedis instance to connect to the Redis container.</p><p>2. <strong>Flush Data</strong>: Clear any leftover data in Redis to ensure consistent results for each test.</p><p>We’ll set this up in a method annotated with @BeforeEach, which runs before every test case.</p><pre>@BeforeAll<br>static void startContainer() {<br>    redisContainer = new RedisContainer(&quot;redis:latest&quot;);<br>    redisContainer.withExposedPorts(6379).start();<br>}<br><br>@BeforeEach<br>void setup() {<br>    jedis = new Jedis(redisContainer.getHost(), redisContainer.getFirstMappedPort());<br>    jedis.flushAll();<br>}</pre><blockquote>FLUSHALL is an actual Redis command that deletes all the keys of all the existing databases. <a href="https://redis.io/docs/latest/commands/flushall/">Read more about it in the official documentation</a>.</blockquote><h4>Cleaning Up After Each Test</h4><p>After each test, we need to close the Jedis connection to free up resources. This ensures no lingering connections interfere with subsequent tests.</p><pre>@AfterEach<br>void tearDown() {<br>    jedis.close();<br>}</pre><h4>Full Setup</h4><p>Here’s how the complete test class looks with everything in place:</p><pre>public class TokenBucketRateLimiterTest {<br><br>    private static RedisContainer redisContainer;<br>    private Jedis jedis;<br>    private TokenBucketRateLimiter rateLimiter;<br><br>    @BeforeAll<br>    static void startContainer() {<br>        redisContainer = new RedisContainer(&quot;redis:latest&quot;);<br>        redisContainer.withExposedPorts(6379).start();<br>    }<br><br>    @AfterAll<br>    static void stopContainer() {<br>        redisContainer.stop();<br>    }<br><br>    @BeforeEach<br>    void setup() {<br>        jedis = new Jedis(redisContainer.getHost(), redisContainer.getFirstMappedPort());<br>        jedis.flushAll();<br>    }<br><br>    @AfterEach<br>    void tearDown() {<br>        jedis.close();<br>    }<br>}</pre><h4>Verifying Requests Within the Bucket Capacity</h4><p>This test ensures the rate limiter allows requests within the defined bucket capacity.</p><p>We configure it with a<strong> capacity of</strong> <strong>5 tokens</strong> and a <strong>refill rate of one token per second</strong>, then call isAllowed(“client-1”) <strong>5 times</strong>.</p><p>Each call should return true, confirming the rate limiter correctly tracks and permits requests within the capacity.</p><pre>@Test<br>void shouldAllowRequestsWithinBucketCapacity() {<br>    rateLimiter = new TokenBucketRateLimiter(jedis, 5, 1.0);<br>    for (int i = 1; i &lt;= 5; i++) {<br>        assertThat(rateLimiter.isAllowed(&quot;client-1&quot;))<br>            .withFailMessage(&quot;Request %d should be allowed within bucket capacity&quot;, i)<br>            .isTrue();<br>    }<br>}</pre><h4>Verifying Requests Are Denied When Bucket is Empty</h4><p>This test ensures the rate limiter correctly denies requests once the bucket is empty.</p><p>Configured with a <strong>capacity of</strong> <strong>5 tokens</strong> and a <strong>refill rate of one token per second</strong>, we isAllowed(“client-1”) <strong>5 times</strong> and expect all to return true.</p><p>On the 6th call, it should return false, verifying the rate limiter blocks requests once the bucket is empty.</p><pre>@Test<br>void shouldDenyRequestsOnceBucketIsEmpty() {<br>    rateLimiter = new TokenBucketRateLimiter(jedis, 5, 1.0);<br>    for (int i = 1; i &lt;= 5; i++) {<br>        assertThat(rateLimiter.isAllowed(&quot;client-1&quot;))<br>            .withFailMessage(&quot;Request %d should be allowed within bucket capacity&quot;, i)<br>            .isTrue();<br>    }<br>    assertThat(rateLimiter.isAllowed(&quot;client-1&quot;))<br>        .withFailMessage(&quot;Request beyond bucket capacity should be denied&quot;)<br>        .isFalse();<br>}</pre><h4>Verifying Bucket is Gradually Refilled</h4><p>This test ensures the rate limiter refills the bucket correctly after every second.</p><p>Configured with a <strong>capacity of</strong> <strong>5 tokens</strong> and a <strong>refill rate of one token per second</strong>, the first 5 requests (isAllowed(“client-1”)) return true, while the 6th request is denied (false).</p><p>After waiting for two seconds, the next two requests are allowed and the third one is denied. Confirming the refilling behavior works as expected.</p><pre>    @Test<br>    void shouldRefillTokensGraduallyAndAllowRequestsOverTime() throws InterruptedException {<br>        rateLimiter = new TokenBucketRateLimiter(jedis, 5, 1.0);<br>        String clientId = &quot;client-1&quot;;<br><br>        for (int i = 1; i &lt;= 5; i++) {<br>            assertThat(rateLimiter.isAllowed(clientId))<br>                .withFailMessage(&quot;Request %d should be allowed within bucket capacity&quot;, i)<br>                .isTrue();<br>        }<br>        assertThat(rateLimiter.isAllowed(clientId))<br>            .withFailMessage(&quot;Request beyond bucket capacity should be denied&quot;)<br>            .isFalse();<br><br>        TimeUnit.SECONDS.sleep(2);<br><br>        assertThat(rateLimiter.isAllowed(clientId))<br>            .withFailMessage(&quot;Request after partial refill should be allowed&quot;)<br>            .isTrue();<br>        assertThat(rateLimiter.isAllowed(clientId))<br>            .withFailMessage(&quot;Second request after partial refill should be allowed&quot;)<br>            .isTrue();<br>        assertThat(rateLimiter.isAllowed(clientId))<br>            .withFailMessage(&quot;Request beyond available tokens should be denied&quot;)<br>            .isFalse();<br>    }</pre><h4>Verifying Independent Handling of Multiple Clients</h4><p>This test ensures the rate limiter handles multiple clients independently.</p><p>Configured with a <strong>capacity of</strong> <strong>5 tokens</strong> and a <strong>refill rate of one token per second</strong>, the first 5 requests (isAllowed(“client-1”)) return true, while the 6th request is denied (false).</p><p>Simultaneously, all 5 requests from <strong>client-2</strong> are allowed (true), confirming the rate limiter maintains separate counters for each client.</p><pre>@Test<br>void shouldHandleMultipleClientsIndependently() {<br>    rateLimiter = new TokenBucketRateLimiter(jedis, 5, 1.0);<br><br>    String clientId1 = &quot;client-1&quot;;<br>    String clientId2 = &quot;client-2&quot;;<br><br>    for (int i = 1; i &lt;= 5; i++) {<br>        assertThat(rateLimiter.isAllowed(clientId1))<br>            .withFailMessage(&quot;Client 1 request %d should be allowed&quot;, i)<br>            .isTrue();<br>    }<br>    assertThat(rateLimiter.isAllowed(clientId1))<br>        .withFailMessage(&quot;Client 1 request beyond bucket capacity should be denied&quot;)<br>        .isFalse();<br><br>    for (int i = 1; i &lt;= 5; i++) {<br>        assertThat(rateLimiter.isAllowed(clientId2))<br>            .withFailMessage(&quot;Client 2 request %d should be allowed&quot;, i)<br>            .isTrue();<br>    }<br>}</pre><h4>Verifying Token Refill Does Not Exceed Bucket Capacity</h4><p>This test verifies that the token bucket rate limiter correctly refills tokens up to the defined capacity without exceeding it.</p><p>Configured with a <strong>capacity of 3 tokens</strong> and a <strong>refill rate of 2 tokens per second</strong>, the first 3 requests (isAllowed(“client-1”)) return true, while the 4th request is denied (false), indicating the bucket is empty.</p><p>After waiting 3 seconds (enough to refill 6 tokens), the bucket refills only up to its maximum capacity of 3 tokens. The next 3 requests are allowed (true), but any additional request is denied (false), confirming that the rate limiter maintains the specified capacity limit regardless of refill surplus.</p><pre>@Test<br>void shouldRefillTokensUpToCapacityWithoutExceedingIt() throws InterruptedException {<br>    int capacity = 3;<br>    double refillRate = 2.0;<br>    String clientId = &quot;client-1&quot;;<br>    rateLimiter = new TokenBucketRateLimiter(jedis, capacity, refillRate);<br><br>    for (int i = 1; i &lt;= capacity; i++) {<br>        assertThat(rateLimiter.isAllowed(clientId))<br>            .withFailMessage(&quot;Request %d should be allowed within initial bucket capacity&quot;, i)<br>            .isTrue();<br>    }<br>    assertThat(rateLimiter.isAllowed(clientId))<br>        .withFailMessage(&quot;Request beyond bucket capacity should be denied&quot;)<br>        .isFalse();<br><br>    TimeUnit.SECONDS.sleep(3);<br><br>    for (int i = 1; i &lt;= capacity; i++) {<br>        assertThat(rateLimiter.isAllowed(clientId))<br>            .withFailMessage(&quot;Request %d should be allowed as bucket refills up to capacity&quot;, i)<br>            .isTrue();<br>    }<br>    assertThat(rateLimiter.isAllowed(clientId))<br>        .withFailMessage(&quot;Request beyond bucket capacity should be denied&quot;)<br>        .isFalse();<br>}</pre><h4>Verifying Denied Requests Do Not Affect Token Count</h4><p>This test ensures that the token bucket rate limiter does not count denied requests when updating the token count.</p><p>Configured with a <strong>capacity of 3 tokens</strong> and a <strong>refill rate of 0.5 tokens per second</strong>, the first 3 requests (isAllowed(“client-1”)) are allowed (true), depleting the bucket. The 4th request is denied (false), confirming the bucket is empty.</p><p>The Redis token count (rate_limit:client-1:count) is then verified to ensure it accurately reflects the remaining tokens (0 in this case) and does not include denied requests. This confirms that the rate limiter updates the token count only when requests are successfully processed.</p><pre>@Test<br>void testRateLimitDeniedRequestsAreNotCounted() {<br>    int capacity = 3;<br>    double refillRate = 0.5;<br>    String clientId = &quot;client-1&quot;;<br>    rateLimiter = new TokenBucketRateLimiter(jedis, capacity, refillRate);<br><br>    for (int i = 1; i &lt;= capacity; i++) {<br>        assertThat(rateLimiter.isAllowed(clientId))<br>            .withFailMessage(&quot;Request %d should be allowed&quot;, i)<br>            .isTrue();<br>    }<br>    assertThat(rateLimiter.isAllowed(clientId))<br>        .withFailMessage(&quot;This request should be denied&quot;)<br>        .isFalse();<br><br>    String key = &quot;rate_limit:&quot; + clientId + &quot;:count&quot;;<br>    int requestCount = Integer.parseInt(jedis.get(key));<br>    assertThat(requestCount)<br>        .withFailMessage(&quot;The count should match remaining tokens and not include denied requests&quot;)<br>        .isEqualTo(0);<br>}</pre><p>Is there any other behavior we should verify? Let me know in the comments!</p><p>The Token Bucket Rate Limiter is a flexible and efficient way to manage request rates, and <strong>Redis</strong> makes it incredibly fast and reliable.</p><p>By leveraging commands like GET, SET, and MULTI/EXEC, we implemented a solution that tracks token counts, refills tokens dynamically based on time elapsed, and ensures the bucket never exceeds its defined capacity.</p><p>Using <strong>Jedis</strong>, we built a clear and intuitive <strong>Java</strong> implementation, and with thorough testing using Redis TestContainers, JUnit 5, and AssertJ, we can confidently verify that it works as expected.</p><p>This approach offers a robust foundation for managing request limits while allowing for burst handling and gradual refill, making it adaptable for more advanced rate-limiting scenarios when needed.</p><h4>GitHub Repo</h4><p>You can find this implementation in <strong>Java</strong> and <strong>Kotlin</strong>:</p><ul><li>Java (<a href="https://github.com/raphaeldelio/redis-rate-limiter-java-example/tree/main/src/main/java/io/redis">Implementation</a>, <a href="https://github.com/raphaeldelio/redis-rate-limiter-java-example/blob/main/src/test/java/io/redis/TokenBucketRateLimiterTest.java">Test</a>)</li><li>Kotlin (<a href="https://github.com/raphaeldelio/redis-rate-limiter-kotlin-example/blob/main/src/main/kotlin/org/example/TokenBucketRateLimiter.kt">Implementation</a>, <a href="https://github.com/raphaeldelio/redis-rate-limiter-kotlin-example/blob/main/src/test/kotlin/org/example/TokenBucketRateLimiterTest.kt">Test</a>)</li></ul><h4>Stay Curious!</h4><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=8cd42f3f8a34" width="1" height="1" alt=""><hr><p><a href="https://medium.com/redis-with-raphael-de-lio/token-bucket-rate-limiter-redis-java-8cd42f3f8a34">Token Bucket Rate Limiter (Redis &amp; Java)</a> was originally published in <a href="https://medium.com/redis-with-raphael-de-lio">Redis with Raphael De Lio</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Fixed Window Counter Rate Limiter (Redis & Java)]]></title>
            <link>https://medium.com/redis-with-raphael-de-lio/fixed-window-counter-rate-limiter-redis-java-b7da0adfa79b?source=rss----a29f9dbf6d82---4</link>
            <guid isPermaLink="false">https://medium.com/p/b7da0adfa79b</guid>
            <category><![CDATA[java]]></category>
            <category><![CDATA[redis]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[system-design-interview]]></category>
            <category><![CDATA[building-with-redis]]></category>
            <dc:creator><![CDATA[Raphael De Lio]]></dc:creator>
            <pubDate>Mon, 30 Dec 2024 13:09:51 GMT</pubDate>
            <atom:updated>2025-01-22T11:29:51.363Z</atom:updated>
            <content:encoded><![CDATA[<blockquote><a href="https://youtu.be/Ki3WKSNpdRU">This article is also available on YouTube!</a></blockquote><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*GkZRBfmAXCFt7sNYaroz5w.png" /></figure><p>The <strong>Fixed Window Counter</strong> is the simplest and most straightforward rate-limiting algorithm. It divides time into fixed intervals (e.g., seconds, minutes, or hours) and counts the number of requests within each interval. If the count exceeds a predefined threshold, the requests are rejected until the next interval begins.</p><blockquote>Looking for a more precise algorithm? <a href="https://medium.com/redis-with-raphael-de-lio/sliding-window-log-rate-limiter-redis-java-ba189940da9e">Take a look at the Sliding Window Log implementation.</a></blockquote><h4>Index</h4><ul><li><strong>Introduction</strong></li><li><strong>How the Fixed Window Counter Rate Limiter Works</strong></li><li><strong>Implementation with Redis and Java</strong></li><li><strong>Testing with TestContainers and AssertJ</strong></li><li><strong>Conclusion (GitHub Repo)</strong></li></ul><h3><strong>How It Works</strong></h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*VsdNn5KGd1A0rIfbczGy8Q.gif" /></figure><h4><strong>1. Define a Window Interval</strong></h4><p>Choose a time interval, such as 1 second, 1 minute, or 1 hour.</p><h4>2. <strong>Track Requests</strong></h4><p>Use a counter to track the number of requests made during the current window.</p><h4>3. <strong>Reset Counter:</strong></h4><p>At the end of the time window, reset the counter to zero and start counting again for the new window.</p><h4>4. <strong>Rate Limit Check:</strong></h4><p>Compare the counter against the allowed limit. If it exceeds the limit, reject further requests until the next window.</p><h3>How to Implement It with Redis and Java</h3><p>There are two ways to implement the Fixed Rate Limiter with Redis. The simplest way is by:</p><h4>1. Use the INCR command to increment the counter in Redis each time a request is allowed</h4><pre>INCR my_counter</pre><p>If there&#39;s no counter set yet, the INCR command will create one as zero and then increment it to one.</p><p>If the counter is already set, the INCR commany will simply increment it by one.</p><h4>2. Set the key to expire in one minute if it’s newly created</h4><p>If the counter doesn’t exist, we need to set a time-to-live to ensure the time window lasts only for the specified period. <strong>But we should only set an expiration if it doesn’t already exist</strong>. Otherwise, Redis would reset the expiration, and older requests could be counted beyond the allowed time.</p><p>We’ll use the EXPIRE command with the NX flag on the key. <strong>The </strong><strong>NX flag ensures the expiration is only set if the key doesn’t already have one.</strong></p><p>This approach is smart because the counter will only track requests during the key’s lifespan. <strong>Once the key expires and is removed, the counter resets, ensuring we only account for requests within the intended time window.</strong></p><pre>EXPIRE my_counter 60 NX</pre><h4>3. Check the counter for each new request</h4><p>When a new request comes in, check the counter to see how many requests have been made. If it’s below the threshold, allow the process and increment the counter. If not, block the process from proceeding.</p><blockquote>If the key doesn’t exist, assume the counter starts at 0.</blockquote><pre>GET my_counter</pre><p>Cool! Now that we understand the basics of our implementation, let’s implement it in Java with Jedis.</p><h3>Implementing it with Jedis</h3><p><strong>Jedis</strong> is a popular Java library used to interact with <strong>Redis </strong>and we will use it for implementing our rate because it provides a simple and intuitive API for executing Redis commands from JVM applications.</p><h4>Start by adding the Jedis library to your Maven file:</h4><p>Check the latest version <a href="https://redis.io/docs/latest/develop/clients/jedis/">here</a>.</p><pre>&lt;dependency&gt;<br>    &lt;groupId&gt;redis.clients&lt;/groupId&gt;<br>    &lt;artifactId&gt;jedis&lt;/artifactId&gt;<br>    &lt;version&gt;5.2.0&lt;/version&gt;<br>&lt;/dependency&gt;</pre><h4>Create a FixedWindowRateLimiter class:</h4><p>The class will take:</p><p>1. A Jedis instance.</p><p>2. A time window size (e.g., 60 seconds).</p><p>3. The maximum number of allowed requests.</p><pre>package io.redis;<br><br>import redis.clients.jedis.Jedis;<br>import redis.clients.jedis.Transaction;<br>import redis.clients.jedis.args.ExpiryOption;<br><br>public class FixedWindowRateLimiter {<br><br>    private final Jedis jedis;<br>    private final int windowSize;<br>    private final int limit;<br><br>    public FixedWindowRateLimiter(Jedis jedis, long windowSize, int limit) {<br>        this.jedis = jedis;<br>        this.limit = limit;<br>        this.windowSize = windowSize;<br>    }<br>}</pre><h4>Validate the Requests</h4><p>The main job of this rate limiter is to check if a client is within their allowed request limit. If yes, the request is allowed, and the counter is updated. If not, the request is blocked.</p><p><strong>Step 1: Generate a key<br></strong>We’ll store each client’s request count as a Redis key. To make keys unique for each client, we’ll format them like this:</p><pre>public boolean isAllowed(String clientId) {<br>    String key = &quot;rate_limit:&quot; + clientId;<br>}</pre><p>For example, if the client ID is user123, their key would be rate_limit:user123.</p><p><strong>Step 2: Fetch the Current Counter<br></strong>We’ll use Redis’s GET command to check how many requests the client has made so far. If the key doesn’t exist, we assume the client hasn’t made any requests, so the counter is 0.</p><pre>public boolean isAllowed(String clientId) {<br>    String key = &quot;rate_limit:&quot; + clientId;<br>    String currentCountStr = jedis.get(key);<br>    int currentCount = currentCountStr != null ? Integer.parseInt(currentCountStr) : 0;<br>}</pre><p><strong>Step 3: Check the Request Limit<br></strong>Next, we compare the current count to the allowed limit. If the counter is less than the limit, the request is allowed. Otherwise, it’s blocked.</p><pre>public boolean isAllowed(String clientId) {<br>    String key = &quot;rate_limit:&quot; + clientId;<br>    String currentCountStr = jedis.get(key);<br>    int currentCount = currentCountStr != null ? Integer.parseInt(currentCountStr) : 0;<br><br>    boolean isAllowed = currentCount &lt; limit;<br>}</pre><p><strong>Step 4: Increment the Counter and Set Expiration<br>If the request is allowed</strong>, we need to do two things:</p><p>1. <strong>Increment the Counter</strong>: Use the Redis INCR command to increase the request count by 1.</p><p>2. <strong>Set an Expiration</strong>: Use the EXPIRE command to ensure the counter resets at the end of the time window. To make sure the expiration won’t reset everytime we increment the counter, we also need to set the NX flag.</p><p>We’ll do this in a <strong>transaction</strong> to ensure that:<br>- Both INCR and EXPIRE happen together, avoiding race conditions.<br>- Both INCR and EXPIRE are pipelined (sent in a batch to Redis) to reduce the number of network trips, improving performance.</p><pre>if (isAllowed) {<br>    Transaction transaction = jedis.multi();<br>    transaction.incr(key); // Increment the counter<br>    transaction.expire(key, windowSize, ExpiryOption.NX); // Set expiration only if not already set<br>    transaction.exec(); // Execute both commands atomically<br>}</pre><blockquote>The first request marks the start of the time window. Any subsequent requests during this window’s lifespan will increment the counter.</blockquote><blockquote>Once the window expires, the key is automatically removed from Redis. The next request after that will define the start of a new window.</blockquote><blockquote>If we didn’t set the NX flag, the expiration would be reset everytime the counter is incremented, increasing the lifespan of the window.</blockquote><h4><strong>Complete Implementation</strong></h4><p>Here’s the full code for the FixedWindowRateLimiter class:</p><pre>package io.redis;<br><br>import redis.clients.jedis.Jedis;<br>import redis.clients.jedis.Transaction;<br>import redis.clients.jedis.args.ExpiryOption;<br><br>public class FixedWindowRateLimiter {<br><br>    private final Jedis jedis;<br>    private final int windowSize;<br>    private final int limit;<br><br>    public FixedWindowRateLimiter(Jedis jedis, long windowSize, int limit) {<br>        this.jedis = jedis;<br>        this.limit = limit;<br>        this.windowSize = windowSize;<br>    }<br><br>    public boolean isAllowed(String clientId) {<br>        String key = &quot;rate_limit:&quot; + clientId;<br>        String currentCountStr = jedis.get(key);<br>        int currentCount = currentCountStr != null ? Integer.parseInt(currentCountStr) : 0;<br>        <br>        boolean isAllowed = currentCount &lt; limit;<br>    <br>        if (isAllowed) {<br>            Transaction transaction = jedis.multi();<br>            transaction.incr(key);<br>            transaction.expire(key, windowSize, ExpiryOption.NX); // Set expire only if not set<br>            transaction.exec();<br>        }<br>    <br>        return isAllowed;<br>    }<br>}</pre><p>And we’re ready to start testing it’s behavior!</p><h3>Testing our Rate Limiter</h3><p>To ensure our Fixed Window Rate Limiter behaves as expected, we’ll write tests for various scenarios. For this, we’ll use three tools:</p><p>1. <strong>Redis TestContainers</strong>: This library spins up an isolated Redis container for testing. This means we don’t need to rely on an external Redis server during our tests. Once the tests are done, the container is stopped, leaving no leftover data.</p><p>2. <strong>JUnit 5</strong>: Our main testing framework, which helps us define and structure tests with lifecycle methods like @BeforeEach and @AfterEach.</p><p>3. <strong>AssertJ</strong>: A library that makes assertions readable and expressive, like assertThat(result).isTrue().</p><p>Let’s begin by adding the necessary dependencies to our pom.xml.</p><h4>Adding Dependencies</h4><p>Here’s what you’ll need in your Maven pom.xml file:</p><pre>&lt;dependency&gt;<br>    &lt;groupId&gt;org.junit.jupiter&lt;/groupId&gt;<br>    &lt;artifactId&gt;junit-jupiter-engine&lt;/artifactId&gt;<br>    &lt;version&gt;5.10.0&lt;/version&gt;<br>    &lt;scope&gt;test&lt;/scope&gt;<br>&lt;/dependency&gt;<br><br>&lt;dependency&gt;<br>    &lt;groupId&gt;com.redis&lt;/groupId&gt;<br>    &lt;artifactId&gt;testcontainers-redis&lt;/artifactId&gt;<br>    &lt;version&gt;2.2.2&lt;/version&gt;<br>    &lt;scope&gt;test&lt;/scope&gt;<br>&lt;/dependency&gt;<br><br>&lt;dependency&gt;<br>    &lt;groupId&gt;org.assertj&lt;/groupId&gt;<br>    &lt;artifactId&gt;assertj-core&lt;/artifactId&gt;<br>    &lt;version&gt;3.11.1&lt;/version&gt;<br>    &lt;scope&gt;test&lt;/scope&gt;<br>&lt;/dependency&gt;</pre><p>Once you’ve added these dependencies, you’re ready to start writing your test class.</p><h4>Setting Up the Test Class</h4><p>The first step is to create a test class named FixedWindowRateLimiterTest. Inside, we’ll define three main components:</p><p>1. <strong>Redis Test Container</strong>: This launches a Redis instance in a Docker container.</p><p>2. <strong>Jedis Instance</strong>: This connects to the Redis container for sending commands.</p><p>3. <strong>Rate Limiter</strong>: The actual FixedWindowRateLimiter instance we’re testing.</p><p>Here’s how the skeleton of our test class looks:</p><pre>public class FixedWindowRateLimiterTest {<br><br>    private static final RedisContainer redisContainer = new RedisContainer(&quot;redis:latest&quot;)<br>            .withExposedPorts(6379);<br><br>    private Jedis jedis;<br>    private FixedWindowRateLimiter rateLimiter;<br><br>    // Start Redis container once before any tests run<br>    static {<br>        redisContainer.start();<br>    }<br>}</pre><h4><strong>Preparing the Environment Before Each Test</strong></h4><p>Before running any test, we need to ensure a clean Redis environment. Here’s what we’ll do:</p><p>1. <strong>Connect to Redis</strong>: Use a Jedis instance to connect to the Redis container.</p><p>2. <strong>Flush Data</strong>: Clear any leftover data in Redis to ensure consistent results for each test.</p><p>We’ll set this up in a method annotated with @BeforeEach, which runs before every test case.</p><pre>@BeforeEach<br>public void setup() {<br>    jedis = new Jedis(redisContainer.getHost(), redisContainer.getFirstMappedPort());<br>    jedis.flushAll();<br>}</pre><blockquote>FLUSHALL is an actual Redis command that deletes all the keys of all the existing databases. <a href="https://redis.io/docs/latest/commands/flushall/">Read more about it in the official documentation</a>.</blockquote><h4><strong>Cleaning Up After Each Test</strong></h4><p>After each test, we need to close the Jedis connection to free up resources. This ensures no lingering connections interfere with subsequent tests.</p><pre>@AfterEach<br>public void tearDown() {<br>    jedis.close();<br>}</pre><h4><strong>Full Setup</strong></h4><p>Here’s how the complete test class looks with everything in place:</p><pre>public class FixedWindowRateLimiterTest {<br>    private static final RedisContainer redisContainer = new RedisContainer(&quot;redis:latest&quot;)<br>            .withExposedPorts(6379);<br><br>    private Jedis jedis;<br>    private FixedWindowRateLimiter rateLimiter;<br><br>    static {<br>        redisContainer.start();<br>    }<br><br>    @BeforeEach<br>    public void setup() {<br>        jedis = new Jedis(redisContainer.getHost(), redisContainer.getFirstMappedPort());<br>        jedis.flushAll();<br>    }<br><br>    @AfterEach<br>    public void tearDown() {<br>        jedis.close();<br>    }<br>}</pre><h4><strong>Verifying Requests Within the Limit</strong></h4><p>This test ensures the rate limiter allows requests within the defined limit.</p><p>We configure it with a<strong> limit of</strong> <strong>5 requests</strong> and a <strong>10-second window</strong>, then call isAllowed(“client-1”) <strong>5 times</strong>. Each call should return true, confirming the rate limiter correctly tracks and permits requests under the limit.</p><pre>@Test<br>public void shouldAllowRequestsWithinLimit() {<br>    rateLimiter = new FixedWindowRateLimiter(jedis, 10, 5);<br>    for (int i = 1; i &lt;= 5; i++) {<br>        assertThat(rateLimiter.isAllowed(&quot;client-1&quot;))<br>                .withFailMessage(&quot;Request &quot; + i + &quot; should be allowed&quot;)<br>                .isTrue();<br>    }<br>}</pre><h4>Verifying <strong>Requests Beyond the Limit</strong></h4><p>This test ensures the rate limiter correctly denies requests once the defined limit is exceeded.</p><p>Configured with a <strong>limit of</strong> <strong>5 requests</strong> in a <strong>60-second window</strong>, we call isAllowed(“client-1”) <strong>5 times</strong> and expect all to return true. On the 6th call, it should return false, verifying the rate limiter blocks requests beyond the allowed limit.</p><pre>@Test<br>public void shouldDenyRequestsOnceLimitIsExceeded() {<br>    rateLimiter = new FixedWindowRateLimiter(jedis, 60, 5);<br>    for (int i = 1; i &lt;= 5; i++) {<br>        assertThat(rateLimiter.isAllowed(&quot;client-1&quot;))<br>                .withFailMessage(&quot;Request &quot; + i + &quot; should be allowed&quot;)<br>                .isTrue();<br>    }<br><br>    assertThat(rateLimiter.isAllowed(&quot;client-1&quot;))<br>            .withFailMessage(&quot;Request beyond limit should be denied&quot;)<br>            .isFalse();<br>}</pre><h4><strong>Verifying Requests After Window Reset</strong></h4><p>This test ensures the rate limiter resets correctly after the fixed window expires.</p><p>Configured with a <strong>limit of 5 requests</strong> and a <strong>1-second window</strong>, the first 5 requests (isAllowed(“client-1”)) return true, while the 6th request is denied (false).</p><p>After waiting for the window to expire, the next request is allowed (true), confirming the reset behavior works as expected.</p><pre>@Test<br>public void shouldAllowRequestsAgainAfterFixedWindowResets() throws InterruptedException {<br>    int limit = 5;<br>    String clientId = &quot;client-1&quot;;<br>    int windowSize = 1;<br>    rateLimiter = new FixedWindowRateLimiter(jedis, windowSize, limit);<br><br>    for (int i = 1; i &lt;= limit; i++) {<br>        assertThat(rateLimiter.isAllowed(clientId))<br>                .withFailMessage(&quot;Request &quot; + i + &quot; should be allowed&quot;)<br>                .isTrue();<br>    }<br><br>    assertThat(rateLimiter.isAllowed(clientId))<br>            .withFailMessage(&quot;Request beyond limit should be denied&quot;)<br>            .isFalse();<br><br>    Thread.sleep((windowSize + 1) * 1000);<br><br>    assertThat(rateLimiter.isAllowed(clientId))<br>            .withFailMessage(&quot;Request after window reset should be allowed&quot;)<br>            .isTrue();<br>}</pre><h4><strong>Verifying Independent Handling of Multiple Clients</strong></h4><p>This test ensures the rate limiter handles multiple clients independently.</p><p>Configured with a<strong> limit of 5 requests</strong> and a <strong>10-second window</strong>, the first 5 requests from <strong>client-1</strong> are allowed (true), while the 6th is denied (false).</p><p>Simultaneously, all 5 requests from <strong>client-2</strong> are allowed (true), confirming the rate limiter maintains separate counters for each client.</p><pre>@Test<br>public void shouldHandleMultipleClientsIndependently() {<br>    int limit = 5;<br>    String clientId1 = &quot;client-1&quot;;<br>    String clientId2 = &quot;client-2&quot;;<br>    int windowSize = 10;<br>    rateLimiter = new FixedWindowRateLimiter(jedis, windowSize, limit);<br><br>    for (int i = 1; i &lt;= limit; i++) {<br>        assertThat(rateLimiter.isAllowed(clientId1))<br>                .withFailMessage(&quot;Client 1 request &quot; + i + &quot; should be allowed&quot;)<br>                .isTrue();<br>    }<br><br>    assertThat(rateLimiter.isAllowed(clientId1))<br>            .withFailMessage(&quot;Client 1 request beyond limit should be denied&quot;)<br>            .isFalse();<br><br>    for (int i = 1; i &lt;= limit; i++) {<br>        assertThat(rateLimiter.isAllowed(clientId2))<br>                .withFailMessage(&quot;Client 2 request &quot; + i + &quot; should be allowed&quot;)<br>                .isTrue();<br>    }<br>}</pre><h4><strong>Verifying Requests Are Denied Until Fixed Window Resets</strong></h4><p>This test ensures the rate limiter denies additional requests until the fixed window expires.</p><p>Configured with a <strong>limit of 3 requests</strong> and a <strong>5-second window</strong>, the first 3 requests (isAllowed(“client-1”)) are allowed (true), while the 4th is denied (false).</p><p>After waiting for half the window duration (2.5 seconds), requests are still denied (false).</p><p>Once the window fully resets (after another 2.5 seconds), the next request is allowed (true), confirming proper behavior during and after the fixed window.</p><pre>@Test<br>public void shouldDenyAdditionalRequestsUntilFixedWindowResets() throws InterruptedException {<br>    int limit = 3;<br>    int windowSize = 5;<br>    String clientId = &quot;client-1&quot;;<br>    rateLimiter = new FixedWindowRateLimiter(jedis, windowSize, limit);<br><br>    for (int i = 1; i &lt;= limit; i++) {<br>        assertThat(rateLimiter.isAllowed(clientId))<br>                .withFailMessage(&quot;Request &quot; + i + &quot; should be allowed within limit&quot;)<br>                .isTrue();<br>    }<br><br>    assertThat(rateLimiter.isAllowed(clientId))<br>            .withFailMessage(&quot;Request beyond limit should be denied&quot;)<br>            .isFalse();<br><br>    Thread.sleep(2500);<br><br>    assertThat(rateLimiter.isAllowed(clientId))<br>            .withFailMessage(&quot;Request should still be denied within the same fixed window&quot;)<br>            .isFalse();<br><br>    Thread.sleep(2500);<br><br>    assertThat(rateLimiter.isAllowed(clientId))<br>            .withFailMessage(&quot;Request should be allowed after fixed window reset&quot;)<br>            .isTrue();<br>}</pre><h4><strong>Verifying Denied Requests Are Not Counted</strong></h4><p>This test ensures that requests denied by the rate limiter are not included in the request count.</p><p>Configured with a limit of 3 requests and a 5-second window, the first 3 requests (isAllowed(“client-1”)) are allowed (true), while the 4th is denied (false).</p><p>Afterward, the Redis key for the client is checked to confirm the stored count equals the limit (3), ensuring denied requests do not increase the counter.</p><pre>@Test<br>public void testRateLimitDeniedRequestsAreNotCounted() {<br>    int limit = 3;<br>    int windowSize = 5;<br>    String clientId = &quot;client-1&quot;;<br>    rateLimiter = new FixedWindowRateLimiter(jedis, windowSize, limit);<br><br>    for (int i = 1; i &lt;= limit; i++) {<br>        assertThat(rateLimiter.isAllowed(clientId))<br>                .withFailMessage(&quot;Request &quot; + i + &quot; should be allowed&quot;)<br>                .isTrue();<br>    }<br><br>    assertThat(rateLimiter.isAllowed(clientId))<br>            .withFailMessage(&quot;This request should be denied&quot;)<br>            .isFalse();<br><br>    String key = &quot;rate_limit:&quot; + clientId;<br>    int requestCount = Integer.parseInt(jedis.get(key));<br>    assertThat(requestCount)<br>            .withFailMessage(&quot;The count (&quot; + requestCount + &quot;) should be equal to the limit (&quot; + limit + &quot;), not counting the denied request&quot;)<br>            .isEqualTo(limit);<br>}</pre><p>Is there any other behavior we should verify? Let me know in the comments!</p><p>The Fixed Window Rate Limiter is a simple yet effective way to manage request rates, and <strong>Redis</strong> makes it incredibly fast and reliable.</p><p>By using commands like INCR and EXPIRE, we created a solution that tracks and limits requests while automatically resetting counters when the time window expires.</p><p>With <strong>Jedis</strong>, we built an easy-to-understand Java implementation, and thanks to thorough testing with Redis TestContainers, JUnit 5, and AssertJ, we can trust it works as expected.</p><p>This approach is a great starting point for handling request limits and can easily be adapted for more complex scenarios if needed.</p><h4>GitHub Repo</h4><p>You can find this implementation in <strong>Java</strong> and <strong>Kotlin</strong>:</p><ul><li>Java (<a href="https://github.com/raphaeldelio/redis-rate-limiter-java-example/blob/main/src/main/java/io/redis/FixedWindowRateLimiter.java">Implementation</a>, <a href="https://github.com/raphaeldelio/redis-rate-limiter-java-example/blob/main/src/test/java/io/redis/FixedWindowRateLimiterTest.java">Test</a>)</li><li>Kotlin (<a href="https://github.com/raphaeldelio/redis-rate-limiter-kotlin-example/blob/main/src/main/kotlin/org/example/FixedWindowRateLimiter.kt">Implementation</a>, <a href="https://github.com/raphaeldelio/redis-rate-limiter-kotlin-example/blob/main/src/test/kotlin/org/example/FixedWindowRateLimiterTest.kt">Test</a>)</li></ul><h4>Stay Curious!</h4><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=b7da0adfa79b" width="1" height="1" alt=""><hr><p><a href="https://medium.com/redis-with-raphael-de-lio/fixed-window-counter-rate-limiter-redis-java-b7da0adfa79b">Fixed Window Counter Rate Limiter (Redis &amp; Java)</a> was originally published in <a href="https://medium.com/redis-with-raphael-de-lio">Redis with Raphael De Lio</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
    </channel>
</rss>