标签：#backend

It's easy to reach for the popular tool before asking what your system actually needs. For job queueing, the usual advice is to use RabbitMQ or Kafka. The underlying burden of using these tools will be additional processes to deploy, monitor and reason about. But what if using your existing database is possible? I built a job queueing system with a PostgreSQL database that cleared the bar without adding infrastructure. The next question will be, does this solution meet the criteria of a job queue? A job needs a few things to execute properly within a system. It needs to be persistent, surviving unforeseen crashes. Jobs must not be processed more than once by workers; one job should be processed once by one worker. Also, a job's state has to be tracked through every step. A job state must show when it's pending, completed or failed. That's the bar any solution must clear. With the Postgres approach, persistence comes free. Jobs live in a table so when a worker dies mid-job, the job still exists in a row in the db. Whereas with in-memory queues, a crash loses everything still in memory. A broker like RabbitMQ has to be configured for persistence and if configured wrongly, jobs get lost. A database however is fundamentally built for durability. Now, let's say three workers poll the queue at the same instant and run the same query. They'll see the same pending job at the top and nothing stops them all from grabbing it. If that job is a payment, the customer gets charged three times for one service. All the workers successfully process the job with no indication of an error or alerts. This is the requirement that seems to demand a real message broker, and it's exactly where people assume a database can't compete. It can. Postgres has a specific tool for exactly this. The SQL clause FOR UPDATE is used to lock rows. This can be called on a job when a worker picks it up to process. By default other workers will get blocked during this process, they'll wait for the lock to r

# Module Resolution Algorithm (Part 1): How Node.js Finds the Right Module In the previous article, we explored one of the most fascinating parts of Node.js—the hidden Module Wrapper Function. We learned that every CommonJS module is wrapped inside a function before execution, and we also discovered that require() is not a JavaScript feature. It is provided by the Node.js runtime. But a very important mystery still remains. When we write: const fs = require ( " fs " ); or const math = require ( " ./math " ); how does Node.js know where these modules are located? How does it decide whether "fs" is a built-in module or a file inside your project? Why does require("./math") work even if you don't write .js ? And what happens internally before your code starts executing? The answer lies inside one of Node.js's most important systems: The Module Resolution Algorithm Understanding this algorithm is essential because every Node.js application uses it hundreds or even thousands of times while starting. What is Module Resolution? The word resolution simply means: Finding the actual file represented by the string passed to require() . Suppose you write: require ( " ./math " ); To you, "./math" looks like a file. But for Node.js, it is initially nothing more than a string. "./math" Node cannot execute a string. It needs the real file. So its first job is to answer one question: "Which exact file should I load?" The complete process of converting the string inside require() into an actual file on disk is called Module Resolution . Why Does Node Need a Resolution Algorithm? Imagine a project like this: project/ ├── app.js ├── math.js ├── database.js ├── auth.js └── utils/ ├── logger.js └── helper.js Now look at these statements. require ( " ./math " ); require ( " ./database " ); require ( " ./utils/logger " ); require ( " fs " ); require ( " express " ); All of them look similar. But internally they are completely different. Some point to your own files. Some point to Node's bu

Redis gets reached for reflexively, "just add Redis," as if it were a single fix for slowness. It's genuinely one of the most useful tools in a backend engineer's kit, but using it well starts with understanding what it actually is: an in-memory data structure store, not just a cache. Once you see it as a fast, versatile store of real data structures, the range of problems it solves cleanly (caching, rate limiting, queues, sessions, leaderboards, locks) stops looking like a grab bag and starts looking like one idea applied many ways. This is the opening article of the Redis Masterclass, and it builds on the PostgreSQL series : Redis usually sits alongside a primary database like Postgres, not instead of it. In-memory is the whole point Redis keeps its data in RAM. That single fact explains most of its character. Reading from memory is orders of magnitude faster than reading from disk, so Redis operations typically complete in well under a millisecond, and a single instance handles a very high request rate. That speed is why it's the default choice for anything on the hot path, where a database round trip would be too slow. The tradeoff is that RAM is smaller and more expensive than disk, and volatile. Redis addresses durability with persistence options we'll cover later, but the mental model to start with is: Redis is fast because it's in memory, and you use it for data that benefits from being fast to access, not as the permanent home for everything. It's a data structure store, not a key-value blob The common misconception is that Redis is a simple key-value store, strings in and strings out. It's much more. Redis stores real data structures as values, each with its own commands: Strings for simple values, counters, and cached blobs. Hashes for objects with fields, like a user record. Lists for ordered sequences and simple queues. Sets for unique collections and membership checks. Sorted sets for ranked data like leaderboards and priority queues. Plus streams, bit

