DEV Community: ByteBridge Talent LLC

Search Results That Jump Back to an Old Query in React: Finding and Fixing the Race

ByteBridge Talent LLC — Thu, 29 Oct 2026 02:10:54 +0000

The problem

A developer built a search bar in React. Each time the user types a letter, the component sends a request to the server and shows the results. Most of the time it works. But sometimes the list shows results for an older, shorter search. The box says "react", and the list shows results for "r". Typing slowly hides the bug. Typing fast makes it show up again.

This is a common bug, and it is easy to miss in local testing, because a local server answers almost every request at the same speed.

The root cause

Every keystroke starts a new request. The network does not promise that answers come back in the same order the requests went out. A short query like "r" can match many rows and take longer on the server. A longer query like "react" can come back fast.

So the timeline can look like this:

0 ms     start request for "r"      (slow, 300 ms)
40 ms    start request for "re"     (fast, 20 ms)
60 ms    "re" answers  -> list shows "re" results   (correct)
300 ms   "r" answers   -> list shows "r" results    (wrong, but it was the last setState)

The buggy code calls setState for every answer, so the last answer to arrive wins, not the last question asked:

// Buggy: every response updates state, in arrival order
useEffect(() => {
  if (!query) return;
  fetch(`/api/search?q=${encodeURIComponent(query)}`)
    .then((res) => res.json())
    .then((data) => setResults({ query, items: data.items }));
}, [query]);

The React docs describe this exact case in "You Might Not Need an Effect": the responses for "hell" and "hello" can arrive in either order, and whichever calls setResults() last is what the user sees. They call it a race condition.

The fix

The fix has three parts. Each part solves a different piece, and all three live in the effect's cleanup function, which React runs before the effect runs again and when the component unmounts.

An ignore flag. Each effect run gets its own flag. Cleanup sets it to true, so a late answer from an old run can no longer change state. This is the part that makes the result correct.
An AbortController. Cleanup calls controller.abort(). Per MDN, this can abort a fetch request and the reading of its response body. The aborted fetch rejects with an AbortError, which we treat as normal, not as a failure. This part saves network and server work.
A short debounce. A timer waits until the user pauses before it sends a request. Cleanup clears the timer, so fast typing sends one request instead of five. This part cuts load. It does not fix ordering by itself.

Here is the full hook:

import { useEffect, useState } from 'react';

export function useSearch(query, { fetchImpl = fetch, delayMs = 250 } = {}) {
  const [state, setState] = useState({ status: 'idle', query: '', items: [], error: null });

  useEffect(() => {
    const q = query.trim();
    if (!q) {
      setState({ status: 'idle', query: '', items: [], error: null });
      return;
    }

    const controller = new AbortController();
    let ignore = false;

    const timer = setTimeout(async () => {
      setState((s) => ({ ...s, status: 'loading', error: null }));
      try {
        const res = await fetchImpl(`/api/search?q=${encodeURIComponent(q)}`, {
          signal: controller.signal,
        });
        if (!res.ok) throw new Error(`HTTP ${res.status}`);
        const data = await res.json();
        if (!ignore) setState({ status: 'done', query: q, items: data.items, error: null });
      } catch (err) {
        if (ignore || err.name === 'AbortError') return; // expected, not a real failure
        setState((s) => ({ ...s, status: 'error', error: err }));
      }
    }, delayMs);

    return () => {
      ignore = true;        // late answers from this run can no longer touch state
      clearTimeout(timer);  // a request that has not started yet never starts
      controller.abort();   // a request in flight is cancelled
    };
  }, [query, fetchImpl, delayMs]);

  return state;
}

Use it like this:

function SearchBox() {
  const [query, setQuery] = useState('');
  const { status, query: shownFor, items, error } = useSearch(query);

  return (
    <>
      <input value={query} onChange={(e) => setQuery(e.target.value)} />
      {status === 'loading' && <p>Loading…</p>}
      {status === 'error' && <p>Something went wrong: {error.message}</p>}
      <p>Showing results for: {shownFor}</p>
      <ul>{items.map((item) => <li key={item}>{item}</li>)}</ul>
    </>
  );
}

Two small details matter:

Keep the query that produced the results in state next to the items. Then the UI can show which search the list belongs to, and a test can check it.
Do not pass a new fetchImpl function on every render, or the effect will re-run each time. Either leave the default, or create the function once outside the component.

Why keep the `ignore` flag if we already abort?

Abort is best effort. If the response is already done by the time cleanup runs, or if the fetch function you call does not pass the signal along (some wrappers drop it), the old promise can still resolve. The ignore check is a plain, in-memory test, so it works in every one of those cases. The React docs show the ignore flag as the basic fix and say cleanup should "either abort the fetch or ignore its result." We do both.

How we tested it

We ran this on Node 20 with React 19, @testing-library/react, and jsdom. A fake fetch makes one-letter queries slow (300 ms) and longer queries fast (20 ms), and it honors AbortSignal like the real one. Four tests:

test('buggy hook shows results for an old query', async () => {
  const log = []; const f = makeFakeFetch(log);
  const { rerender } = render(h(BuggyBox, { query: 'r', fetchImpl: f }));
  rerender(h(BuggyBox, { query: 're', fetchImpl: f }));
  await act(() => sleep(400));
  assert.equal(screen.getByTestId('out').textContent, 're -> r'); // box says "re", list is for "r"
});

test('fixed hook keeps the newest query and aborts the old one', async () => {
  const log = []; const f = makeFakeFetch(log);
  const { rerender } = render(h(FixedBox, { query: 'r', fetchImpl: f, delayMs: 0 }));
  await act(() => sleep(5));
  rerender(h(FixedBox, { query: 're', fetchImpl: f, delayMs: 0 }));
  await act(() => sleep(400));
  assert.equal(screen.getByTestId('out').textContent, 're -> re');
  assert.ok(log.includes('abort r'));
});

test('debounce: fast typing sends one request', async () => {
  // types r, re, rea, reac, react 30 ms apart with a 100 ms debounce
  assert.deepEqual(log, ['start react', 'finish react']);
});

test('ignore flag still protects when the old request cannot be aborted', async () => {
  // fetch wrapper drops the signal on purpose
  assert.ok(log.includes('finish r'));                               // old answer did arrive
  assert.equal(screen.getByTestId('out').textContent, 're -> re');   // but it was ignored
});

Result: 4 of 4 tests pass. The request logs from the run:

fixed log:    start r, abort r, start re, finish re
debounce log: start react, finish react

The first test proves the bug is real. The other three prove each part of the fix does its own job.

Trade-offs

Debounce adds delay. Every search waits for the pause before it starts. A longer delay sends fewer requests but feels slower. A shorter delay feels faster but sends more. Pick a value and measure it with real users.
Abort does not undo work. The server may have already run the query. Abort saves bandwidth and frees the browser connection. It does not roll back anything on the server, so never rely on abort for requests that change data.
Two requests in development are normal. With Strict Mode, React runs the effect, cleans it up, and runs it again in development. The docs say you will see two fetches in the Network tab, and the cleanup makes the first one harmless. In a production build there is one.
A data library may fit better. The React docs point out that caching, server-side fetching, and request waterfalls are still open problems with hand-written effects, and that frameworks and data libraries handle them. If your app already uses one, use its query hooks instead of this hook. If it does not, this hook is a small, clear step, and it is easy to replace later.
The ignore flag alone is enough for correctness. If you cannot abort (for example, an SDK that does not accept a signal), the flag still keeps the screen right. You lose only the network savings.

Make sure the stale results are gone

Run the tests. The buggy test should pass (it proves the bug), and the three fixed tests should pass.
Slow the network in the browser. Open DevTools, go to the Network tab, and pick a slow throttling preset. Type a word quickly. You should see older requests marked as cancelled, and only the last one should complete.
Show the source query. Render "Showing results for: …" next to the list, as in the example. Type fast, then compare it with the input. They should always match once loading ends.
Check the console. There should be no errors for aborted requests. If you see AbortError in your error UI, the catch block is not filtering it.

Official sources

React docs, You Might Not Need an Effect (section "Fetching data", race conditions and the ignore flag): https://react.dev/learn/you-might-not-need-an-effect
React docs, Synchronizing with Effects (section "Fetching data", abort or ignore in cleanup, two fetches in development): https://react.dev/learn/synchronizing-with-effects
React docs, useEffect reference (section "Fetching data with Effects"): https://react.dev/reference/react/useEffect
MDN, AbortController: abort() method: https://developer.mozilla.org/en-US/docs/Web/API/AbortController/abort
MDN, AbortSignal: https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal

Written by the team at ByteBridge Talent LLC, a tech talent and IT staffing firm in Grand Island, Nebraska. Learn more at bytebridgetalent.com.

Clear JSON Errors in FastAPI: One Shape for Every Failure

ByteBridge Talent LLC — Sun, 25 Oct 2026 21:52:50 +0000

Updated: October 26, 2026

A phone app calls an API and gets an error. The app wants to show a short, kind message. But the error comes back in a shape the app did not expect, so it shows "undefined" instead.

This happens a lot. FastAPI is easy to work with. Its default errors just do not all look alike.

Below, every error gets one JSON shape, and a few tests check it.

Tested with: Python 3.13.5, FastAPI 0.161.0, Pydantic 2.14.1 and pytest 9.1.1 on Linux. Outputs are pasted from a single run.

Two words first

Exception: a Python error that stops the normal flow of code.
Exception handler: a function that catches one kind of exception and turns it into a response.

FastAPI lets you register a handler for each kind of exception. That is the whole trick.

The problem: two shapes by default

Here is a tiny app with no custom handlers. It asks for a missing book, then sends a word where a number belongs.

from fastapi import FastAPI, HTTPException
from fastapi.testclient import TestClient

plain = FastAPI()


@plain.get("/books/{book_id}")
def get_book(book_id: int):
    raise HTTPException(status_code=404, detail="Book not found")


client = TestClient(plain)
print(client.get("/books/7").json())
print(client.get("/books/abc").json())

{'detail': 'Book not found'}
{'detail': [{'type': 'int_parsing', 'loc': ['path', 'book_id'], 'msg': 'Input should be a valid integer, unable to parse string as an integer', 'input': 'abc'}]}

In the first error, detail is a string. In the second, detail is a list of objects. Client code now needs two paths just to read an error.

One shape for all errors

Pick a shape and keep it. This post uses a small one:

{"error": {"status": 404, "code": "book_not_found", "message": "No book with id 7."}}

status repeats the HTTP status, which helps in logs.
code is a short, stable word. Client code can check it safely.
message is for humans. You can reword it later without breaking clients.
details appears only when there is more to say, such as which field failed.

There is also a standard shape, called "Problem Details" (RFC 9457). It uses fields like type, title and detail. It is a good choice for public APIs. The idea in this post is the same either way: one shape, everywhere.

The app with four handlers

import logging

from fastapi import FastAPI, Request
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse
from pydantic import BaseModel, Field
from starlette.exceptions import HTTPException as StarletteHTTPException

log = logging.getLogger("api")
app = FastAPI()


class AppError(Exception):
    def __init__(self, status: int, code: str, message: str):
        self.status = status
        self.code = code
        self.message = message


def error_body(status, code, message, details=None):
    body = {"status": status, "code": code, "message": message}
    if details:
        body["details"] = details
    return {"error": body}


@app.exception_handler(AppError)
async def handle_app_error(request: Request, exc: AppError):
    body = error_body(exc.status, exc.code, exc.message)
    return JSONResponse(status_code=exc.status, content=body)


@app.exception_handler(RequestValidationError)
async def handle_bad_input(request: Request, exc: RequestValidationError):
    details = []
    for err in exc.errors():
        field = ".".join(str(part) for part in err["loc"][1:])
        details.append({"field": field, "problem": err["msg"]})
    body = error_body(422, "invalid_input", "Some fields are not valid.", details)
    return JSONResponse(status_code=422, content=body)


@app.exception_handler(StarletteHTTPException)
async def handle_http_error(request: Request, exc: StarletteHTTPException):
    codes = {404: "not_found", 405: "method_not_allowed"}
    code = codes.get(exc.status_code, "http_error")
    body = error_body(exc.status_code, code, str(exc.detail))
    return JSONResponse(status_code=exc.status_code, content=body,
                        headers=exc.headers)


@app.exception_handler(Exception)
async def handle_crash(request: Request, exc: Exception):
    log.exception("Unhandled error on %s", request.url.path)
    body = error_body(500, "internal_error", "Something went wrong on the server.")
    return JSONResponse(status_code=500, content=body)


BOOKS = {1: {"id": 1, "title": "Clean Errors", "pages": 120}}


class NewBook(BaseModel):
    title: str = Field(min_length=1)
    pages: int = Field(gt=0)


@app.get("/books/{book_id}")
def get_book(book_id: int):
    if book_id not in BOOKS:
        raise AppError(404, "book_not_found", f"No book with id {book_id}.")
    return BOOKS[book_id]


@app.post("/books", status_code=201)
def add_book(book: NewBook):
    new_id = max(BOOKS) + 1
    BOOKS[new_id] = {"id": new_id, **book.model_dump()}
    return BOOKS[new_id]


@app.get("/books/{book_id}/rating")
def get_rating(book_id: int):
    scores = []  # bug: no reviews yet, so this list is empty
    return {"rating": sum(scores) / len(scores)}

Each handler has one job:

AppError is for errors you raise on purpose, like a missing book. You choose the status and the code.
RequestValidationError fires when input fails the Pydantic model. The handler lists each bad field in plain words.
StarletteHTTPException covers errors the framework raises itself, like an unknown URL (404) or a wrong method (405). Register the Starlette class, not only FastAPI's own HTTPException. Then those framework errors get caught too.
Exception is the safety net for bugs. It logs the full traceback on the server. The client only gets a calm, general message.

Why hide the details of a crash? A traceback can show file paths, library versions and pieces of data. That belongs in your logs, not in a public reply.

See every error in one run

TestClient sends fake requests to the app without starting a server. The option raise_server_exceptions=False makes it return the 500 response instead of raising the bug.

import json
import logging

from fastapi.testclient import TestClient

from app import app

logging.disable(logging.CRITICAL)  # keep the demo output short
client = TestClient(app, raise_server_exceptions=False)

for method, path, data in [
    ("GET", "/books/7", None),
    ("POST", "/books", {"title": "", "pages": -3}),
    ("GET", "/nowhere", None),
    ("GET", "/books/1/rating", None),
]:
    r = client.request(method, path, json=data)
    print(method, path, "->", r.status_code)
    print(json.dumps(r.json(), indent=2))

GET /books/7 -> 404
{
  "error": {
    "status": 404,
    "code": "book_not_found",
    "message": "No book with id 7."
  }
}
POST /books -> 422
{
  "error": {
    "status": 422,
    "code": "invalid_input",
    "message": "Some fields are not valid.",
    "details": [
      {
        "field": "title",
        "problem": "String should have at least 1 character"
      },
      {
        "field": "pages",
        "problem": "Input should be greater than 0"
      }
    ]
  }
}
GET /nowhere -> 404
{
  "error": {
    "status": 404,
    "code": "not_found",
    "message": "Not Found"
  }
}
GET /books/1/rating -> 500
{
  "error": {
    "status": 500,
    "code": "internal_error",
    "message": "Something went wrong on the server."
  }
}

Four different failures. One shape. The client code needs just one path now.

Lock it in with tests

Shapes drift over time. Someone adds a new route and raises a plain error. Tests catch that early.

import pytest
from fastapi.testclient import TestClient

from app import app

client = TestClient(app, raise_server_exceptions=False)


def check_shape(response, status, code):
    assert response.status_code == status
    assert response.headers["content-type"] == "application/json"
    error = response.json()["error"]
    assert error["status"] == status
    assert error["code"] == code
    assert error["message"]
    return error


def test_missing_book():
    check_shape(client.get("/books/7"), 404, "book_not_found")


def test_bad_input_lists_each_field():
    r = client.post("/books", json={"title": "", "pages": -3})
    error = check_shape(r, 422, "invalid_input")
    assert [d["field"] for d in error["details"]] == ["title", "pages"]


def test_wrong_type_in_path():
    error = check_shape(client.get("/books/abc"), 422, "invalid_input")
    assert error["details"][0]["field"] == "book_id"


@pytest.mark.parametrize("method, path, status, code", [
    ("GET", "/nowhere", 404, "not_found"),
    ("DELETE", "/books/1", 405, "method_not_allowed"),
])
def test_framework_errors(method, path, status, code):
    check_shape(client.request(method, path), status, code)


def test_crash_hides_details():
    error = check_shape(client.get("/books/1/rating"), 500, "internal_error")
    assert "ZeroDivision" not in error["message"]


def test_good_request_still_works():
    r = client.post("/books", json={"title": "Fast Paths", "pages": 90})
    assert r.status_code == 201
    assert r.json()["title"] == "Fast Paths"

7 passed in 0.24s

check_shape is the heart of it. Every test runs through it, so every error must pass the same checks. Note the last test. It makes sure the good path still works after all these changes.

Small rules that keep errors useful

Keep codes stable. Treat book_not_found like part of the API. Changing it can break a client.
Keep messages short. One sentence. No stack traces, no SQL.
Use the right status. 404 for missing, 422 for bad input, 500 for bugs.
Log the 500s. The calm message is for users. The traceback is for you.
Add a test for each new error code. It takes one line with check_shape.

Key points

FastAPI's default errors come in more than one shape.
Pick one JSON shape: status, code, message and optional details.
Register handlers for your own error class, validation errors, Starlette HTTP errors and plain Exception.
Hide crash details from clients. Keep them in logs.
Test the shape for every kind of error.

Sources: FastAPI docs: handling errors; FastAPI docs: testing; Starlette docs: exceptions; Starlette docs: test client; RFC 9457: Problem Details for HTTP APIs; Python docs: logging, Logger.exception

This note comes from ByteBridge Talent LLC, an IT staffing company in Grand Island, Nebraska.

Version note: this code ran on FastAPI 0.161.0 and Starlette 1.9.0. Handler names and test client options can shift between major versions. Check the docs for the version in your own project before you copy it.