Teams treat "externalize the rules" as two different decisions depending on the stack. In Node, it's "which npm package handles conditionals." In Java, it's "do we adopt Drools." Both framings are wrong in the same way — they turn an architecture decision into a product decision before anyone's actually designed the seam. The seam is the same regardless of language: rules become data instead of control flow, the boundary between your service and the rule layer is typed on both sides, and a contract test catches the moment a rule change would silently break what your code expects back. Get that seam right and it barely matters whether you're calling it from Express or Spring Boot. Get it wrong and you've just moved your if statements into a config file and called it progress. The seam: rules as data, not control flow The actual pattern is small. Instead of branching logic living inline in a handler or a service method, you define a typed input, a typed output, and a rule set that maps one to the other — evaluated somewhere the calling code doesn't need to know the internals of. That's it. That's the whole architectural move. Everything else — which engine, which language, how it's hosted — is an implementation detail on top of that seam. Most of the friction teams run into with a low-code layer in Node.js or a Java service isn't the rule engine choice. It's skipping the typed boundary and finding out three months later that a rule change silently returns a shape the calling code wasn't built to handle. Node.js: keeping the boundary typed Here's the seam in a TypeScript service. The route handler never sees a conditional — it sees a typed input going in and a typed decision coming out: interface PricingInput { userTier : " free " | " pro " | " enterprise " ; cartTotal : number ; couponCode ?: string ; } interface PricingDecision { discountPercent : number ; reason : string ; } async function evaluatePricingRule ( input : PricingInput ): Promise < PricingDecision > { c

A background worker sits quietly for weeks, chewing through a job queue without incident, and then one Tuesday afternoon it disappears mid-batch, taking forty in-flight jobs down with it. No stack trace pointing at the offending line, no alert until a customer notices their export never finished. Nine times out of ten, the culprit is one of the most under-discussed failure modes in server-side JavaScript: unhandled promise rejections. They are easy to introduce, easy to miss in code review, and in modern Node.js they no longer just print a warning — they can end your process outright. This post walks through what unhandled promise rejections actually are at the engine level, why they are far more dangerous in long-running Node.js services than in typical web requests, how Node's default behavior around them has shifted over the years, and the concrete patterns you can use to stop them from quietly killing your jobs. What an Unhandled Promise Rejection Actually Is At the JavaScript engine level, a promise is a state machine with three possible states: pending, fulfilled, or rejected. When an async operation fails — a network call times out, a database query throws, a JSON parse blows up — the promise representing that operation transitions to the rejected state and carries a reason, usually an Error object. That's all a rejection is: a value flowing down the promise's error channel instead of its success channel. The engine only considers a rejection "handled" if, by the time it does its bookkeeping (which happens on a microtask checkpoint, not synchronously), there is a .catch() handler, a second argument to .then() , or a surrounding try/catch around an await somewhere in that promise's chain. If none of those exist anywhere in the chain, the rejection is classified as unhandled. This is the precise, narrow definition of unhandled promise rejections: a promise that reaches the rejected state with zero handlers attached anywhere along its chain of consumers. It's wo