GitHub Actions Reusable Workflows: Write Your CI Once, Use It in Every Repo

ByteBridge Talent LLC — Sun, 18 Oct 2026 09:20:56 +0000

You have five repositories. Each one has its own CI file. They all do almost the same thing: check out the code, set up Python, install packages, run the linter, run the tests.

Then one day you need to change something, like the Python version. Now you edit five files, open five pull requests, and hope you did not miss one.

GitHub Actions has a fix for this called reusable workflows. You write the CI steps once, in one place. Every repo calls that one file. Change it once, and every repo gets the change.

This post walks through it step by step, with YAML you can copy.

Two words first

A workflow is a YAML file in .github/workflows/ that GitHub runs when something happens, like a push.
A reusable workflow is a workflow that other workflows can call, like a function.

The file that does the calling is the caller. The file being called is the called workflow.

Step 1: Write the shared workflow

Make a repo just for shared CI, for example my-org/ci-workflows. Add this file at .github/workflows/python-ci.yml:

name: Python CI (reusable)

on:
  workflow_call:
    inputs:
      python-version:
        description: "Python version to test with"
        type: string
        default: "3.13"
      run-lint:
        description: "Run the linter too?"
        type: boolean
        default: true
    secrets:
      PYPI_TOKEN:
        required: false
    outputs:
      tested-version:
        description: "The Python version that was tested"
        value: ${{ jobs.test.outputs.version }}

jobs:
  test:
    runs-on: ubuntu-latest
    outputs:
      version: ${{ steps.report.outputs.version }}
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-python@v6
        with:
          python-version: ${{ inputs.python-version }}
      - run: pip install -r requirements.txt
      - if: ${{ inputs.run-lint }}
        run: ruff check .
      - run: pytest -q
      - id: report
        run: echo "version=${{ inputs.python-version }}" >> "$GITHUB_OUTPUT"

The key line is on: workflow_call. That is what makes the file callable. Under it you list three things:

inputs: settings the caller can pass in. Each one has a type (string, number or boolean) and can have a default.
secrets: passwords or tokens the workflow may need. Here the token is optional.
outputs: values the workflow hands back to the caller when it is done.

One note: this example installs from requirements.txt, so that file must include ruff and pytest.

Step 2: Call it from each repo

In every app repo, the CI file becomes very short:

name: CI

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  tests:
    uses: my-org/ci-workflows/.github/workflows/python-ci.yml@v1
    with:
      python-version: "3.12"
    secrets: inherit

  tell-me:
    needs: tests
    runs-on: ubuntu-latest
    steps:
      - run: echo "Tested on Python ${{ needs.tests.outputs.tested-version }}"

Read the tests job line by line:

uses: points to the shared file: owner, repo, path, then @ and a version.
with: fills in the inputs. We did not set run-lint, so it uses its default, true.
secrets: inherit passes this repo's secrets along. This works when both repos are in the same organization or enterprise. You can also pass secrets one by one instead.

The second job, tell-me, waits for tests and reads its output with needs.tests.outputs.tested-version.

Step 3: Pin a version

The part after @ matters. You can use a branch name, a tag like v1, or a full commit SHA.

A branch like @main is easy, but any change to main hits every repo right away, even a broken one.
A tag like @v1 lets you test changes first, then move the tag when you are happy.
A commit SHA never changes. It is the safest choice when the shared file lives in a repo you do not control.

Calling a workflow in the same repo

If the shared file is in the same repo, use a short path with no @:

name: CI (same repo)

on:
  pull_request:

jobs:
  tests:
    strategy:
      matrix:
        python: ["3.12", "3.13"]
    uses: ./.github/workflows/python-ci.yml
    with:
      python-version: ${{ matrix.python }}
      run-lint: false

The matrix runs the shared workflow two times, once for each Python version.

Rules that trip people up

These all come from GitHub's own docs:

A calling job has no steps. A job with uses: can only have a short list of keys, like name, with, secrets, needs, if, strategy, concurrency and permissions. Add steps and the file is invalid. If you need extra steps, put them in a separate job, like tell-me above.
env does not cross over. Environment variables set at the top of the caller are not passed to the called workflow. Use inputs instead, or vars set at the repo or organization level.
The file must be in .github/workflows/. Sub-folders do not work.
Access rules apply. A public repo can only call reusable workflows from public repos. A private repo can call public ones, or private ones that have been shared with it in Settings.
There are limits. You can nest up to ten levels of workflows, and one workflow file can call at most 50 unique reusable workflows in total.
Token permissions can only go down. The called workflow can make the GITHUB_TOKEN weaker than the caller's, never stronger.

Check your files before you push

Run actionlint, a free checker for workflow files. It catches typos, wrong input types and the steps mistake from rule 1. All the YAML in this post passes it with no errors.

actionlint

Without it, you often only find a mistake after you push and the run fails.

When to use this, and when not to

Reusable workflows are a great fit when several repos run the same kind of job: test a Python package, build a container, deploy to the same cloud.

They are less useful when each repo is truly different. Forcing very different projects into one shared file gives you a giant file full of if: checks. In that case, a small composite action for the shared steps is often cleaner.

Quick recap

Add on: workflow_call to make a workflow callable.
Pass settings with inputs, secrets with secrets, and read results with outputs.
Call it with uses: at the job level, never inside steps.
Pin to a tag or a SHA, not a moving branch.
Lint with actionlint before you push.

Source: GitHub Docs: Reusing workflow configurations

If you landed here while reading about ByteBridge Talent LLC IT staffing, this is the kind of everyday clean-up our engineers write about: small changes that make a team's work calmer.

ByteBridge Talent LLC is a Grand Island, Nebraska team working on software development, cloud and DevOps, and data. Read more about us at bytebridgetalent.com.

Practical Secrets Management in Python: From .env Files to a Secrets Manager

ByteBridge Talent LLC — Sat, 17 Oct 2026 12:37:57 +0000

Many leaked credentials are not stolen by clever attackers. They get committed to git, printed in a stack trace (the error report Python shows when something crashes), or pasted into a chat thread. Good secrets management in Python is mostly about boring discipline: one place to load secrets, strict validation at startup, no accidental logging, and a path to a real secrets manager. This post builds that up step by step.

What counts as a secret?

A secret is any value that gives access to something. Database passwords, API tokens, cloud access keys, signing keys and webhook secrets are all secrets. If one leaks, someone else can act as your app. Secrets management is the set of habits and tools that keep these values safe: where you store them, how your Python code loads them, how you change (rotate) them, and how you stop them from showing up in logs or in git.

The five rules below are the base. Each step after that turns one rule into working Python code.

The rules

Secrets never live in source code or the repository.
The app reads secrets from the environment or a secrets manager, in one module.
If a secret is missing or in the wrong format, the app stops at startup with a clear error, not on the first request.
Secret values never appear in logs, printed objects, or error messages.
Rotation does not require a redeploy.

Step 1: A single config module with validation

Use the standard library only, so this works anywhere:

# config.py
import os
from dataclasses import dataclass, field


class ConfigError(RuntimeError):
    pass


class Secret:
    """Wraps a sensitive string so it is never printed by accident."""

    __slots__ = ("_value",)

    def __init__(self, value: str):
        self._value = value

    def reveal(self) -> str:
        return self._value

    def __repr__(self) -> str:
        return "Secret('**********')"

    __str__ = __repr__


def _require(name: str) -> str:
    value = os.environ.get(name)
    if value is None or not value.strip():
        raise ConfigError(f"Missing required environment variable: {name}")
    return value.strip()


@dataclass(frozen=True)
class Settings:
    database_url: Secret
    api_token: Secret
    log_level: str = field(default="INFO")

    @classmethod
    def from_env(cls) -> "Settings":
        db = _require("DATABASE_URL")
        if not db.startswith(("postgresql://", "postgres://")):
            raise ConfigError("DATABASE_URL must be a PostgreSQL URL")
        token = _require("API_TOKEN")
        if len(token) < 32:
            raise ConfigError("API_TOKEN looks too short (expected >= 32 chars)")
        return cls(
            database_url=Secret(db),
            api_token=Secret(token),
            log_level=os.environ.get("LOG_LEVEL", "INFO").upper(),
        )

Notice the error messages name the variable but never echo its value. Because Secret overrides __repr__, printing Settings gives you:

Settings(database_url=Secret('**********'), api_token=Secret('**********'), log_level='INFO')

Call Settings.from_env() once in main() and pass the result around. Code that needs the raw value must call .reveal(), which is easy to grep for in review.

Step 2: .env files for local development only

.env files are convenient locally. Load them only if they exist, and never in production:

# dev_env.py
import os
from pathlib import Path


def load_dotenv(path: str = ".env") -> None:
    """Minimal .env loader: KEY=VALUE lines, # comments, no overrides."""
    p = Path(path)
    if not p.is_file():
        return
    for raw in p.read_text(encoding="utf-8").splitlines():
        line = raw.strip()
        if not line or line.startswith("#") or "=" not in line:
            continue
        key, _, value = line.partition("=")
        key = key.strip()
        value = value.strip().strip('"').strip("'")
        os.environ.setdefault(key, value)

(python-dotenv does the same with more edge cases handled.) Add .env to .gitignore and commit a .env.example with placeholder values so new developers know what to set.

Step 3: Fetch from a secrets manager in production

Environment variables are visible to anything that can inspect the process, and they can't change without a restart. In production, fetch from a managed store such as AWS Secrets Manager, with a short cache time (a TTL, or "time to live": how many seconds a saved value is trusted before the code fetches it again), so a rotated secret is picked up without a redeploy:

# secrets_store.py
import json
import threading
import time

import boto3
from botocore.exceptions import ClientError


class CachedSecret:
    def __init__(self, secret_id: str, ttl_seconds: int = 300, client=None):
        self._secret_id = secret_id
        self._ttl = ttl_seconds
        self._client = client or boto3.client("secretsmanager")
        self._lock = threading.Lock()
        self._value = None
        self._fetched_at = 0.0

    def _fetch(self) -> dict:
        try:
            resp = self._client.get_secret_value(SecretId=self._secret_id)
        except ClientError as exc:
            code = exc.response["Error"]["Code"]
            raise RuntimeError(
                f"Could not read secret {self._secret_id!r}: {code}"
            ) from None
        return json.loads(resp["SecretString"])

    def get(self, force_refresh: bool = False) -> dict:
        with self._lock:
            expired = time.monotonic() - self._fetched_at > self._ttl
            if force_refresh or self._value is None or expired:
                self._value = self._fetch()
                self._fetched_at = time.monotonic()
            return self._value

raise ... from None drops the original exception chain, which keeps request details out of logs. Give the app's IAM role (its AWS identity) the secretsmanager:GetSecretValue permission only for the secrets it needs, listed by their ARN (each secret's full AWS ID).

Handling rotation gracefully

When a database password rotates, open connections keep working but new ones with the cached password fail. Retry once with a fresh secret:

import psycopg

db_secret = CachedSecret("prod/app/db")


def connect():
    for attempt in (1, 2):
        creds = db_secret.get(force_refresh=(attempt == 2))
        try:
            return psycopg.connect(
                host=creds["host"],
                dbname=creds["dbname"],
                user=creds["username"],
                password=creds["password"],
                connect_timeout=5,
            )
        except psycopg.OperationalError:
            if attempt == 2:
                raise

Step 4: Keep secrets out of logs

Logs are copied to many places: log tools, error trackers, support tickets. A secret in a log line can be read by far more people than the secret itself. So we add a safety net.

Even with Secret, a raw value can slip into a log line through an f-string or an exception from a library. Add a logging filter that redacts known values and common token patterns:

# redact.py
import logging
import re

TOKEN_PATTERNS = [
    re.compile(r"AKIA[0-9A-Z]{16}"),                 # AWS access key id
    re.compile(r"ghp_[A-Za-z0-9]{36}"),              # GitHub token
    re.compile(r"(?i)(password|passwd|pwd)=([^\s&]+)"),
]


class RedactFilter(logging.Filter):
    def __init__(self, known_secrets=()):
        super().__init__()
        self._known = [s for s in known_secrets if s]

    def filter(self, record: logging.LogRecord) -> bool:
        msg = record.getMessage()
        for s in self._known:
            msg = msg.replace(s, "[REDACTED]")
        for pat in TOKEN_PATTERNS:
            msg = pat.sub("[REDACTED]", msg)
        record.msg, record.args = msg, None
        return True


def install(known_secrets=()):
    handler = logging.StreamHandler()
    handler.addFilter(RedactFilter(known_secrets))
    logging.basicConfig(level=logging.INFO, handlers=[handler], force=True)

Usage: install([settings.api_token.reveal()]). The filter sits on the root logger's handler, so it covers log lines from every logger that passes its records up to the root logger (the default).

Step 5: Stop secrets before they reach git

Prevention beats cleanup. Run a scanner as a pre-commit hook (a check that runs every time you commit) and in CI (your automated build and test pipeline). With pre-commit and gitleaks:

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.21.2
    hooks:
      - id: gitleaks

pip install pre-commit
pre-commit install
pre-commit run --all-files

If a secret is committed anyway, rotate it first. Rewriting history with git filter-repo is useful cleanup, but forks, clones, and CI caches may already have the value.

Common pitfalls

Even teams with good tools make the same few mistakes. Watch for these in code review.

Logging the whole config or environment. logger.debug(os.environ) is a classic leak. Log key names only.
Secrets in Docker build args or layers. ARG/ENV values persist in image history. Use a BuildKit secret mount (RUN --mount=type=secret) instead. It gives the build step the secret without saving it in the image.
Caching forever. No TTL means rotation needs a restart. A few minutes is a good default.
One secret shared across environments. A dev leak becomes a prod incident. Use separate secrets per environment.
Broad IAM permissions. secretsmanager:* on * lets one compromised service read everything.
Validation errors that echo values. "Invalid token: abc123..." puts the secret in your error tracker.

The short checklist

Centralize loading, validate at startup, wrap values so they don't print, fetch from a manager with a TTL cache, and scan every commit. None of these steps is complicated, and together they close the most common ways credentials leak from Python services.

Notes from the ByteBridge Talent LLC software engineering team.

Least-Privilege AWS IAM for Small Teams: Permission Boundaries, Access Analyzer, and Terraform

ByteBridge Talent LLC — Wed, 14 Oct 2026 22:05:41 +0000

Small teams hit the same IAM wall. Either one person holds admin and becomes the bottleneck for every new Lambda role, or everyone gets AdministratorAccess "for now" and it never gets taken back. Neither scales.

Permission boundaries offer a middle path: developers can create and manage their own roles, but no role they create can ever exceed a ceiling you define. Pair that with IAM Access Analyzer to generate policies from real usage and flag unused access, and you get least privilege without a dedicated security team.

How permission boundaries work

A permission boundary is a managed policy attached to a user or role that sets the maximum permissions it can have. Effective permissions are the intersection:

effective = identity policies âˆ© permission boundary   (minus any explicit deny, SCPs, etc.)

A boundary grants nothing by itself. If the boundary allows s3:* but the role's policy allows only s3:GetObject, the role gets s3:GetObject. If the role's policy allows iam:* but the boundary doesn't, the role gets no IAM access.

The useful pattern: let developers call iam:CreateRole only if they attach the boundary. Then even a role with AdministratorAccess attached is capped.

Step 1: The boundary policy

This boundary allows typical application services, blocks privilege escalation, and prevents anyone from removing or editing the boundary itself. Replace 123456789012 with your account ID.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowAppServices",
      "Effect": "Allow",
      "Action": [
        "s3:*",
        "dynamodb:*",
        "sqs:*",
        "sns:*",
        "lambda:*",
        "logs:*",
        "cloudwatch:*",
        "xray:*",
        "events:*",
        "states:*",
        "ssm:GetParameter*",
        "secretsmanager:GetSecretValue",
        "kms:Decrypt",
        "kms:GenerateDataKey*"
      ],
      "Resource": "*"
    },
    {
      "Sid": "AllowRoleManagementOnlyWithBoundary",
      "Effect": "Allow",
      "Action": [
        "iam:CreateRole",
        "iam:PutRolePolicy",
        "iam:AttachRolePolicy",
        "iam:DetachRolePolicy",
        "iam:DeleteRolePolicy"
      ],
      "Resource": "arn:aws:iam::123456789012:role/app/*",
      "Condition": {
        "StringEquals": {
          "iam:PermissionsBoundary": "arn:aws:iam::123456789012:policy/app-boundary"
        }
      }
    },
    {
      "Sid": "AllowRoleHousekeeping",
      "Effect": "Allow",
      "Action": [
        "iam:GetRole",
        "iam:GetRolePolicy",
        "iam:ListRolePolicies",
        "iam:ListAttachedRolePolicies",
        "iam:TagRole",
        "iam:UntagRole",
        "iam:DeleteRole",
        "iam:UpdateAssumeRolePolicy",
        "iam:PassRole"
      ],
      "Resource": "arn:aws:iam::123456789012:role/app/*"
    },
    {
      "Sid": "DenyBoundaryTampering",
      "Effect": "Deny",
      "Action": [
        "iam:CreatePolicyVersion",
        "iam:DeletePolicy",
        "iam:DeletePolicyVersion",
        "iam:SetDefaultPolicyVersion"
      ],
      "Resource": "arn:aws:iam::123456789012:policy/app-boundary"
    },
    {
      "Sid": "DenyBoundaryRemoval",
      "Effect": "Deny",
      "Action": [
        "iam:DeleteRolePermissionsBoundary",
        "iam:DeleteUserPermissionsBoundary"
      ],
      "Resource": "*"
    },
    {
      "Sid": "DenyUserAndKeyCreation",
      "Effect": "Deny",
      "Action": [
        "iam:CreateUser",
        "iam:CreateAccessKey",
        "iam:CreateLoginProfile",
        "organizations:*",
        "account:*"
      ],
      "Resource": "*"
    }
  ]
}

Key choices:

Path scoping (role/app/*). Developer-created roles live under the /app/ path, so they can't touch your break-glass or CI roles elsewhere.
iam:PermissionsBoundary condition. CreateRole, PutRolePolicy, and AttachRolePolicy succeed only when the target role carries this exact boundary. That condition key is supported on those actions.
iam:PassRole limited to /app/. Developers can hand their roles to Lambda or ECS, but can't pass a more powerful role.
Explicit denies stop anyone from rewriting or detaching the boundary.

Apply the same boundary to the developers' own role. That way the developer, and every role the developer creates, sits under the same ceiling. Without it, a developer could create a role without the boundary through some other permission they hold.

Step 2: Terraform for the boundary and a bounded role

data "aws_caller_identity" "current" {}

resource "aws_iam_policy" "app_boundary" {
  name        = "app-boundary"
  description = "Permission ceiling for developer-managed application roles"
  policy = templatefile("${path.module}/app-boundary.json.tftpl", {
    account_id = data.aws_caller_identity.current.account_id
  })
}

data "aws_iam_policy_document" "lambda_trust" {
  statement {
    actions = ["sts:AssumeRole"]
    principals {
      type        = "Service"
      identifiers = ["lambda.amazonaws.com"]
    }
  }
}

resource "aws_iam_role" "orders_api" {
  name                 = "orders-api"
  path                 = "/app/"
  assume_role_policy   = data.aws_iam_policy_document.lambda_trust.json
  permissions_boundary = aws_iam_policy.app_boundary.arn
}

data "aws_iam_policy_document" "orders_api" {
  statement {
    sid       = "OrdersTable"
    actions   = ["dynamodb:GetItem", "dynamodb:PutItem", "dynamodb:Query"]
    resources = ["arn:aws:dynamodb:us-east-1:${data.aws_caller_identity.current.account_id}:table/orders"]
  }
  statement {
    sid       = "Logs"
    actions   = ["logs:CreateLogStream", "logs:PutLogEvents"]
    resources = ["arn:aws:logs:us-east-1:${data.aws_caller_identity.current.account_id}:log-group:/aws/lambda/orders-api:*"]
  }
}

resource "aws_iam_role_policy" "orders_api" {
  name   = "orders-api"
  role   = aws_iam_role.orders_api.id
  policy = data.aws_iam_policy_document.orders_api.json
}

Save the boundary JSON from Step 1 as app-boundary.json.tftpl, replacing 123456789012 with ${account_id}. The templatefile call fills it in.

The role's own policy is narrow; the boundary is the safety net if someone later attaches something broad. To make the boundary hard to forget, wrap the role in a small module where permissions_boundary and path are fixed and not variables:

# modules/app-role/main.tf
variable "name" { type = string }
variable "trust_policy_json" { type = string }
variable "boundary_arn" { type = string }

resource "aws_iam_role" "this" {
  name                 = var.name
  path                 = "/app/"
  assume_role_policy   = var.trust_policy_json
  permissions_boundary = var.boundary_arn
}

output "role_arn" { value = aws_iam_role.this.arn }
output "role_name" { value = aws_iam_role.this.name }

Proving the boundary works

Assume the developer role and try to create a role without the boundary:

aws iam create-role \
  --role-name test-no-boundary \
  --path /app/ \
  --assume-role-policy-document file://lambda-trust.json
# An error occurred (AccessDenied) ... not authorized to perform: iam:CreateRole

Then retry with --permissions-boundary arn:aws:iam::123456789012:policy/app-boundary and it succeeds. Put this check in your onboarding docs; it is the fastest way to show the team that the guardrail is real.

Step 3: Generate policies from real usage with Access Analyzer

Writing narrow policies by hand is slow. IAM Access Analyzer can read CloudTrail and generate a policy based on what a role actually called. You need a CloudTrail trail (management events) logging to S3, and a service role Access Analyzer can use to read it.

aws accessanalyzer start-policy-generation \
  --policy-generation-details '{"principalArn":"arn:aws:iam::123456789012:role/app/orders-api"}' \
  --cloud-trail-details '{
    "trails":[{"cloudTrailArn":"arn:aws:cloudtrail:us-east-1:123456789012:trail/management","allRegions":true}],
    "accessRole":"arn:aws:iam::123456789012:role/service-role/AccessAnalyzerMonitorServiceRole",
    "startTime":"2026-09-15T00:00:00Z",
    "endTime":"2026-10-15T00:00:00Z"
  }'
# returns a jobId

aws accessanalyzer get-generated-policy \
  --job-id <jobId> \
  --include-resource-placeholders

The output is a draft policy listing the actions used. Treat it as a starting point:

It captures management events by default. Data events such as s3:GetObject and dynamodb:GetItem appear only if your trail logs them, so add those by hand if needed.
Use --include-resource-placeholders and replace placeholders with real ARNs; a generated "Resource": "*" is not least privilege.
Use a window that covers the role's full cycle, including monthly jobs, or you'll strip permissions that run rarely.

Before applying any edited policy, validate it:

aws accessanalyzer validate-policy \
  --policy-type IDENTITY_POLICY \
  --policy-document file://orders-api.json

This catches errors, security warnings (like iam:PassRole with *), and suggestions. You can run it in CI against terraform show -json output so bad policies fail review.

Step 4: Unused-access findings

Policy generation is per role and on demand. Unused-access analyzers run continuously across the account and report:

roles not used within the tracking period,
unused access keys and passwords,
permissions granted but not used (at service and action level).

Create one in Terraform:

resource "aws_accessanalyzer_analyzer" "unused" {
  analyzer_name = "unused-access"
  type          = "ACCOUNT_UNUSED_ACCESS"

  configuration {
    unused_access {
      unused_access_age = 90
    }
  }
}

Unused-access analyzers are a paid feature, billed per IAM role and user analyzed per month, so check current pricing before enabling. For a small account the cost is usually modest. External-access analyzers (type = "ACCOUNT") are free and worth enabling too, since they flag resources shared outside your account.

List active findings:

aws accessanalyzer list-findings-v2 \
  --analyzer-arn arn:aws:access-analyzer:us-east-1:123456789012:analyzer/unused-access \
  --filter '{"status":{"eq":["ACTIVE"]}}'

Review them in a monthly slot. Delete unused roles, remove unused services from policies, and archive findings that are deliberate (for example, disaster-recovery roles that sit idle by design) with an archive rule so they don't keep resurfacing.

A least-privilege checklist for small teams

[ ] Humans sign in through IAM Identity Center; no IAM users with long-lived keys.
[ ] A permission boundary exists and is attached to developer roles and every role they create.
[ ] Developer-managed roles live under a dedicated path such as /app/.
[ ] iam:PassRole is scoped to that path, never *.
[ ] The boundary denies editing or removing itself.
[ ] Application roles are created through a Terraform module that fixes the boundary.
[ ] New role policies start from Access Analyzer policy generation, then get real resource ARNs.
[ ] validate-policy runs in CI on IAM changes.
[ ] An external-access analyzer is enabled in every region you use.
[ ] An unused-access analyzer is enabled and findings are reviewed monthly.
[ ] Break-glass admin access exists, is documented, and alerts when used.

Wrap-up

Permission boundaries let a small team move fast without one person approving every role, and Access Analyzer turns "least privilege" from a guess into something based on actual usage. Start with the boundary, since it caps the blast radius immediately, then tighten individual roles over time as the findings come in.

Written by the ByteBridge Talent LLC software engineering team.

ByteBridge Talent LLC is an E-Verify enrolled tech staffing firm in Grand Island, Nebraska: bytebridgetalent.com

Catching Terraform Drift Early: Scheduled Plans in GitHub Actions with AWS OIDC (No Long-Lived Keys)

ByteBridge Talent LLC — Wed, 14 Oct 2026 21:55:14 +0000

Terraform state describes what you think is deployed. Drift is the gap between that and reality: someone changes a security group in the console during an incident, an autoscaling event edits a tag, or a teammate runs apply from a stale branch. Drift is rarely dramatic on the day it happens. It hurts later, when an unrelated change produces a plan full of surprises and nobody is sure which side is right.

The fix is cheap: run terraform plan on a schedule, read the exit code, and open an issue when something differs. This post builds that pipeline in GitHub Actions, authenticates to AWS with OIDC so there are no stored access keys, and fans out across multiple workspaces with a matrix.

What we are building

An IAM OIDC identity provider for GitHub and a read-only IAM role that only this repository's workflow can assume.
A scheduled workflow that runs terraform plan -detailed-exitcode -lock=false nightly.
A matrix that checks several environments (directories or workspaces) in parallel.
An issue per environment when drift is detected, updated instead of duplicated on later runs.

Step 1: The OIDC provider and drift-check role

GitHub Actions can request a short-lived OIDC token that AWS STS exchanges for temporary credentials. You define the trust once, in Terraform:

data "tls_certificate" "github" {
  url = "https://token.actions.githubusercontent.com/.well-known/openid-configuration"
}

resource "aws_iam_openid_connect_provider" "github" {
  url             = "https://token.actions.githubusercontent.com"
  client_id_list  = ["sts.amazonaws.com"]
  thumbprint_list = [data.tls_certificate.github.certificates[0].sha1_fingerprint]
}

data "aws_iam_policy_document" "drift_trust" {
  statement {
    actions = ["sts:AssumeRoleWithWebIdentity"]

    principals {
      type        = "Federated"
      identifiers = [aws_iam_openid_connect_provider.github.arn]
    }

    condition {
      test     = "StringEquals"
      variable = "token.actions.githubusercontent.com:aud"
      values   = ["sts.amazonaws.com"]
    }

    # Only the main branch of this one repository.
    condition {
      test     = "StringEquals"
      variable = "token.actions.githubusercontent.com:sub"
      values   = ["repo:my-org/infra:ref:refs/heads/main"]
    }
  }
}

resource "aws_iam_role" "drift_check" {
  name                 = "github-terraform-drift-check"
  assume_role_policy   = data.aws_iam_policy_document.drift_trust.json
  max_session_duration = 3600
}

If an OIDC provider for GitHub already exists in the account, reference it with a data "aws_iam_openid_connect_provider" block instead of creating a second one; AWS allows only one provider per URL. AWS also now validates GitHub's certificate chain itself, so the thumbprint is mostly a formality, but the provider resource still requires a value in older provider versions.

The sub condition is the important part. Without it, any repository on GitHub could assume the role. Pin it to the exact repo and ref. If you trigger from a GitHub environment instead, the subject becomes repo:my-org/infra:environment:prod.

Permissions: plan needs to read, not write

terraform plan refreshes every resource, so the role needs broad read access plus access to the state backend:

resource "aws_iam_role_policy_attachment" "read_only" {
  role       = aws_iam_role.drift_check.name
  policy_arn = "arn:aws:iam::aws:policy/ReadOnlyAccess"
}

data "aws_iam_policy_document" "state_read" {
  statement {
    actions   = ["s3:GetObject", "s3:ListBucket"]
    resources = [
      "arn:aws:s3:::my-org-tf-state",
      "arn:aws:s3:::my-org-tf-state/*",
    ]
  }
  statement {
    actions   = ["dynamodb:GetItem", "dynamodb:DescribeTable"]
    resources = ["arn:aws:dynamodb:us-east-1:123456789012:table/tf-locks"]
  }
}

resource "aws_iam_role_policy" "state_read" {
  name   = "terraform-state-read"
  role   = aws_iam_role.drift_check.id
  policy = data.aws_iam_policy_document.state_read.json
}

ReadOnlyAccess is wide, and it includes reads of things like S3 objects. If that is too much for your account, start with it, then tighten using the IAM Access Analyzer policy generation covered in our least-privilege post. Because the role cannot write, a compromised workflow can look but not change anything. We run plan with -lock=false so the role never needs to write lock entries; a read-only plan cannot corrupt state.

Note that some data sources and providers read secrets (for example aws_secretsmanager_secret_version). If your configuration uses them, the role needs that access too, and the plan output may contain sensitive values. Keep plan output out of public issues.

Step 2: Understanding `-detailed-exitcode`

By default terraform plan exits 0 whether or not changes exist. With -detailed-exitcode:

Exit code	Meaning
`0`	Succeeded, no changes
`1`	Error
`2`	Succeeded, changes present (drift or unapplied code)

This is what lets a pipeline distinguish "drift" from "broken". One subtlety: exit code 2 also fires when main contains merged code that was never applied. That is still worth an alert, since it means main doesn't match production.

Step 3: The scheduled workflow with a matrix

Assume a repository layout with one root module per environment:

envs/
  dev/
  staging/
  prod/

.github/workflows/drift.yml:

name: terraform-drift

on:
  schedule:
    - cron: "17 2 * * *"   # 02:17 UTC daily; off the hour to avoid queue spikes
  workflow_dispatch: {}

permissions:
  id-token: write   # required to request the OIDC token
  contents: read
  issues: write

concurrency:
  group: terraform-drift
  cancel-in-progress: false

jobs:
  plan:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        env: [dev, staging, prod]
    defaults:
      run:
        working-directory: envs/${{ matrix.env }}
    steps:
      - uses: actions/checkout@v4

      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/github-terraform-drift-check
          aws-region: us-east-1
          role-session-name: drift-${{ matrix.env }}-${{ github.run_id }}

      - uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: 1.9.8
          terraform_wrapper: false   # keep real exit codes

      - name: terraform init
        run: terraform init -input=false

      - name: terraform plan
        id: plan
        run: |
          set +e
          terraform plan -detailed-exitcode -lock=false -input=false -no-color -out=tfplan > plan.txt 2>&1
          code=$?
          set -e
          echo "exitcode=$code" >> "$GITHUB_OUTPUT"
          if [ "$code" -eq 1 ]; then
            cat plan.txt
            exit 1
          fi
          terraform show -no-color tfplan | grep -E '^\s*# .* (will|must) be' > summary.txt || true
          cat summary.txt

      - name: Open or update drift issue
        if: steps.plan.outputs.exitcode == '2'
        env:
          GH_TOKEN: ${{ github.token }}
          ENV_NAME: ${{ matrix.env }}
        run: |
          title="Terraform drift detected: ${ENV_NAME}"
          {
            echo "Scheduled plan found changes in \`envs/${ENV_NAME}\`."
            echo
            echo "Run: ${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}"
            echo
            echo '```
{% endraw %}
'
            head -c 60000 summary.txt
            echo '
{% raw %}
```'
          } > body.md

          existing=$(gh issue list --repo "$GITHUB_REPOSITORY" --state open \
            --label drift --search "in:title \"${title}\"" --json number --jq '.[0].number')

          if [ -n "$existing" ]; then
            gh issue comment "$existing" --repo "$GITHUB_REPOSITORY" --body-file body.md
          else
            gh issue create --repo "$GITHUB_REPOSITORY" --title "$title" \
              --label drift --body-file body.md
          fi

Create the drift label once (gh label create drift --color B60205) or gh issue create --label will fail.

A few details that matter:

terraform_wrapper: false. The setup-terraform wrapper intercepts output and can mask exit codes in some versions. Turning it off keeps $? honest.
set +e around plan. GitHub's default bash runs with -e, so exit code 2 would fail the step before you can read it.
Summary, not full plan. The issue gets only the resource-level lines (# aws_security_group.web will be updated in-place). The full plan can contain sensitive attributes. Engineers can rerun locally or read the job log.
fail-fast: false. A broken dev shouldn't cancel the prod check.
Dedupe. The workflow comments on an existing open issue rather than opening a new one every night. Close the issue when drift is resolved and the next detection opens a fresh one.

Using Terraform workspaces instead of directories

If you use one root module with terraform workspace, swap the matrix and select the workspace after init:

    strategy:
      fail-fast: false
      matrix:
        workspace: [dev, staging, prod]
    steps:
      # ...checkout, credentials, setup-terraform as above...
      - run: terraform init -input=false
      - run: terraform workspace select ${{ matrix.workspace }}
      - name: terraform plan
        run: terraform plan -detailed-exitcode -lock=false -input=false -no-color -var-file=${{ matrix.workspace }}.tfvars

Alternatively, set TF_WORKSPACE: ${{ matrix.workspace }} as an env var on the job, which Terraform reads automatically.

If environments live in separate AWS accounts (recommended), use include to give each its own role:

      matrix:
        include:
          - env: dev
            role: arn:aws:iam::111111111111:role/github-terraform-drift-check
          - env: prod
            role: arn:aws:iam::222222222222:role/github-terraform-drift-check

and pass role-to-assume: ${{ matrix.role }}. Each account gets its own OIDC provider and role with the same trust policy.

Triage: what to do when the issue opens

Drift has three common causes, and each has a different fix:

Out-of-band change that should stay. Codify it in Terraform, open a PR, and the next plan goes clean.
Out-of-band change that should not stay. Run terraform apply through your normal pipeline to revert it.
Noise. Attributes that AWS or another controller manages (autoscaling desired count, tags added by other tools). Use lifecycle { ignore_changes = [...] } narrowly, on the specific attribute, with a comment explaining why.

To see only drift without your pending code changes, run terraform plan -refresh-only. It shows what changed in the real world compared to state, without diffing against configuration.

Limits worth knowing

Drift detection only covers resources Terraform manages. Things created entirely by hand are invisible to it; AWS Config or a tagging policy covers that gap.
A nightly schedule means drift can exist for up to a day. For security-sensitive resources, pair this with real-time alerts (EventBridge on CloudTrail events).
GitHub disables scheduled workflows in repositories with no activity for 60 days. A quiet infra repo can silently stop checking, so watch for that.

Wrap-up

With an OIDC role scoped to one repo and branch, a read-only permission set, and -detailed-exitcode, drift detection becomes a small, boring workflow that runs every night and only speaks up when something is off. There are no keys to rotate, and each environment's status shows up as an issue your team already knows how to triage.

Written by the ByteBridge Talent LLC software engineering team.

ByteBridge Talent LLC is an E-Verify enrolled tech staffing firm in Grand Island, Nebraska: bytebridgetalent.com

A Reusable Terraform Module for Secure S3 Buckets, with Remote State and CI Plan Checks

ByteBridge Talent LLC — Wed, 14 Oct 2026 21:36:02 +0000

Copy-pasting S3 bucket resources between projects is how buckets end up unencrypted, public, or unversioned. A small module turns your team's standards into the default. In this post we'll build one, keep Terraform state in S3 with locking, and add a GitHub Actions workflow that runs terraform plan on every pull request.

Tested with Terraform 1.10+ and AWS provider 5.x.

Project layout

.
├── modules/
│   └── secure-bucket/
│       ├── main.tf
│       ├── variables.tf
│       └── outputs.tf
├── envs/
│   └── prod/
│       ├── backend.tf
│       └── main.tf
└── .github/workflows/terraform-plan.yml

The module

variables.tf

variable "bucket_name" {
  description = "Globally unique bucket name."
  type        = string

  validation {
    condition     = can(regex("^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$", var.bucket_name))
    error_message = "Bucket name must be 3-63 chars of lowercase letters, digits, dots or hyphens."
  }
}

variable "kms_key_arn" {
  description = "Optional KMS key ARN. If null, SSE-S3 (AES256) is used."
  type        = string
  default     = null
}

variable "noncurrent_version_days" {
  description = "Days to keep noncurrent object versions."
  type        = number
  default     = 90
}

variable "force_destroy" {
  description = "Allow destroying a non-empty bucket. Keep false in production."
  type        = bool
  default     = false
}

variable "tags" {
  description = "Tags applied to the bucket."
  type        = map(string)
  default     = {}
}

main.tf

terraform {
  required_version = ">= 1.10"
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

resource "aws_s3_bucket" "this" {
  bucket        = var.bucket_name
  force_destroy = var.force_destroy
  tags          = var.tags
}

resource "aws_s3_bucket_ownership_controls" "this" {
  bucket = aws_s3_bucket.this.id
  rule {
    object_ownership = "BucketOwnerEnforced"
  }
}

resource "aws_s3_bucket_public_access_block" "this" {
  bucket                  = aws_s3_bucket.this.id
  block_public_acls       = true
  block_public_policy     = true
  ignore_public_acls      = true
  restrict_public_buckets = true
}

resource "aws_s3_bucket_versioning" "this" {
  bucket = aws_s3_bucket.this.id
  versioning_configuration {
    status = "Enabled"
  }
}

resource "aws_s3_bucket_server_side_encryption_configuration" "this" {
  bucket = aws_s3_bucket.this.id
  rule {
    apply_server_side_encryption_by_default {
      sse_algorithm     = var.kms_key_arn == null ? "AES256" : "aws:kms"
      kms_master_key_id = var.kms_key_arn
    }
    bucket_key_enabled = var.kms_key_arn != null
  }
}

resource "aws_s3_bucket_lifecycle_configuration" "this" {
  bucket = aws_s3_bucket.this.id

  rule {
    id     = "expire-noncurrent-versions"
    status = "Enabled"
    filter {}

    noncurrent_version_expiration {
      noncurrent_days = var.noncurrent_version_days
    }

    abort_incomplete_multipart_upload {
      days_after_initiation = 7
    }
  }

  depends_on = [aws_s3_bucket_versioning.this]
}

data "aws_iam_policy_document" "tls_only" {
  statement {
    sid     = "DenyInsecureTransport"
    effect  = "Deny"
    actions = ["s3:*"]
    resources = [
      aws_s3_bucket.this.arn,
      "${aws_s3_bucket.this.arn}/*",
    ]
    principals {
      type        = "*"
      identifiers = ["*"]
    }
    condition {
      test     = "Bool"
      variable = "aws:SecureTransport"
      values   = ["false"]
    }
  }
}

resource "aws_s3_bucket_policy" "tls_only" {
  bucket     = aws_s3_bucket.this.id
  policy     = data.aws_iam_policy_document.tls_only.json
  depends_on = [aws_s3_bucket_public_access_block.this]
}

outputs.tf

output "bucket_id" {
  value = aws_s3_bucket.this.id
}

output "bucket_arn" {
  value = aws_s3_bucket.this.arn
}

A few design choices worth noting. BucketOwnerEnforced disables ACLs entirely, so access is controlled only by policies. The TLS-only policy rejects plain-HTTP requests. The lifecycle rule stops versioning from growing storage costs forever.

Remote state with locking

Local state files get lost, and two engineers applying at once can corrupt them. Store state in S3. Since Terraform 1.10, the S3 backend can lock with a lock file in the bucket itself (use_lockfile), so a DynamoDB table is no longer required.

Create the state bucket once, outside the configuration that uses it (a small bootstrap stack, or the CLI):

#!/usr/bin/env bash
set -euo pipefail
BUCKET="acme-tfstate-prod"
REGION="us-east-1"

aws s3api create-bucket --bucket "$BUCKET" --region "$REGION"
aws s3api put-bucket-versioning --bucket "$BUCKET" \
  --versioning-configuration Status=Enabled
aws s3api put-public-access-block --bucket "$BUCKET" \
  --public-access-block-configuration \
  BlockPublicAcls=true,IgnorePublicAcls=true,BlockPublicPolicy=true,RestrictPublicBuckets=true

(For regions other than us-east-1, add --create-bucket-configuration LocationConstraint=$REGION.)

envs/prod/backend.tf

terraform {
  backend "s3" {
    bucket       = "acme-tfstate-prod"
    key          = "storage/terraform.tfstate"
    region       = "us-east-1"
    encrypt      = true
    use_lockfile = true
  }
}

envs/prod/main.tf

provider "aws" {
  region = "us-east-1"
}

module "reports_bucket" {
  source      = "../../modules/secure-bucket"
  bucket_name = "acme-prod-reports"
  tags = {
    env   = "prod"
    owner = "data-platform"
  }
}

output "reports_bucket_arn" {
  value = module.reports_bucket.bucket_arn
}

If you're on an older Terraform version, use dynamodb_table = "terraform-locks" with a table whose hash key is LockID (string) instead of use_lockfile.

CI: terraform plan on every pull request

The workflow below checks formatting, validates, and runs a plan. It authenticates to AWS with GitHub's OIDC provider, so no long-lived access keys live in repository secrets.

name: terraform-plan

on:
  pull_request:
    paths:
      - "modules/**"
      - "envs/**"

permissions:
  contents: read
  id-token: write

jobs:
  plan:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: envs/prod
    steps:
      - uses: actions/checkout@v4

      - uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: 1.10.5

      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/github-terraform-plan
          aws-region: us-east-1

      - name: Format check
        run: terraform fmt -check -recursive ../..

      - name: Init
        run: terraform init -input=false

      - name: Validate
        run: terraform validate -no-color

      - name: Plan
        run: terraform plan -input=false -no-color -lock-timeout=120s -detailed-exitcode
        continue-on-error: true
        id: plan

      - name: Fail on plan error
        if: steps.plan.outputs.exitcode == '1'
        run: exit 1

-detailed-exitcode returns 0 for no changes, 2 for changes, and 1 for errors. Only an actual error fails the job. Give the plan role read-only permissions plus access to the state bucket. Applies should use a separate, more privileged role that runs only on the main branch.

Common pitfalls

Inline bucket arguments. In AWS provider 4+, versioning, server_side_encryption_configuration, and similar blocks on aws_s3_bucket are deprecated. Use the standalone resources shown above.
State bucket managed by the same stack it stores. One destroy deletes your state. Bootstrap it separately and protect it.
Forgetting state contains secrets. Outputs and some resource attributes land in state in plain text. Restrict who can read the state bucket.
force_destroy = true in production. Fine for test buckets, dangerous for anything with data.
Lifecycle filter omitted. Newer provider versions warn or fail without filter {}. Include it explicitly.
Plans with long-lived keys in CI. Prefer OIDC roles scoped per environment.

Wrap-up

A module encodes the security defaults once, remote state with locking keeps the team in sync, and a plan check on every pull request makes infrastructure changes reviewable like any other code. Start with one bucket module, then apply the same pattern to VPCs, IAM roles, and databases.

Written by the ByteBridge Talent LLC software engineering team.

ByteBridge Talent LLC is an E-Verify enrolled tech staffing firm in Grand Island, Nebraska: bytebridgetalent.com

Zero-Downtime Kubernetes Deploys: Probes, Rolling Updates, and PodDisruptionBudgets

ByteBridge Talent LLC — Wed, 14 Oct 2026 04:06:44 +0000

Kubernetes advertises rolling updates out of the box, yet many teams still see a burst of 502s on every deploy. The defaults are only part of the story: zero downtime needs correct probes, a sensible rollout strategy, graceful shutdown, and protection from voluntary disruptions like node drains. This post walks through each piece with manifests you can apply today.

Why requests get dropped

During a rollout, three things can go wrong:

New pods receive traffic before they are ready. The container process is running, but caches, DB pools, or JIT warm-up are not done.
Old pods are killed while they still have in-flight requests. Endpoint removal and SIGTERM happen concurrently, so a pod may receive new connections after it starts shutting down.
Too many pods disappear at once. A rollout combined with a node drain or autoscaler scale-down can drop capacity below what your traffic needs.

Each problem has a dedicated Kubernetes feature.

Step 1: Readiness, liveness, and startup probes

Readiness decides whether a pod is in the Service's endpoints. Fail it and traffic stops; the pod is not restarted.
Liveness decides whether the container should be restarted. Use it only for "this process is wedged" conditions.
Startup holds off liveness checks until a slow-starting app has booted.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
  labels:
    app: web
spec:
  replicas: 4
  revisionHistoryLimit: 5
  selector:
    matchLabels:
      app: web
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 25%
      maxUnavailable: 0
  minReadySeconds: 10
  template:
    metadata:
      labels:
        app: web
    spec:
      terminationGracePeriodSeconds: 45
      containers:
        - name: web
          image: ghcr.io/example/web:1.4.2
          ports:
            - name: http
              containerPort: 8080
          resources:
            requests:
              cpu: 250m
              memory: 256Mi
            limits:
              memory: 512Mi
          startupProbe:
            httpGet:
              path: /healthz
              port: http
            periodSeconds: 5
            failureThreshold: 24   # up to 120s to boot
          readinessProbe:
            httpGet:
              path: /ready
              port: http
            periodSeconds: 5
            timeoutSeconds: 2
            failureThreshold: 2
          livenessProbe:
            httpGet:
              path: /healthz
              port: http
            periodSeconds: 10
            timeoutSeconds: 2
            failureThreshold: 3
          lifecycle:
            preStop:
              exec:
                command: ["sh", "-c", "sleep 10"]

Keep /healthz cheap and local: it should answer "is my process alive?", not "is the database up?". If liveness checks a shared dependency, a database blip restarts every pod at once. /ready can check dependencies the pod truly can't serve without.

Step 2: A rollout strategy that never reduces capacity

The two knobs that matter:

maxUnavailable: 0 means Kubernetes never removes an old pod until a new one is Ready.
maxSurge: 25% lets it create extra pods (here, 1 of 4) above the desired count during the rollout.

minReadySeconds: 10 requires a new pod to stay Ready for 10 seconds before it counts as available. That catches apps that pass their first readiness check and then crash.

The trade-off is that you need spare cluster capacity for the surge pods. If your cluster is tightly packed, the rollout stalls in Pending instead of dropping traffic, which is the failure mode you want.

Step 3: Graceful shutdown

When a pod is deleted, Kubernetes sends SIGTERM and, in parallel, removes the pod from Service endpoints. kube-proxy, ingress controllers, and cloud load balancers take a few seconds to notice. The preStop sleep above keeps the pod serving during that window; only then does SIGTERM reach your process.

Your application must also handle SIGTERM by finishing in-flight requests. A minimal Python example:

import signal
import sys
from http.server import ThreadingHTTPServer, BaseHTTPRequestHandler
import threading


class Handler(BaseHTTPRequestHandler):
    def do_GET(self):
        body = b"ok"
        self.send_response(200)
        self.send_header("Content-Length", str(len(body)))
        self.end_headers()
        self.wfile.write(body)


server = ThreadingHTTPServer(("0.0.0.0", 8080), Handler)


def shutdown(signum, frame):
    # shutdown() blocks until serve_forever exits, so run it in a thread
    threading.Thread(target=server.shutdown, daemon=True).start()


signal.signal(signal.SIGTERM, shutdown)
server.serve_forever()
server.server_close()
sys.exit(0)

Make sure terminationGracePeriodSeconds exceeds the preStop sleep plus your longest request. Otherwise the kubelet sends SIGKILL mid-request.

Step 4: PodDisruptionBudgets for voluntary disruptions

Rollouts aren't the only time pods go away. kubectl drain, cluster upgrades, and the cluster autoscaler all evict pods. A PodDisruptionBudget (PDB) tells the eviction API how many pods must stay up:

apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: web-pdb
spec:
  minAvailable: 3
  selector:
    matchLabels:
      app: web

With 4 replicas and minAvailable: 3, a drain evicts at most one web pod at a time and waits for its replacement to become Ready. Spread the replicas across nodes so a single drain doesn't touch most of them:

      topologySpreadConstraints:
        - maxSkew: 1
          topologyKey: kubernetes.io/hostname
          whenUnsatisfiable: ScheduleAnyway
          labelSelector:
            matchLabels:
              app: web

(Add that under spec.template.spec in the Deployment.)

Step 5: Deploy and verify with kubectl

#!/usr/bin/env bash
set -euo pipefail

NS="${NS:-default}"
IMAGE="${1:?usage: deploy.sh <image>}"

kubectl -n "$NS" set image deployment/web web="$IMAGE"
kubectl -n "$NS" annotate deployment/web \
  kubernetes.io/change-cause="deploy $IMAGE" --overwrite

if ! kubectl -n "$NS" rollout status deployment/web --timeout=300s; then
  echo "Rollout failed, rolling back" >&2
  kubectl -n "$NS" rollout undo deployment/web
  kubectl -n "$NS" rollout status deployment/web --timeout=300s
  exit 1
fi

kubectl -n "$NS" get pdb web-pdb

Set spec.progressDeadlineSeconds (default 600) so a stuck rollout is reported as failed and rollout status exits non-zero.

To prove zero downtime, run a load loop against the Service while deploying:

while true; do
  code=$(curl -s -o /dev/null -w '%{http_code}' http://web.default.svc.cluster.local/)
  [ "$code" != "200" ] && echo "$(date +%T) got $code"
  sleep 0.1
done

Any line printed during a rollout is a dropped request worth investigating.

Common pitfalls

Liveness probe identical to readiness, checking the database. One dependency outage becomes a cluster-wide restart storm.
No preStop delay. Traffic still routes to terminating pods for a few seconds, causing connection resets.
minAvailable equal to replicas. The PDB blocks every drain forever, and node upgrades hang.
Single replica. No probe or PDB can make one pod zero-downtime. Run at least two.
Shells that swallow signals. command: ["sh", "-c", "python app.py"] may leave sh as PID 1, and it won't forward SIGTERM. Use exec or an init like tini.
Probe timeouts too tight. A 1s timeout on a GC-heavy JVM causes flapping under load.

Wrap-up

Zero-downtime deploys come from layers that work together: probes gate traffic, maxUnavailable: 0 preserves capacity, preStop plus SIGTERM handling drains connections, and PDBs guard against drains. Add the curl loop to your staging pipeline and you'll catch regressions before users do.

Written by the ByteBridge Talent LLC engineering team.

DEV Community: ByteBridge Talent LLC

Search Results That Jump Back to an Old Query in React: Finding and Fixing the Race

The problem

The root cause

The fix

Why keep the ignore flag if we already abort?

How we tested it

Trade-offs

Make sure the stale results are gone

Official sources

Clear JSON Errors in FastAPI: One Shape for Every Failure

Two words first

The problem: two shapes by default

One shape for all errors

The app with four handlers

See every error in one run

Lock it in with tests

Small rules that keep errors useful

Key points

GitHub Actions Reusable Workflows: Write Your CI Once, Use It in Every Repo

Two words first

Step 1: Write the shared workflow

Step 2: Call it from each repo

Step 3: Pin a version

Calling a workflow in the same repo

Rules that trip people up

Check your files before you push

When to use this, and when not to

Quick recap

Practical Secrets Management in Python: From .env Files to a Secrets Manager

What counts as a secret?

The rules

Step 1: A single config module with validation

Step 2: .env files for local development only

Step 3: Fetch from a secrets manager in production

Handling rotation gracefully

Step 4: Keep secrets out of logs

Step 5: Stop secrets before they reach git

Common pitfalls

The short checklist

Least-Privilege AWS IAM for Small Teams: Permission Boundaries, Access Analyzer, and Terraform

How permission boundaries work

Step 1: The boundary policy

Step 2: Terraform for the boundary and a bounded role

Proving the boundary works

Step 3: Generate policies from real usage with Access Analyzer

Step 4: Unused-access findings

A least-privilege checklist for small teams

Wrap-up

Catching Terraform Drift Early: Scheduled Plans in GitHub Actions with AWS OIDC (No Long-Lived Keys)

What we are building

Step 1: The OIDC provider and drift-check role

Permissions: plan needs to read, not write

Step 2: Understanding -detailed-exitcode

Step 3: The scheduled workflow with a matrix

Using Terraform workspaces instead of directories

Triage: what to do when the issue opens

Limits worth knowing

Wrap-up

A Reusable Terraform Module for Secure S3 Buckets, with Remote State and CI Plan Checks

Project layout

The module

variables.tf

main.tf

outputs.tf

Remote state with locking

envs/prod/backend.tf

envs/prod/main.tf

CI: terraform plan on every pull request

Common pitfalls

Wrap-up

Zero-Downtime Kubernetes Deploys: Probes, Rolling Updates, and PodDisruptionBudgets

Why requests get dropped

Step 1: Readiness, liveness, and startup probes

Step 2: A rollout strategy that never reduces capacity

Step 3: Graceful shutdown

Step 4: PodDisruptionBudgets for voluntary disruptions

Step 5: Deploy and verify with kubectl

Common pitfalls

Wrap-up

Why keep the `ignore` flag if we already abort?

Step 2: Understanding `-detailed-exitcode`