Most developers think about crypto payments as a checkout problem. Generate an invoice. Show a payment page. Wait for a webhook. Mark the order as paid. That is the clean version. Real merchants do not live in the clean version. They live in support tickets. A customer says they paid, but the order is still pending. A payment arrives after the invoice expires. Someone sends the right amount on the wrong network. A webhook fails. A customer underpays. A support agent cannot tell whether the issue is customer error, blockchain delay, invoice expiry, fulfillment failure, or an internal system bug. This is where developers can build a real product. A Crypto Payment Support Desk is a support and operations layer for merchants that accept crypto payments. It helps support teams search payments, inspect payment timelines, classify issues, explain statuses to customers, escalate real problems, and reduce the amount of manual investigation required for every crypto payment ticket. In this article, I will use OxaPay as the example payment infrastructure because its documentation exposes the primitives needed to build this kind of product: invoice generation, payment status callbacks, HMAC-signed webhooks, payment information lookup, payment history, static addresses, SDKs, plugins, and automation integrations. This is not a generic “add crypto payments to your app” article. It is a blueprint for developers who want to build a support-facing product that merchants may actually pay for. The business idea The idea is simple: Build a support desk that sits between a merchant's payment system, order system, and support team. The merchant already accepts crypto payments. The problem is that their support team cannot quickly answer payment-related questions. Your product gives them one place to investigate cases like: “The customer says they paid, but the order is unpaid.” “The invoice expired, but a transaction later appeared.” “The payment is underpaid.” “The webhook was received,

A customer clicks the Pay button, the server sends the request to a payment provider, and the charge succeeds. The trouble begins when the response never reaches the browser because the connection drops. The frontend sees a timeout and retries the same request, while the backend treats it as a brand-new payment. One customer action has now created two valid charges. This kind of failure is easy to miss because every part of the system appears to behave correctly on its own. The browser retries because it never received a response, the API processes a valid POST request, and the payment provider accepts the instruction it was given. The defect sits between those systems, where no component has enough context to know that the second request is a repeat. The same pattern can create duplicate orders, emails, subscriptions, shipments, support tickets, or background jobs. The common advice is to retry failed requests, but that advice is incomplete. A retry is safe only when the server can distinguish a repeated business operation from a new one. For payment APIs, that usually means introducing an idempotency key, storing the original result, and protecting the write path against race conditions. The rest of this article walks through that flow using Node.js, Express, and PostgreSQL. The bug starts with a normal-looking endpoint Consider a small Express endpoint that creates a payment by calling an external provider. The code receives the request body, sends the amount and customer data to the provider, and returns the resulting payment object. Nothing about this route looks obviously unsafe during a basic code review, and the happy-path test is likely to pass without trouble. The risk appears only when the request succeeds remotely but the response is lost before the client receives it. `app.post("/payments", async (req, res, next) => { try { const payment = await paymentProvider.charge({ customerId: req.body.customerId, amount: req.body.amount, currency: req.body.currenc

Most SaaS products do not need a “crypto payment button.” They need a payment module. That distinction matters. A button can redirect a customer to a payment page. A module has to know which user is paying, which workspace should be upgraded, which plan should become active, when access should expire, how failed or expired payments should be handled, how support can inspect payment status, and how finance can export records later. That is where developers can build a serious product. A Crypto Payment Module for SaaS Apps is a reusable layer that lets SaaS builders add crypto payments without building the whole payment lifecycle from scratch. In this article, I will use OxaPay as the example crypto payment infrastructure because its documentation exposes the primitives needed for this kind of module: invoice generation, white-label payments, static addresses, webhooks, payment information, payment history, SDKs for PHP, Python and Laravel, and automation integrations. This is not a “get rich with crypto APIs” article. It is a practical blueprint for developers who want to build something SaaS founders, indie hackers, agencies, and product teams may actually pay for. The core idea A Crypto Payment Module gives SaaS apps a production-ready way to accept crypto payments and translate payment events into SaaS account states. Instead of selling this: I can integrate crypto payments into your app. You sell this: I can give your SaaS a reusable crypto billing module with invoices, payment status tracking, webhook verification, plan activation, grace periods, admin tools, and payment history sync. That is a much stronger offer. A SaaS founder does not only care that a payment happened. They care that the right account is upgraded, the right plan is applied, the right billing period is extended, the right user sees the right status, and the support team can understand what happened when something goes wrong. That is what your module should solve. Why this is a real developer

Validate what comes in, shape what goes out, and give every outcome its proper status code. So Phase 1 gave my app a memory — a real database that remembers users and expenses even after a restart. Small problem: the only way to actually talk to it was a Python script I ran by hand. The app could remember things, but it was mute. Nobody on the internet could add an expense, list their spending, or delete a typo. Phase 2 fixes that. This is where the app grows a mouth — real HTTP endpoints you hit through the browser. The buzzword is CRUD : Create, Read, Update, Delete. The four things basically every app does to data. I went in thinking "it's just four functions, how hard can it be" and came out having learned about request/response contracts, dependency injection, and roughly six different HTTP status codes — mostly by triggering them wrong first. Let me dump what I learned [and the parts that tripped me up, because there were, uh, several]. The Structure is as follows. Lets call it PHASE 2 — The Endpoints: Set up the request/response contracts (two Pydantic schemas: one for input, one for output) Build a session dependency so every request gets a safe, auto-closing DB connection POST — create an expense GET — list them all + fetch one [with a proper 404] PATCH — update just the fields that changed DELETE — remove one cleanly First, the two new ideas [and no, nothing to install this time] Phase 1 had two new libraries. Phase 2 has two new ideas — and the nice part is there's nothing to pip install , because Pydantic already ships inside FastAPI. [Which means requirements.txt didn't change this phase. Still worth knowing the freeze habit is only for phases where you actually install something.] Pydantic — the bouncer at the door. Your SQLAlchemy models describe how data is stored ; Pydantic describes the shape data must have to cross the border of your API . It checks types, rejects garbage, and turns raw JSON into a clean Python object before it gets anywhere near

I honestly thought learning REST APIs would be easy. At first, creating a simple GET or POST endpoint feels straightforward and you start thinking, "I've got this." Then reality hits. Every API needs middleware, validation, error handling, controllers, database integration, authentication, authorization, testing, pagination, CORS, environment variables, deployment and a dozen other things. Somewhere along the way, you realize you didn't just sign up to build an API—you signed up to build an entire backend ecosystem. 😂💻

If your Clio integration started returning 401 and you are trying to work out why, the first question is not about your code. It is which of Clio's two OAuth systems you are on, because they have different rules and most advice on the internet does not say which one it is describing. There are two, and they are not interchangeable Clio Manage is the older one. OAuth at app.clio.com/oauth , API at app.clio.com/api/v4 . Clio Platform is the newer one, covering Grow and the lead inbox among others. OAuth at auth.api.clio.com/oauth , API at api.clio.com . They differ on essentially every point that matters when a token dies. Manage Platform Access token lifetime 2,592,000s, 30 days 86,400s, 24 hours Refresh token expiry Documented as none No time expiry, but rotates Refresh token rotation Not documented, and the refresh sample returns no new refresh token Documented: rotates on every use, previous one revoked Revocation endpoint POST app.clio.com/oauth/deauthorize , Bearer auth POST auth.api.clio.com/oauth/revoke , Basic auth Treat the lifetime row as the documented default rather than a constant. Honour the expires_in you get back on each response instead of hardcoding 30 days, because there are field reports of accounts issuing much shorter access tokens, and a hardcoded assumption fails in a way that looks exactly like revocation. That rotation row is the one that decides your debugging. On Platform , every refresh gives you a new refresh token and kills the old one, so failing to persist the new value out of each response leaves you holding a dead token the next time you try. Clio's docs say it directly: store the new refresh token returned in each response. On Manage , the documented behaviour is a long-lived refresh token that does not expire and is not replaced. Their refresh response sample does not even include a refresh_token field. So on Manage, a token that suddenly stops working usually points somewhere else: revocation, or the wrong region. The region trap

There are two versions of this job and they have different answers. Most of the confusion, including ours, comes from assuming they are the same thing. Applying a whole template list to a matter Clio's interface has a button for this, and the natural assumption is that there is a matching endpoint on the task template resource. There is not. Nothing under /task_template_lists will assign anything to a matter, and no path in Clio's spec contains "apply". It is done from the matter instead. Both POST /matters.json and PATCH /matters/{id}.json accept a nested array: task_template_list_instances[] : task_template_list : { id } required on POST assignee_id : the user the list is assigned to notify_assignees : whether assignees get notified due_at : ISO-8601 date (format : date, not date-time) Those are the only two operations in the API that accept it. Note the asymmetry: on POST /matters.json the task_template_list object is required, and on PATCH /matters/{id}.json the item schema marks nothing as required at all. POST /task_template_lists/{id}/copy.json exists and sounds like the thing you want. It is not. It duplicates a list into another list , takes name , description and practice_area (all optional), and has no matter parameter. The two problems that will actually cost you time Instances are write-only. task_template_list_instances appears in those two request bodies and nowhere in the matter response schema. So there is no documented way to ask "does this matter already have the list on it?" You verify by fetching /tasks.json filtered to the matter and matching on names, which is uglier than it sounds and is most of the reconciliation work. Which makes idempotency your problem. If your automation fires the PATCH twice, nothing in the API stops you assigning the checklist twice. For anything triggered off matter creation or a stage change, decide up front how you detect an already-applied list, because the readback above is the only tool you have. Between them, th

A saga test that stops after “payment succeeded, inventory failed, refund called” assumes compensation is reliable. It is another distributed operation, so test it under the same faults. Use this sequence: 1. payment capture succeeds 2. inventory reservation times out 3. refund succeeds at provider 4. refund response is lost 5. compensation message is delivered again 6. late inventory-failed event arrives again The invariant is not “refund endpoint called once.” It is: captured amount - confirmed refunded amount = final charged amount and final charged amount is never negative Persist an inbox record for consumed message IDs and an outbox record for each intended side effect. Give the provider request a stable idempotency key derived from saga and compensation step: { "sagaId" : "order-42" , "step" : "refund-payment-v1" , "idempotencyKey" : "order-42:refund-payment:v1" , "amount" : 4900 } A deterministic simulator should permute duplicate delivery, delayed acknowledgement, worker crash, and out-of-order events. After every run, assert one terminal order state, at most one economic refund, and a complete evidence trail. “Already refunded” must reconcile to success only after amount and payment identity match. AWS describes coordination choices and rollback behavior in its Saga pattern guidance . The implementation detail that deserves its own test is durable compensation progress: a process restart cannot erase whether the external side effect occurred. Alert on sagas stuck in compensating , but do not let an operator click “retry” with a new key. The runbook should first query provider state, compare amount and currency, and resume the same operation identity. Exactly-once delivery is not required to preserve money. Stable operation identity plus reconciliation is.

Prisma and Drizzle connect as the postgres role and bypass Supabase RLS entirely, so your policies never protect ORM queries. Here's the fix. TL;DR: No. Prisma and Drizzle open their own direct Postgres connection and log in as the postgres role, which owns your tables and carries BYPASSRLS — so Row Level Security is skipped on every ORM query. Point your app's connection at a dedicated, non-owner NOBYPASSRLS role (and keep the auth check in your code), not at postgres . If you built your Supabase project assuming RLS is a safety net on the data itself, adding an ORM quietly punches a hole straight through it. Your policies are still there. They just never run for the ORM's connection. Here's the mechanism, the myth to unlearn, and three fixes in order of how much you should reach for them. Does Prisma respect Supabase RLS? No. RLS is not a global property of the database — Postgres enforces it per role, per statement . A policy only bites for a role that is (a) not the table's owner, (b) has no BYPASSRLS attribute, and (c) is not a superuser. The Supabase JS client satisfies all three because it reaches Postgres through PostgREST, which runs your query as the unprivileged anon or authenticated role. Prisma and Drizzle satisfy none of them: they read DATABASE_URL and open a raw SQL connection as postgres , which owns virtually every table you migrated and holds BYPASSRLS . Either fact alone is enough for Postgres to skip your policies. So the same query that returns one tenant's rows through supabase-js returns every tenant's rows through Prisma. That is not a bug in your policy — it's the connection role. Two doors into the same database There are two completely different paths to your data, and they authenticate as different roles. The supabase-js path (RLS enforced). supabase-js talks HTTP to PostgREST, not to Postgres directly. PostgREST connects as authenticator , validates the request JWT, and does a SET ROLE into anon or authenticated for the statement. Those

As developers, we use authorization libraries almost every day. Whether it's a web application, an API, or an internal tool, we often rely on packages that decide who can do what. But I realized I had never actually built one. So instead of using an existing library, I decided to build my own Role-Based Access Control (RBAC) library in Go using only the standard library. This project eventually became GateKeeper v1.0.0. Why I Built One As a beginner in backend development, I wanted to get exposure on how to make public APIs and how to make them work under the hood. It also made me fight my old syntax habits. Go has strict error handling, which I also learned. I built it because I wanted to understand the engineering decisions behind public libraries. Instead of watching another tutorial, I built it myself. Project Goals Before writing any code, I brainstorm the architecture in my mind. No external library used, only the standard Go library. Keeping the public APIs simple and easy to read for developers to use. Write tests for each and every function, no matter how small. These constraints forced me to think more carefully about the design instead of depending on external packages. The Core Model Engine ├── Users ├── Roles └── Permissions Relationships are straightforward: Users | V Roles | V Permissions A user can have multiple roles, and roles can have multiple permissions. Permissions describe access to a resource and an action. Designing The API One thing I learned the hard way is that API design matters more than the implementation itself. I wanted to keep the library easy to read even without documentation. The public API ended up looking something like this: CreateUser() CreateRole() CreatePermission() AssignRole() AssignPermission() Can() DeleteUser() DeleteRole() DeletePermission() RenameUser() RenameRole() I had to redesign the API many times before eventually coming up with the final one. The time spent fighting the design was worth it. It taught me API de

I don lose count of how many times I don see this kind yarns online: "Backend development na just CRUD. Everything else na decoration." And honestly? I sabi why people dey talk am. E no kuku wrong. E no just complete, na like when person say "cooking na just to heat food." Technically, e dey true. But e dey miss almost everything wey make am skill. Make I carry you waka through wetin I mean, using something wey all of us don do before: to order food for app. First, Wetin CRUD Really Be CRUD mean Create, Read, Update, Delete, na the four things you fit do to any piece of data. Operation Wetin e dey do Normally e go be Create Add new data POST /orders Read Fetch existing data GET /orders/482 Update Change existing data PATCH /orders/482 Delete Remove data DELETE /orders/482 You place order, that na Create. You check where the order dey, that na Read. You change delivery address before dem ship am, na Update be that. You cancel am, that one na Delete. Change "order" to "post", "message", or "appointment" and you don describe almost every app wey dey for your phone. If you dey new for backend work, to build small CRUD API na genuinely good way to learn. You go jam routing, HTTP methods, request validation, database, and ORM almost by accident. Na exactly why every bootcamp dey start you off with building Todo app. But see this thing, to build only the CRUD part of that food order na maybe 10% of the real engineering work. Make we follow that one order through everything else wey suppose happen. "Who Even Dey Ask?" — Authentication Somebody send this: DELETE /orders/482 Fine. But who you be sef? If anybody at all fit hit that endpoint, you no get API, you get public database with extra steps. Before any Create, Read, Update, or Delete happen, backend need answer one question first: who dey make this request? That one na authentication, JWT, session cookie, OAuth, whichever flavor you dey use. "Dem Get Permission Do That?" — Authorization Say two different people send tha

The trust proxy setting is an important concept in backend development, especially when implementing rate-limiting in our APIs. But deciding its accurate value depends heavily on our deployment topology. When we deploy our application in production, the client may not talk directly to our backend. There may be 1 or more proxies in between who forward the request to the next proxy or the backend server. Those proxies can be Load balancers, API gateways, reverse proxy like nginx or any custom service. So effectively, our request has to do some 'hops' over these proxies to reach backend. When we implement rate limiting in app to prevent the DOS attack, we generally intend this rate limit on the basis of client IP address. And this works fine when client request reaches our backend directly. But when we have multi-hop architecture, the simple setup won't work as expected. Because the most recent IP will be of the proxy and not the client. So all the traffic coming from different users will be considered from the single client(our own proxy) and thus there will be false positives as the rate limiting will trigger much often. In this scenario, we must tell our backend to ignore these extra hops(i.e. to trust our proxies). This is done by specifying trust proxy. If there is 1 proxy between client-server we set trust proxy to 1; if there are 2, or more, we set it accordingly. This will ensure our express app skips(trusts) these IPs, and accurately figures out actual client IP. The originating IP address of client is identified from 'X-Forwarded-For' header by the express app. But setting trust proxy is not that straightforward. The numerical value for trust proxy will not work in every case. If there are different paths from which our request reaches backend, there is a chance that the number of proxies may be different in each path. For example - internal vs external traffic: External(public) traffic: (Client -> Web Application Firewall -> Load balancer -> Reverse Proxy ->

Every time you open a website, sign into an application, or send a request to an API, a server responds with a small but powerful message: an HTTP status code. Most developers encounter these codes every day. But behind every number is a story about what happened between the client and the server. HTTP status codes are part of a standardized response system defined by RFC 9110. They help applications understand whether a request succeeded, needs attention, or failed. The HTTP Status Code Families 🟢 2xx — Success The request was received, understood, and completed successfully. Examples: 200 OK — The request succeeded. 201 Created — A new resource was successfully created. These responses tell the client: everything worked as expected. 🔵 3xx — Redirection The requested resource requires an additional step. These responses help clients find another location or use a different version of a resource. Examples include redirects and cache-related responses. 🟠 4xx — Client Errors Something is wrong with the request sent by the client. Common examples: 400 Bad Request — The request format is invalid. 401 Unauthorized — Authentication is required. 403 Forbidden — The client does not have permission. 404 Not Found — The requested resource does not exist. In simple terms: the problem is usually on the client side. 🔴 5xx — Server Errors The request was valid, but the server failed while processing it. Example: 500 Internal Server Error — An unexpected error occurred on the server. These responses indicate problems within the server or its internal systems. Why HTTP Status Codes Matter HTTP status codes are not just numbers. They are: The language of web communication Essential signals for API behavior Valuable tools for debugging and monitoring A foundation of backend engineering and distributed systems Understanding status codes helps developers build better applications, diagnose problems faster, and design more reliable systems. A single three-digit number can reveal what ha

느린 LLM 호출 중 DB connection을 잡지 않는 이유 AI 기능의 latency는 모델 응답 시간으로만 끝나지 않습니다. 요청이 LLM이나 embedding API를 기다리는 동안 데이터베이스 session까지 긴 범위로 유지하면, 느린 외부 호출이 DB connection pool의 압력으로 전파될 수 있습니다. 이 글은 AI memory OSS인 Honcho의 변경 이력과 pinned source를 읽으면서, 외부 호출과 DB transaction/session 경계를 어떻게 분리했는지 추적한 기록입니다. Scenario Honcho의 dialectic 경로(저장된 memory를 근거로 사용자 질문에 답하는 질의 경로)는 답하기 전에 다음 작업을 수행합니다. peer·session·workspace 확인 -> 관련 memory 검색 -> embedding·LLM 호출 -> 필요하면 tool로 추가 조회·기록 -> 답변 생성 여기에는 짧은 DB 조회와 상대적으로 느리고 변동성이 큰 외부 호출이 섞여 있습니다. 두 작업을 하나의 session scope로 묶으면, DB가 필요하지 않은 대기 시간까지 session lifetime에 포함됩니다. 변경 전에는 무엇이 묶여 있었나 PR #477 직전의 agentic_chat 은 하나의 tracked_db context 안에서 peer와 설정을 읽고, 그 session을 DialecticAgent 에 전달한 뒤, agent.answer() 가 끝날 때까지 같은 context를 유지했습니다. streaming 경로도 같은 형태였습니다. 구조를 단순화하면 다음과 같습니다. DB session open -> preflight read -> DialecticAgent receives session -> embedding / memory tools / LLM answer DB session close commit 0533c6d 의 제목도 이 문제를 dialectic held connection 으로 기록합니다. 다만 이번 분석에서는 실제 pool checkout 시간이나 장애를 재현하지 않았습니다. 여기서 확인한 것은 코드의 session scope와 변경 의도입니다. SQLAlchemy의 session 객체를 만들었다고 곧바로 connection을 점유하는 것은 아닙니다. 하지만 이 경로처럼 SQL을 실행해 transaction이 시작되면 session은 pool에서 빌린 connection을 commit·rollback까지 유지합니다. Honcho의 tracked_db 는 종료할 때 rollback() 과 close() 를 호출하므로, SQL 실행 뒤 이 context를 LLM 대기까지 유지하던 범위를 줄이는 것은 이 경로의 connection 점유 구간도 줄이는 일입니다. 어떻게 경계를 줄였나 변경 후에는 tracked_db("dialectic.preflight") 가 본 작업 전 검증과 설정 조회(preflight), 즉 peer 존재 여부, session/workspace 설정, peer card를 읽는 구간만 감쌉니다. context가 끝난 다음에 DialecticAgent 를 만들고 LLM 답변을 생성합니다. Agent 생성자에서도 DB session 인자가 제거됐습니다. short DB preflight -> 필요한 값 읽기 DB session close agent execution -> embedding / LLM / tools tool needs DB -> tool-owned short DB session -> close 핵심은 DB 사용을 없앤 것이 아닙니다. 요청 전체가 session을 소유하는 대신, DB가 필요한 작업이 자기 범위의 session을 소유하도록 바꾼 것 입니다. pinned current code에서도 유지되는가 분석 기준 commit 85239a6 에서도 이 경계는 유지되고 더 구체화돼 있습니다. src/dialectic/chat.py 의 일반·streaming 경로 모두 preflight context를 닫은 뒤 agent를 실

The Quest Begins (The “Why”) I still remember the night our API started to sputter under a sudden traffic spike. Users were seeing 502 errors, the monitoring dashboard looked like a neon rainstorm, and I felt like I was stuck in a lobby waiting for the elevator that never arrives. We had a simple round‑robin load balancer sitting in front of three identical services. It worked fine when traffic was smooth, but as soon as a burst hit, one node would get overloaded while the others twiddled their thumbs. Honestly, I thought we just needed more servers. Throwing hardware at the problem felt like using a sledgehammer to crack a nut—expensive and messy. After a few frantic Slack threads and a lot of coffee, I realized the real issue wasn’t capacity; it was how we distributed the work. The balancer was oblivious to the actual load on each backend, treating every request like it was the same weight. That moment became my quest: design a load balancer that reacts to real‑time load, stays simple enough to operate, and doesn’t cause a reshuffling nightmare when we scale the cluster. The Revelation (The Insight) The breakthrough came when I read about least‑connections load balancing combined with a slow‑start period for new hosts. The core insight is deceptively simple: Send each new request to the backend that currently has the fewest active connections. Why does that work? Immediate fairness – If one node is handling long‑running requests, it will naturally have a higher connection count and receive fewer new ones until it catches up. Burst absorption – During a traffic spike, requests spill over to the less‑busy nodes instead of piling onto a single overloaded instance. Predictable scaling – When we add a new server, it starts with zero connections, so it gets a fair share of traffic right away—but we temper that with a slow‑start window to avoid overwhelming a cold host. Compare that to round‑robin, which blindly cycles through the list regardless of each node’s state. In