DEV Community: Susumu Takahashi

DNS Records Explained — What A, CNAME, and TXT Records Actually Point To

Susumu Takahashi — Wed, 30 Sep 2026 00:40:54 +0000

"Configuring a domain" usually boils down to "adding a DNS record." Setting up a subdomain, improving email deliverability, proving ownership of a domain to some external service — the goals differ, but the actual task is often the same: add one line in a domain management panel. This post walks through three of the most common DNS record types — A, CNAME, and TXT — what each one actually points to, and two real examples from our own domain.

What DNS is resolving

Between typing wpmm.jp into a browser and a page actually loading, there's a lookup happening: "this human-readable name — which server's IP address does it actually correspond to?" DNS (the Domain Name System) is the distributed database that answers that question, organizing information per domain into units called records. Records come in different types, and each type answers a different kind of question. Here we'll focus on the three that come up most often.

A records — a hostname pointing straight at an IPv4 address

The A record is the most basic type: it maps a hostname (say, wpmm.jp) directly to a specific IPv4 address. It's a simple map — "traffic to this domain should go to this IP." When you stand up a new web server and want to serve it from a custom domain, an A record is typically the first thing you configure.

CNAME records — a hostname pointing at another hostname

A CNAME (Canonical Name) record treats one hostname as an alias for another. Instead of pointing directly at an IP address, it says "the real content for this name lives over there, at that other hostname" — an indirect reference, unlike the direct one an A record gives you. CNAME comes with a few constraints worth knowing. The most important: a name that has a CNAME record can't also carry other record types (like MX or TXT) at the same time, because a CNAME forwards every query for that name wholesale. It also can't be placed at a zone apex (the bare domain itself, like wpmm.jp with no subdomain) — an A record is the usual choice there instead.

TXT records — arbitrary text attached to a name

A TXT record attaches an arbitrary text string to a domain, rather than an IP address or another hostname. It started out as a place for human-readable notes, but today it's almost entirely consumed by machines. Two common uses: proving ownership of a domain to an external service (the service issues a random string, you add it as a TXT record, and that proves you control the DNS for that domain), and email authentication configuration.

Example 1: standing up a subdomain starts with an A record

When we set up our English blog at the subdomain en.wpmm.jp, the first step was creating that subdomain in the hosting panel and pointing it at a document root. Behind the scenes, that action adds an A record for the new hostname en.wpmm.jp (or configures the hosting provider's authoritative DNS to resolve it implicitly) — and it takes some time for that change to reach DNS caches around the world, commonly called "propagation." That delay has a very practical consequence: try to install WordPress on the new subdomain immediately after creating it, and a connection attempt from an environment still holding a stale cache entry can fail outright. Right after a DNS change, it's worth confirming through a separate path — a dig lookup, or checking against a different resolver — that the change has actually propagated, before moving on to the next step. It saves time that would otherwise go into chasing a mysterious error.

Example 2: email deliverability comes down to a set of three TXT records

When we investigated why our confirmation emails weren't reliably reaching Gmail and Outlook inboxes, the fix that actually mattered was adding a TXT record. Email authentication rests on three mechanisms — SPF, DKIM, and DMARC — and all three are published as TXT records. SPF lists which servers are allowed to send mail on behalf of a domain. DKIM attaches a cryptographic signature to a message so a recipient can verify it wasn't tampered with in transit. DMARC declares a policy for what to do when SPF and/or DKIM checks fail, and where to send reports about those results. Our domain already had SPF and DKIM configured; DMARC was the one missing piece. Adding a TXT record at the hostname _dmarc.wpmm.jp:

v=DMARC1; p=none; rua=mailto:info@wpmm.jp

completed the set of three, and deliverability to major overseas mail providers improved. (p=none is the loosest possible policy — it means "don't reject or quarantine mail that fails authentication, just send a summary report" — a deliberate way to observe before escalating to something stricter like p=reject.) We go into more detail on how SPF, DKIM, and DMARC divide the work in our earlier post on this exact fix, if you want the fuller picture.

Takeaway

An A record answers "what IP does this name point to." A CNAME answers "what other name does this name point to." A TXT record answers "what arbitrary text is attached to this name." Each type is answering a genuinely different question. In practice, the part that trips people up isn't the meaning of the record itself — it's the time lag between making a change and that change actually taking effect anywhere it's queried from. For anything involving multiple steps, like standing up a subdomain or wiring up email authentication, confirming that a DNS change has actually propagated before moving to the next step tends to be the faster path, not the slower one.

pip Version Specifiers — What `==`, `>=`, and `~=` Actually Commit You To

Susumu Takahashi — Tue, 29 Sep 2026 00:52:54 +0000

Anyone who has written a requirements.txt file has probably paused at the line after the package name. Leave it blank, pin it with ==3.0.0, set a floor with >=3.0.0, or split the difference with ~=3.0.0 — they look similar, but each one makes a completely different promise about what gets installed in the future. This post walks through pip's version specifier syntax, then looks at why our own tool's requirements.txt picked one particular style, and what that choice trades away.

The question a version specifier is answering

Note: pip's version specifiers follow PEP 440. Writing an operator and a version number after a package name tells pip which range of versions is acceptable to install.

Leave the specifier off entirely, and pip installs whatever the latest release happens to be at install time. That's a statement of "any current version is fine" — but running pip install against the same requirements.txt six months later will pull in whatever the ecosystem has moved on to by then. Version specifiers exist to put a boundary around that uncertainty: how much freedom do you want to give the installer over what "the future" is allowed to look like?

The main operators, compared

Syntax	Meaning
`==3.0.0`	Only this exact version is allowed (fully pinned)
`>=3.0.0`	This version or newer — a floor only
`<3.0.0`	Only versions below this — a ceiling only
`!=3.0.0`	Any version except this one
`~=3.0.0`	3.0.0 or newer, but below 3.1.0 (the "compatible release" operator)

The one that trips people up most is ~=. ~=3.0.0 is shorthand for >=3.0.0, ==3.0.* — it accepts patch-level updates (the third number) but locks out the moment the minor version (the second number) ticks up. Truncate it to ~=3.0 instead, and the tolerance widens to accept minor updates too, becoming the equivalent of >=3.0, ==3.*. How many digits you write changes the granularity of what's allowed — that's the real difference from a plain >=.

Why our own requirements.txt uses `>=`

Our desktop maintenance tool's requirements.txt specifies all six dependencies with a lower bound only:

flask>=3.0.0
fabric>=3.2.0
playwright>=1.40.0
cryptography>=41.0.0
Pillow>=10.0.0
certifi>=2024.0.0

We chose >= over a full == pin so that security and bug fixes in newer releases get picked up automatically. That matters especially for cryptography (crypto primitives) and certifi (the CA certificate bundle), both of which receive periodic vulnerability fixes and root-certificate updates — pinning either one indefinitely to an old version is itself a risk. Leaving off an upper bound follows the same logic: nothing rules out a future release before it exists.

What `>=` gives up in exchange — build reproducibility

The trade-off shows up at build time. This tool is packaged into a distributable binary with arch -x86_64 pip3 install -r requirements.txt && arch -x86_64 python3 build_app.py, using PyInstaller. Run that exact command twice, weeks apart, without touching requirements.txt at all, and pip resolves "3.0.0 or newer" fresh each time — so the two builds can end up bundling genuinely different versions of flask or cryptography. Looking at a diff of requirements.txt alone can't tell you whether two builds actually shipped with the same dependency set.

That uncertainty becomes a real problem when a bug only reproduces on one specific dependency version, or when a minor-version bump quietly changes behavior — a deprecation warning gets promoted to a hard error, a default value flips — and it slips into a build unnoticed because nothing in the repo changed. Full == pinning would turn "update a dependency" into a deliberate, tested step. With >=, the update timing is implicitly decided the moment someone runs pip install.

Projects that need strict reproducibility typically solve this with a two-tier setup: keep the loose requirements.txt for expressing intent, but also generate a lock file from pip freeze that every routine install actually reads from, regenerating it only when a dependency bump is deliberate. Our tool runs with a small team and a mostly static build environment, and dependency updates are infrequent enough that we haven't introduced that second tier — we run on >= alone for now. If the build environment grows, or subtle version drift between builds starts causing real problems, a lock file is the natural next step.

Takeaway

==, >=, and ~= are all answers to the same underlying question: how much should the future version be allowed to drift from what you tested against? == maximizes reproducibility at the cost of manual updates; >= picks up updates automatically at the cost of no longer being able to tell, from the requirements file alone, exactly what's installed right now. We picked >= mainly to avoid missing updates to crypto- and certificate-related packages — but that choice is inseparable from accepting a lower bar on reproducibility. Which operator you reach for is really a design decision about whether your project values staying current or staying reproducible more.

Cache-Control vs. ETag: What Each One Actually Controls

Susumu Takahashi — Sun, 27 Sep 2026 23:18:11 +0000

Open a browser's network tab and you'll see Cache-Control and ETag sitting on the response headers of nearly every image, stylesheet, and script. Most developers recognize both names, but far fewer could explain how they actually divide the work of caching between them. This post walks through the basics of HTTP caching, then looks at how this project's own OGP image generator uses one of these headers and deliberately skips the other.

The Problem These Headers Solve

Note: HTTP caching lets a browser (or a CDN in between) hold on to a response it already fetched — an image, a stylesheet, a script — and reuse it on the next request for the same URL instead of asking the server again.

Without any instructions from the server, a browser has to guess whether a cached response is still safe to reuse, and that guess tends to be inconsistent across browsers and situations. Cache-Control and ETag exist to remove the guesswork by having the server state its intent explicitly. But they answer two different questions: Cache-Control answers "how long can you skip asking me entirely?" and ETag answers "once that period is over, how can you cheaply check whether anything actually changed?"

What Cache-Control Controls

Cache-Control sets an expiration window. This project's blog theme includes ogp-generator.php, which renders an OGP preview image with PHP's GD library for any post that has no featured image set. When it serves the generated PNG, it attaches:

header('Content-Type: image/png');
header('Content-Length: ' . filesize($file));
header('Cache-Control: public, max-age=2592000, immutable');

Each directive does something distinct:

public — this response can be cached not just by the requesting browser but by any shared cache along the way, such as a CDN. (A response with per-user content, like a personal dashboard, would use private instead.)
max-age=2592000 — the number of seconds the cache is considered fresh. 2,592,000 seconds is exactly 30 days; for that entire window, a browser revisiting the same URL never contacts the server at all.
immutable — a declaration that the content will not change for the duration of max-age. With this set, the browser skips even the lightweight revalidation check described below on a page reload — it just uses the cached copy, no questions asked.

Pairing a 30-day window with immutable only makes sense if "this exact URL will never point to different content" genuinely holds. How that guarantee gets built is the interesting part.

What ETag Controls — Checking In After Expiration

Once max-age expires, a browser doesn't simply throw the cached copy away — it asks the server whether the old copy is still good. ETag (short for Entity Tag) is what makes that check cheap.

Note: an ETag is a short identifier — usually a hash — generated from a response's actual content. If even a single byte of the content changes, the ETag changes with it, making it effectively a fingerprint of the content.

The revalidation flow looks like this:

The server's first response includes something like ETag: "abc123".
The browser remembers that value, and once the cached copy has expired, it sends a follow-up request carrying If-None-Match: "abc123".
The server recomputes the content's current ETag. If it hasn't changed, it replies with 304 Not Modified — a lightweight response with no body.
The browser sees the 304 and keeps using its existing cached copy.

The key detail is that a 304 Not Modified response never re-transmits the actual image or file — the server still has to do the work of recomputing whether the content changed, but the network transfer itself is skipped. Where max-age is a blunt instrument ("skip checking entirely for this long"), ETag is a finer one ("even after the window closes, skip re-downloading if nothing actually changed").

Why ogp-generator.php Doesn't Use ETag

Given the above, it might seem like ogp-generator.php is missing something by not implementing ETag. Looking at the actual code shows the opposite: the design makes revalidation unnecessary in the first place.

$modkey  = get_post_modified_time('YmdHis', true, $post); // GMT-based
$cache_file = $cache_dir . "/post-{$post_id}-{$lang}-{$modkey}.png";

The generated filename bakes in the post ID, the language, and the post's last-modified timestamp. When a post is edited and post_modified changes, the resulting PNG's filename — and therefore its URL — changes along with it. This is a technique commonly called cache busting: instead of asking "has this URL's content changed?", the system makes sure a given URL's content can never change in the first place, because any real change produces a different URL.

Under that design, there's nothing for ETag to check — a given URL is guaranteed, by its own structure, to point at content that was frozen the moment it was generated. That guarantee is exactly what makes it safe to attach immutable. If the generator instead reused the same filename after a post's title changed, immutable would be lying to the browser, and editors would see stale OGP images persist for up to 30 days after every edit.

Both approaches solve the same underlying problem — keeping a cache from serving stale content — but from opposite directions. ETag accepts that the URL stays fixed and pays a small revalidation cost on every expiration cycle to confirm freshness. Baking a version into the URL itself avoids that round trip entirely, at the cost of only working cleanly when there's a reliable signal (here, post_modified) to version against. Which approach fits depends on how often, and at what granularity, the underlying content actually changes.

Takeaway

Cache-Control and ETag both exist to control caching, but they control different parts of it. Cache-Control's max-age controls how long a browser can skip contacting the server entirely. ETag controls how cheaply the server and browser can confirm, once that window closes, whether the content has genuinely changed. Baking a content version into the URL itself — as ogp-generator.php does with a post's modification timestamp — sidesteps the need for ETag altogether, making a long max-age with immutable safe rather than reckless. Whichever strategy is used, the caching logic is only as trustworthy as the assumption it's built on about when the underlying content actually changes.

Exponential Backoff vs. Fixed-Interval Retries: When Growing Wait Times Actually Help

Susumu Takahashi — Sat, 26 Sep 2026 00:26:28 +0000

How to retry a failed operation is a design question every network-facing piece of code eventually has to answer. The textbook technique is exponential backoff — doubling the wait time on each retry — but it isn't automatically the right answer everywhere. This post works through what problem exponential backoff actually solves, then looks at three real retry paths in this app's own code where fixed intervals were chosen instead, and why.

The Problem Exponential Backoff Solves

Note: exponential backoff is a retry strategy where the wait time between attempts grows exponentially — 1s, 2s, 4s, 8s, and so on — instead of staying constant.

base = 1
for attempt in range(6):
    delay = base * (2 ** attempt)
    print(f"attempt {attempt}: wait {delay}s")
# attempt 0: wait 1s
# attempt 1: wait 2s
# attempt 2: wait 4s
# attempt 3: wait 8s
# attempt 4: wait 16s
# attempt 5: wait 32s

Exponential backoff earns its keep in one specific situation: many independent clients retrying against the same shared resource at once. When a server starts failing under load, and every client retries at a fixed interval, the retries arrive in synchronized waves that keep hitting the already-struggling server at the same cadence — a pattern often called a "thundering herd." Spacing each client's retries out exponentially means those waves drift apart over time, giving the server room to recover. That's why most HTTP client libraries and cloud SDKs ship exponential backoff by default.

The flip side is that this only pays off when many independent clients are actually contending for the same resource. Where that condition doesn't hold, exponential backoff adds complexity without buying anything. Here are three retry sites in this codebase where it was deliberately skipped.

Example 1: A Single Fixed Retry for HTTP Checks

This app checks a site's HTTP status before and after WordPress updates, rolling back if things got worse. The core of that logic is maintenance_agent.py::_http_status_check_stable():

def _http_status_check_stable(url, timeout=15, retry_delay=3, basic_auth=None):
    status = _http_status_check(url, timeout=timeout, basic_auth=basic_auth)
    if status == 0:
        try:
            import time as _time
            _time.sleep(retry_delay)
        except Exception:
            pass
        status = _http_status_check(url, timeout=timeout, basic_auth=basic_auth)
    return status

Only status == 0 (a failure before the response even reaches the server — DNS blip, TLS handshake failure, a momentary connection drop) triggers a retry, and it's exactly one retry after a flat 3-second wait. A 5xx response isn't retried at all — once a response actually comes back, the code treats that as a genuine server-side problem rather than a transient network hiccup.

There's no exponential growth anywhere in this function, and the reason is in a comment elsewhere in the same file: this function gets called from up to five different call sites for a single site during one maintenance run — a baseline check, a post-core-update check, post-rollback checks, and a check after each individual plugin update. On a site with twenty plugins, that call count adds up fast. If each of those calls retried multiple times with growing delays, the total time a single site's maintenance run could take would become unpredictable, which matters a lot for an unattended scheduled run where per-site duration needs to stay roughly bounded. Telling apart "a momentary blip" from "a genuinely down server" doesn't require patiently waiting longer and longer — one fixed retry is enough.

Example 2: Polling for a File Lock at a Fixed Interval

Two processes in this app — the GUI web server and a background maintenance run launched as a separate process — can both try to write the same config file (sites_*.json etc.) at once. core/file_lock.py::FileLock prevents that collision:

def acquire(self) -> None:
    deadline = time.monotonic() + self.timeout
    while True:
        if self._try_acquire_once():
            return
        if time.monotonic() >= deadline:
            raise FileLockTimeout(
                f"Failed to acquire lock within {self.timeout}s: {self.lock_path}"
            )
        time.sleep(self.poll_interval)

The defaults are timeout=10.0 and poll_interval=0.1 — it polls every 0.1 seconds until either the lock is acquired or ten seconds pass, with no growth in the interval at all.

Here again, exponential backoff wouldn't fit the actual contention pattern. This lock is contended by, at most, two processes belonging to the same app — not an unbounded number of independent clients — so there's no thundering herd to prevent in the first place. And since the wait is local disk I/O rather than load on a remote server, the cost of polling frequently is just a bit of wasted CPU wake-ups, not risk to a shared resource. Given that, polling at a short fixed interval means the lock gets picked up close to the moment it's released; a growing interval would risk sitting through an unnecessarily long gap right when the lock happens to free up.

Example 3: Retrying by Changing Approach, Not by Waiting

core/ssh_utils.py has a different kind of retry when fetching the plugin list:

res = c.run(
    f"{wp_with_plugins} plugin list --update=available --format=json",
    hide=True, warn=True, encoding='utf-8'
)
if not (res.ok and res.stdout.strip()):
    # fall back: retry with all plugins skipped
    res = c.run(
        f"{wp_safe} plugin list --update=available --format=json",
        hide=True, warn=True, encoding='utf-8'
    )

The first attempt runs WP-CLI without --skip-plugins, so any plugin's own update-detection hook can fire. If that fails, the fallback switches immediately — with no delay at all — to a safer command that skips every plugin. This isn't the kind of failure that waiting resolves; the suspected cause is a specific plugin interfering with the command itself, a structural problem rather than a transient one. So the retry axis here isn't "how long to wait" but "which approach to use."

Takeaway

Exponential backoff earns its complexity when many independent clients might hammer the same resource at once, spreading out the resulting wave of retries so an overloaded server gets room to recover — a solid default for calls to external APIs and cloud services. But when the retry count is inherently small (one HTTP recheck), when contention is limited to a couple of processes on the same machine (a local file lock), or when the failure isn't the kind that time alone fixes (switching strategy instead of retrying the same command), fixed intervals — or no delay at all — are simpler and don't leave anything on the table. The question worth asking before reaching for backoff isn't "how should the wait time grow," but "what's actually contending for what, and would waiting longer even help."

Why SSH Key Authentication Beats Password Authentication — What Is Actually Being Proven

Susumu Takahashi — Thu, 24 Sep 2026 23:48:45 +0000

"Use key-based auth instead of a password" is common advice for connecting to a server over SSH. But what exactly does key authentication prove, and how does that differ from what a password proves? This post works through the mechanics of what each method is actually demonstrating.

Authentication is an act of proof

Note: authentication is the process of confirming that whoever just connected really is who they claim to be, based on some kind of evidence. It's often confused with authorization, which is a separate concept covering what a confirmed identity is then allowed to do.

Every authentication scheme ultimately comes down to a choice: what evidence counts as proof of identity? Password authentication and public-key authentication answer that question in fundamentally different ways.

Password authentication: proving you know a secret by stating it

Password authentication is structurally simple. Client and server both know the same secret in advance. The client sends that secret to the server, the server compares it (usually after hashing) against its own stored record, and a match means "authenticated."

The weakness lives in that structure itself: the secret gets stated, directly, as part of the exchange. SSH's transport is encrypted, so eavesdropping isn't the main concern — the problems lie elsewhere:

Passwords people can actually remember tend to have far lower entropy than machine-generated random values, which makes them susceptible to dictionary and brute-force attacks
Reusing the same password across services turns one leak into an entry point for every other server that shares it (credential stuffing)
If the value stored server-side (a hash) ever leaks, it opens the door to offline brute-forcing

In short, password authentication proves "I know the secret" by transmitting the secret — or a value derived directly from it.

Public-key authentication: proving possession without ever handing over the secret

Public-key authentication proves identity a completely different way, built on asymmetric cryptography — a public/private key pair.

Note: asymmetric cryptography uses two mathematically linked but distinct keys: a private key for signing or decrypting, and a public key for verifying or encrypting. Deriving one key from the other is designed to be computationally infeasible.

Only the public key gets registered on the server ahead of time. The private key never leaves the client machine. During authentication, the server sends a random challenge value; the client signs it with the private key and sends the signature back. The server verifies that signature using the registered public key — a valid signature is proof that the client holds the matching private key, without the private key itself ever being transmitted.

That's the decisive difference. Password authentication sends the secret itself over the wire. Public-key authentication only ever sends proof of possession (a signature), and by design, that proof can't be reverse-engineered back into the private key.

What happens if server-side data leaks

The difference becomes stark when you consider what a leak of server-side authentication data actually costs.

With password authentication, what the server stores is a password hash. If that hash leaks, an attacker can brute-force it offline — and a weak password will eventually fall.

With public-key authentication, what the server stores is the public key itself — information that's meant to be public by definition. A leak of that data costs nothing, because there was never a secret sitting on the server side to begin with. Not putting anything secret on the server is the core of why public-key authentication is safer.

A real example: narrowing authentication down to one explicit key

This app's SSH connection code (core/ssh_utils.py::get_ssh_connection()) doesn't just use public-key authentication — it also deliberately narrows which key gets tried.

connect_kwargs = {'look_for_keys': False, 'allow_agent': False}
if 'ssh_key_path' in site and site['ssh_key_path']:
    ...
    pkey = load_any_ssh_key(key_path, passphrase=ssh_passphrase)
    connect_kwargs['pkey'] = pkey

return Connection(
    host=site['ssh_host'],
    user=site['ssh_user'],
    port=site.get('ssh_port', 22),
    connect_timeout=15,
    connect_kwargs=connect_kwargs
)

look_for_keys=False and allow_agent=False turn off the SSH client library's (paramiko's) default behavior of trying every key under ~/.ssh/ and every key registered in a running SSH agent. Only the one key specified in that site's configuration is passed in explicitly via pkey.

This isn't a matter of taste. In an environment managing many sites, leaving automatic key discovery on means a single connection attempt can end up trying several candidate keys back to back — quickly running into OpenSSH's MaxAuthTries limit (6 by default). If the server side has protection like fail2ban or OpenSSH's PerSourcePenalties, a legitimate administrator can end up temporarily blocking their own IP by accident. Pinning "this connection uses exactly this one key" isn't about the strength of authentication itself — it's a structural fix for a pitfall specific to managing many sites at once.

Turning password login off entirely, server-side

Beyond using key auth on the client, it's also standard practice to set PasswordAuthentication no in sshd_config, so the server won't even accept password login attempts. That's a well-documented, standard OpenSSH setting — not some private operational trick — and it follows a simple principle: eliminate the weaker authentication path rather than just discouraging its use. No matter how strong a key is, if the same account can still be reached with a password, that's where an attacker will aim.

How this connects to choosing a key type

An earlier post, SSH Key Types: RSA vs. ED25519 vs. ECDSA — Which Should You Use?, covered which key algorithm to pick once you're using public-key authentication. This post is one layer earlier in that decision: why choose public-key authentication over a password in the first place. Picking a key algorithm is a decision that only comes up after you've already committed to that approach.

Summary

Password authentication proves "I know the secret" by transmitting the secret itself. Public-key authentication proves the same kind of claim — "I am who I say I am" — by transmitting only proof of possession, never the private key. That difference directly shapes the blast radius of a server-side data leak: a leaked password hash is a starting point for an attacker, while a leaked public key is worthless to one, because it was never secret to begin with. Keeping nothing secret on the server side is the most fundamental reason SSH key authentication is recommended over passwords.

Unit Tests vs. Regression Tests: Why the Same Feature Gets Tested Twice

Susumu Takahashi — Thu, 24 Sep 2026 00:54:59 +0000

Look through a maintenance tool's test suite long enough and you'll run into a small puzzle: a function already has a test, so why does another file add a second one for what looks like the same behavior? Two tests that appear to cover the same ground can actually exist for entirely different reasons.

This post walks through the distinction between "unit tests" and "regression tests," using real test code from this project as the example.

Unit tests: verifying a function in isolation

Note: a unit test checks the smallest testable piece of a program — a function, class, or method — independently from the rest of the system.

A unit test's job is simple: feed a function a range of plausible inputs and confirm the output matches expectations. It's naturally written right alongside the implementation, or shortly after.

Take the helper functions that diagnose and fix SSH private key permission issues:

class TestIsPermissionError(unittest.TestCase):
    def test_openssh_too_open(self):
        msg = "Permissions 0644 for '/Users/x/.ssh/id_rsa' are too open."
        self.assertTrue(key_perms.is_permission_error(msg))

    def test_windows_openssh(self):
        msg = "Permissions on the private key file 'C:\\Users\\x\\.ssh\\key' are too open."
        self.assertTrue(key_perms.is_permission_error(msg))

    def test_case_insensitive(self):
        self.assertTrue(key_perms.is_permission_error("ARE TOO OPEN"))

Each test method feeds is_permission_error() a different plausible input — a typical OpenSSH message, the Windows-flavored wording, a case variation — and checks the return value. The POSIX (Mac/Linux) side runs real chmod calls; the Windows icacls path is mocked out since it can't run in this CI environment.

The question this test is asking is: "does this function behave as designed?" It verifies a contract, and it can be written the moment the function exists, independent of anything that happens later in production.

Regression tests: sealing off an incident that already happened

Note: "regression" means slipping backward. A regression test checks that a bug fixed in the past hasn't quietly come back with a later code change.

Regression tests are a different animal. They aren't triggered by "let's verify the spec" — they're triggered by "this actually broke, in a real environment, once."

Here's an incident from development on v1.6.11. A pre-build version-consistency script (tools/bump_version.py) printed a success message containing an emoji (✅). On Mac, the console defaults to UTF-8, so nothing ever went wrong there. But on Windows with a Japanese locale, when this script ran as a subprocess with its output piped, Python defaulted to the locale encoding (cp932) — which can't represent that emoji — and the script crashed with a UnicodeEncodeError. Worse, the caller (build_app.py) misreported that crash as a "version mismatch," making the real cause harder to trace.

That incident produced tests/test_windows_cp932_safety.py, built as two layers:

Layer 1 (static check): scan the source of any script that runs as a subprocess during build/release, character by character, and confirm nothing in it fails to encode as cp932.

CP932_CRITICAL_SCRIPTS = [
    "tools/bump_version.py",
]

def test_critical_scripts_are_fully_cp932_encodable(self):
    for rel in CP932_CRITICAL_SCRIPTS:
        with open(os.path.join(ROOT, rel), encoding="utf-8") as f:
            text = f.read()
        for ch in text:
            try:
                ch.encode("cp932")
            except UnicodeEncodeError:
                ...  # record the failure

Layer 2 (behavioral check): actually run the target script as a child process with PYTHONIOENCODING=cp932 set, and confirm it exits cleanly (return code 0) without raising UnicodeEncodeError. A static character scan alone can't guarantee the script won't crash at runtime, so the behavior itself gets checked separately.

The question this test asks isn't "is this function correct?" — it's "has that specific incident happened again?" The function itself was already fixed by the time this test was written, and the behavioral layer confirms the fix works. The reason this test stays in the suite indefinitely is to catch a future edit that quietly reintroduces an emoji into an output message.

Why a "correct" function still broke

The bump_version.py emoji output wasn't a logic bug in isolation — printing a checkmark on success did exactly what it was supposed to do. The problem lived in an assumption about which environment, and by what path, that output would be read.

A unit test verifies a function's contract in the abstract: given this input, does it return that? Looked at on its own, the emoji output passes such a test easily. The failure only surfaces when three conditions line up at once — a specific locale (cp932), output flowing through a pipe, and the call happening from inside a subprocess. No amount of exhaustively unit-testing the function's normal logic would have caught that combination.

That's exactly why an incident that actually happened, across environments, gets frozen into an automated test rather than left as a lesson learned once and then forgotten.

What the test filenames themselves signal

This repository's test suite includes files like test_stability_v47.py and test_db_backup_v48.py, named after internal development round numbers. The header of test_db_backup_v48.py reads, in part:

Issue #299 (fixed 2026-04-24): regression guard for the
os.path.join(local_site_backup_dir, backup_file) bug — backup_file had
become a remote absolute path, so the second argument was treated as
absolute and the first argument was discarded entirely.

os.path.join() has a documented behavior: if a later argument is an absolute path, everything before it is discarded and only that absolute path is returned. That's not a bug — it's the documented contract. The actual incident was that the calling code assumed the string it passed in would always be a relative filename, when in practice a remote absolute path made it through, silently discarding the intended local backup directory.

A test carrying an issue number or round number in its filename or header comment is a signal that it exists to guard against a specific past incident, not to exercise the general behavior of a module. By contrast, a file named purely after the module it covers — like test_key_perms.py — is a unit test aimed at verifying that module's spec.

The connection to visual regression testing

An earlier post on this blog, What Is Visual Regression Testing? How Screenshot Diffing Catches Layout Breaks, covers a variant of this same idea. That post froze "has the layout broken" into a pixel-comparison check; the cp932 example here freezes "has a specific piece of logic broken under a specific environment" into a code-execution check. The verification mechanism differs — image diffing versus running a script — but the underlying design is the same: take an incident that already happened once, and turn it into something that can be re-checked automatically, indefinitely.

Summary

Unit tests confirm that a function or module behaves according to spec, written around the same time as the implementation. Regression tests exist to make sure an incident that already happened once, in a real environment, doesn't quietly happen again after a future code change — and they're written after the fact. Both take the shape of "a test," but they're born at different moments and serve different purposes. When a test suite has multiple files touching what looks like the same feature, it's often carrying two distinct kinds of intent at once: verifying a spec, and remembering an incident.

How Desktop Apps Detect and Kill Stale Processes on Startup

Susumu Takahashi — Tue, 22 Sep 2026 01:16:42 +0000

You close a desktop app, but its process is still sitting there in the task manager or Activity Monitor. Many people have run into this. This article looks at the design behind a common fix: detecting a leftover process from a previous run at startup, cleaning it up safely, and only then starting fresh.

Why a Process Can Fail to Exit

A Python desktop app built with a Flask backend and a browser as its display, packaged into a single executable with PyInstaller, often relies on a hard-exit call like os._exit(0) to shut down. The catch: calling this from a background daemon thread doesn't always terminate the process in a frozen (packaged) build. From the user's point of view, they clicked "quit," but the process kept running behind the scenes.

Note: a daemon thread is one that gets forcibly terminated when the main thread exits. It's commonly used for background work, but calling os._exit() from inside one doesn't guarantee the whole process actually terminates.

A leftover process like this causes trouble the next time the app is launched — the port it was using is still occupied, or two instances end up running and conflicting with each other.

Separating "the PID is alive" from "the port is responding"

This app writes the running instance's information to a port file (app_running.port) as port\nPID. On the next launch, it reads this file and checks whether the recorded PID is actually still alive.

def _is_pid_alive(pid: int) -> bool:
    """Check whether a PID is alive (macOS/Windows)"""
    if sys.platform == 'win32':
        try:
            import ctypes
            kernel32 = ctypes.windll.kernel32
            SYNCHRONIZE = 0x00100000
            handle = kernel32.OpenProcess(SYNCHRONIZE, False, pid)
            if handle:
                kernel32.CloseHandle(handle)
                return True
            return False
        except Exception:
            return False
    else:
        try:
            os.kill(pid, 0)
            return True
        except (OSError, ProcessLookupError):
            return False

What's worth noting here is that checking whether a process is alive works completely differently on Unix-like systems versus Windows. On Unix-like systems, os.kill(pid, 0) sends signal number 0 — which, per the POSIX spec, doesn't actually deliver a signal at all. It's a special case that only performs permission and existence checks. A nonexistent PID raises ProcessLookupError (a subclass of OSError). Windows has no equivalent to signal 0, so the check instead tries to obtain a process handle via OpenProcess() and treats success or failure as the liveness result.

But "the PID is alive" and "the process is working correctly" aren't the same thing, and that distinction is the core of this design. A process can be alive while its main loop is hung or its listening socket has stopped responding — from the outside, that's indistinguishable from an unresponsive zombie. So beyond checking whether the PID exists, the code also checks whether the recorded port actually accepts a connection.

def _kill_stale_process():
    port, pid = _read_port_file()
    if pid is None:
        return
    if not _is_pid_alive(pid):
        # Process already exited, only the port file is left behind — clean up only
        _cleanup_instance_files()
        return
    # Process is alive but the port doesn't respond — treat it as a zombie
    is_listening = False
    if port is not None:
        try:
            with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
                s.settimeout(1.0)
                is_listening = s.connect_ex(('127.0.0.1', port)) == 0
        except Exception:
            pass
    if not is_listening:
        _force_kill_pid(pid)
        _cleanup_instance_files()
    # if is_listening=True (running normally), leave the port file alone

This function splits the port file's state into three cases at startup:

The PID is already dead: the process already exited, cleanly or otherwise. Only the leftover port file needs cleaning up.
The PID is alive but the port doesn't respond: the process is still around but isn't doing its job — a zombie. This is the case that gets force-killed.
The PID is alive and the port responds: a genuinely running instance. Nothing happens here, and the port file is left untouched.

Misclassifying case 3 as "an old process" and killing it would take down a healthy instance the user never asked to stop. Not stopping at a liveness check, and going one step further to confirm the process is actually serving requests, is a deliberate second layer meant to avoid exactly that kind of false positive.

Force-killing also differs by OS

Just like the liveness check, the mechanism for force-killing a process differs by platform.

def _force_kill_pid(pid: int):
    """Force-kill a PID (macOS/Windows)"""
    if sys.platform == 'win32':
        try:
            subprocess.run(
                ['taskkill', '/F', '/PID', str(pid)],
                stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=5,
                creationflags=subprocess.CREATE_NO_WINDOW
            )
        except Exception:
            pass
    else:
        try:
            os.kill(pid, signal.SIGKILL)
        except Exception:
            pass

On Unix-like systems, this sends SIGKILL. That signal can't be caught or ignored by the target process — it's a kernel-level termination, which is exactly what's needed for a zombie process whose normal signal handlers may not even be functioning anymore. Windows has no direct equivalent, so the code shells out to taskkill /F instead.

macOS has its own reactivation quirk

Everything above is about cleaning up after a process that failed to exit properly. macOS adds a separate wrinkle on top of that: clicking an already-running app's icon in the Dock or Finder doesn't launch a new process at all — it just "activates" (brings to the front) the existing one. That's standard macOS behavior across the board, but it's not automatically convenient for an app built around a Flask backend plus a browser front end.

In a frozen build running on macOS, when this app detects an existing instance already running, it requests a graceful shutdown (waiting for any maintenance operation in progress to finish), sends SIGTERM, waits up to 15 seconds, and falls back to SIGKILL if the process is still alive — only then does it start up again as a new process. Without this, simply reactivating the existing instance wouldn't reflect what the user actually wants when they double-click the app expecting a fresh launch.

A different problem: the browser tab closes, the server doesn't

Separate from detecting and killing stale processes at startup, this app also handles a different kind of leftover-process problem: what happens when the browser tab is closed but the server process keeps running. The browser sends a request to /api/heartbeat every 30 seconds, and if the server hasn't received one in 60 seconds — and no maintenance operation is in progress — it sends itself SIGKILL and exits.

This mechanism serves a different purpose and fires at a different time than the startup-time stale-process check. Heartbeat monitoring answers "how does a running process realize it's been abandoned by the user," while _kill_stale_process answers "how does a newly starting process clean up the wreckage of a previous one." They can look like the same category of problem — process cleanup — but they differ in who's doing the detecting (the running process itself, versus the next process about to start) and when it happens (continuous monitoring, versus a one-time check at launch).

Summary

Point	Takeaway
Checking if a PID is alive	Unix-like systems use `os.kill(pid, 0)`; Windows uses `OpenProcess()` — the mechanism differs by OS
"Alive" vs. "actually working"	Checking whether the port responds, not just whether the PID exists, avoids killing a healthy instance by mistake
Force-killing	`SIGKILL` on Unix-like systems, `taskkill /F` on Windows
macOS reactivation	Because Dock/Finder won't launch a new process for a running app, the old one has to be explicitly terminated before starting fresh
vs. heartbeat monitoring	Startup cleanup and abandonment detection solve different problems on different timelines

Something as seemingly simple as "terminate a process" turns out to involve several stacked decisions: platform-specific ways to check whether something is alive, a multi-step check to avoid killing a healthy process by accident, and handling for platform-specific quirks like macOS reactivation.

Semantic Versioning (SemVer): Why Version Numbers Have Three Parts

Susumu Takahashi — Sun, 20 Sep 2026 23:40:15 +0000

Most software version numbers look like 1.6.11 — three numbers separated by dots. This isn't an arbitrary naming choice; it follows a widely adopted convention called Semantic Versioning, or SemVer. This article looks at why version numbers are split into three parts, and what it actually takes to implement that convention correctly in code.

What MAJOR.MINOR.PATCH Each Mean

SemVer formats a version as MAJOR.MINOR.PATCH (for example, 1.6.11), and each position carries a distinct meaning:

MAJOR: incremented when you make a breaking change — something that could stop existing usage from working
MINOR: incremented when you add functionality in a backward-compatible way — existing usage keeps working
PATCH: incremented when you fix a bug in a backward-compatible way — no behavior-breaking side effects

Note: "backward-compatible" means code or usage written for an older version keeps working on the newer one. A breaking change is one where something that used to work stops working after the update.

What matters here is that these three numbers aren't just a sequential counter — each position is assigned a specific meaning. Just by glancing at a version number, you can get a rough sense of whether an update is likely safe to apply immediately or whether it deserves a closer look first.

Why a Single Incrementing Number Isn't Enough

Imagine version numbers were just a plain sequence: v1, v2, v3, and so on. Looking at a single number like that tells you nothing about whether the change behind it was a minor fix or a major overhaul. Users would have to read the release notes every single time just to figure out whether it's safe to upgrade — the number itself carries almost no information.

Splitting the version into MAJOR.MINOR.PATCH is a way to make the number itself carry meaning. If only the PATCH digit moved, you can generally trust it's safe to apply right away. If MAJOR moved, that's a signal to check what changed before upgrading. The structure of the number becomes a form of communication in itself.

Why Version Comparisons Need to Be Numeric

This app stores its current version as VERSION = "1.6.11" in version.py, and compares it against the latest version published on the update server at startup to decide whether an update is available. This comparison step hides a classic pitfall that's easy to overlook when working with SemVer.

def _is_newer(remote_version, current_version):
    """Compare versions using semantic versioning (X.Y.Z)"""
    try:
        remote = tuple(int(x) for x in remote_version.strip().split('.'))
        current = tuple(int(x) for x in current_version.strip().split('.'))
        return remote > current
    except (ValueError, AttributeError):
        return False

If this comparison were done as a plain string comparison ("1.10.0" > "1.9.0"), the result would actually come out wrong. Python's string comparison walks character by character in lexicographic order, so "1.10.0" ends up evaluated as smaller than "1.9.0" — the first character 1 matches, but at the second character it's comparing . against ., then 1 against 9, and 1 sorts before 9. Numerically, 1.10.0 is the newer version, but a naive string comparison gets it backwards.

_is_newer avoids this by splitting each version string on the dot, converting each segment to an integer with int(), and comparing the resulting tuples. Tuple comparison in Python evaluates elements left to right as numbers, so (1, 10, 0) > (1, 9, 0) correctly evaluates to True. Only by treating each of the three parts as an independent number — rather than as characters in a string — does the version ordering actually match its intended meaning. The visual ordering of the string and the semantic ordering of "which version is newer" are not always the same thing, and that distinction is the whole point of this design.

A Version Number Doesn't Live in Just One Place

There's a second practical challenge in applying SemVer in a real project: the version string rarely lives in just one file. It typically ends up duplicated across the installer configuration, a metadata file on the distribution server, and filenames referenced in download links. In this app, beyond version.py itself, the version string is also embedded separately in the installer-generation config, a distribution metadata file, and the download page's link text.

Keeping all of these in sync by hand is a standing risk — it's easy to forget one. This project actually hit that exact problem once: the installer configuration was left un-bumped while every other file moved forward, so the installer that got built still carried the old version number. To close that gap, we built a script that lists every file that needs updating and bumps them all together, plus a --check mode that verifies every file's embedded version string actually matches the single source of truth in version.py.

python tools/bump_version.py 1.6.11 2026-06-11   # bump every target file at once
python tools/bump_version.py --check              # verify consistency only (exit 1 on mismatch)

--check is wired in as a gate before the build step runs. If any file's version string drifts from what version.py declares, the build stops right there. Rather than relying on someone remembering to check every file by hand, the consistency check runs mechanically, every time.

Summary

Point	Takeaway
MAJOR.MINOR.PATCH split	Each digit encodes whether a change is breaking, additive, or a plain fix
vs. a plain counter	A single incrementing number carries almost no information on its own
The string comparison trap	Lexicographic comparison gets `"1.10.0" < "1.9.0"` wrong
Comparing as tuples	Converting each segment to `int()` and comparing as tuples restores correct ordering
Version numbers, duplicated	Version strings scattered across multiple files need a bump-and-verify script to avoid drift

Semantic Versioning isn't just a naming convention — it's a design choice to make the version number itself a communication tool for whoever is about to upgrade. Actually implementing that idea correctly in code means paying attention to details outside the convention itself, like numeric comparison correctness and keeping duplicated version strings in sync.

How Symmetric Encryption (Fernet) Keeps Local Credentials Safe on Disk

Susumu Takahashi — Sat, 19 Sep 2026 05:16:23 +0000

Desktop apps that talk to servers over SSH or an API often need to remember a password or key between launches. Asking the user to retype it every time isn't realistic, but saving it as plain text in a config file is risky — the moment that file ends up in a backup, a sync folder, or gets shared with someone for debugging, the credential is exposed. This post looks at how symmetric encryption solves that specific problem, using Python's cryptography library and its Fernet recipe as a concrete example.

Note: Symmetric encryption uses the same key for both encrypting and decrypting. That's different from the SSH keys covered in SSH key types (RSA / ED25519 / ECDSA) — what actually differs, and which one to pick, which are asymmetric — a public/private key pair. Asymmetric encryption exists to let two separate parties authenticate or communicate without ever sharing a secret. Symmetric encryption fits a different case: a single program encrypting data now so that the same program can read it back later.

Why symmetric encryption is the right tool here

SSH connections and API calls involve two separate parties — the local machine and a remote server — so a secure way to exchange keys matters, and that's exactly what asymmetric cryptography is built for. Local credential storage is a different problem: the app encrypts its own configuration and later decrypts it for its own use. There's no second party to negotiate a key with. A single key, kept somewhere safe, is enough. Symmetric algorithms are also computationally lighter, which suits this "lock your own box with your own key" use case well.

What Fernet actually bundles together

Fernet, part of Python's cryptography library, packages a set of well-understood primitives into one safe-to-use recipe:

AES (Advanced Encryption Standard) encrypts the payload itself.
HMAC (Hash-based Message Authentication Code) signs the ciphertext so tampering can be detected.
An embedded timestamp records when the token was created, which can later support expiration checks.
URL-safe Base64 encoding turns the whole thing into a printable string that drops cleanly into JSON or a text file.

The important part is that Fernet handles authentication, not just confidentiality. Plain encryption without an integrity check can still be tampered with — an attacker without the key generally can't read the plaintext, but might still be able to flip bits in the ciphertext and corrupt it in a way that goes unnoticed. Fernet's built-in HMAC check catches that: if a token has been altered since it was created, decryption fails outright.

from cryptography.fernet import Fernet

key = Fernet.generate_key()          # 32 random bytes, URL-safe base64 encoded
f = Fernet(key)

token = f.encrypt(b"my-secret-password")   # encrypt -> token
plain = f.decrypt(token)                   # decrypt -> original bytes

Where the key lives, and how not to lose it

The hardest part of using symmetric encryption in practice usually isn't the algorithm — it's key management. Anyone holding the key can decrypt the data, and losing the key makes the encrypted data permanently unreadable. That's a fundamentally different failure mode than a forgotten password, which can just be reset, so persisting the key safely deserves real care.

This app generates a key the first time it runs, and stores it in a hidden file under the user's home directory with permissions restricted to the file's owner. On later launches it reads back the same key. As a safeguard against that file disappearing — accidental deletion, a corrupted profile directory — a second copy of the same key is kept in another location, and at startup both locations are checked so that a missing copy can be restored from whichever one still exists.

# Simplified: try the primary location, fall back to the backup,
# and re-sync whichever copy is missing.
key = load_from(PRIMARY) or load_from(BACKUP) or Fernet.generate_key()
sync_to_both_locations(key)

Keeping the key in more than one place and reconciling them on every startup is unglamorous compared to the encryption itself, but it matters just as much in practice. A single storage location turns any accidental deletion or disk hiccup directly into unrecoverable data.

Letting a value announce its own encryption state

One more detail worth noting: every encrypted value in this app is prefixed with ENC: before being saved.

def encrypt_value(value: str) -> str:
    if value.startswith("ENC:"):
        return value  # already encrypted, skip
    encrypted = fernet.encrypt(value.encode()).decode()
    return f"ENC:{encrypted}"

That prefix solves two practical problems at once. First, it makes encryption idempotent — calling it twice on an already-encrypted value won't double-encrypt it. Second, it lets old plaintext data and newly encrypted data coexist in the same file without ambiguity: the value itself tells you which state it's in. That means encryption support can be added to an existing app without a one-time migration pass — new writes get encrypted immediately, and old entries only get encrypted the next time they're written.

Encrypting fields by allow-list, not by default

Rather than encrypting an entire configuration blob, this app exposes a helper that takes an explicit list of keys to encrypt within a dictionary — the caller decides what counts as sensitive.

def encrypt_dict(data: dict, keys_to_encrypt: list) -> dict:
    result = data.copy()
    for k in keys_to_encrypt:
        if k in result and result[k]:
            result[k] = encrypt_value(str(result[k]))
    return result

# Only the genuinely sensitive fields are named explicitly
site = encrypt_dict(site, ["ssh_password", "api_key"])

Encrypting non-sensitive fields like a site name or URL would make the config file unreadable and hard to diff by hand for no real benefit. An explicit allow-list keeps the sensitive fields protected while leaving everything else plain and inspectable.

Failing soft when decryption goes wrong

Finally, decryption here doesn't raise on failure — it just returns the value unchanged.

def decrypt_value(value: str) -> str:
    try:
        return fernet.decrypt(value[4:].encode()).decode()
    except Exception:
        return value  # return as-is rather than raising

That choice matters if a config file ever gets loaded with the wrong key (say, one generated on a different machine) or gets corrupted by a manual edit. Instead of crashing the whole app, one unreadable field is returned untouched while everything else keeps loading normally. A degraded state — one field still garbled — is a better outcome than the app failing to start at all.

Summary

Design piece	What it's for
Fernet (AES + HMAC + timestamp)	Encryption with built-in tamper detection
Key stored in two locations with mutual recovery	Reduces the risk that losing the key means losing the data
`ENC:` prefix	Prevents double-encryption; distinguishes old plaintext from new ciphertext
Allow-list-based `encrypt_dict`	Encrypts only sensitive fields, keeps the rest readable
Decryption fails soft, not hard	One corrupted field doesn't take down the whole app

Symmetric encryption itself is a well-established, boring technology. What actually determines whether it works safely in a real app is everything around it — where the key lives and how it survives being lost, how encrypted and plaintext values are told apart, and what happens when decryption doesn't go as planned.

What `rsync -avz --delete` Actually Does

Susumu Takahashi — Fri, 18 Sep 2026 00:13:53 +0000

A lot of people paste rsync -avz --delete into a deploy script and move on without ever unpacking what each letter means. It works, so there's rarely a reason to stop and ask. But understanding what each flag actually instructs the command to do makes it much easier to reason about exactly how far --delete reaches, and why the other flags are there in the first place. This post breaks down the main options and shows how they're actually used in a real theme deployment.

Note: rsync ("remote sync") is a file-synchronization tool that compares source and destination and transfers only what has changed. Unlike a plain copy, it uses a delta-transfer algorithm internally, which is where it earns its keep when the same files get synced over and over.

Quick reference

Option	Meaning	What it does
`-a`	archive mode	Recursively copies files while preserving permissions, timestamps, symlinks, and ownership
`-v`	verbose	Prints the name of every file transferred
`-z`	compress	Compresses data in transit to reduce bandwidth usage
`--delete`	delete sync	Removes files from the destination that no longer exist in the source, making the destination an exact mirror
`-e`	remote shell	Specifies how to connect (which SSH key, port, and options to use)

`-a` isn't one flag — it's a bundle of flags

-a looks like a single option, but it's shorthand for several flags combined. Expanded, it's equivalent to -rlptgoD:

Expanded	Meaning
`-r`	recursive — process directories recursively
`-l`	copy symlinks as symlinks, not as the files they point to
`-p`	preserve permissions
`-t`	preserve timestamps (modification time)
`-g`	preserve group ownership
`-o`	preserve owner
`-D`	preserve device and special files

The one that's easy to overlook is -t (preserve timestamps). rsync decides whether a file needs re-transferring by comparing file size and modification time against what it saw last time. If timestamps got reset to "now" on every sync instead of being preserved, rsync would see a different modification time on every run even when the file's content hadn't changed at all — and it would fall back to re-transferring everything, which defeats the point of a delta-transfer tool. Using -a isn't just about keeping metadata intact; it's what lets rsync's own change-detection logic work correctly in the first place.

How far does `--delete` actually reach?

--delete makes the destination match the source exactly: anything removed from the source also gets removed from the destination. The part worth understanding precisely is that it only operates within the specific source and destination directories you point it at.

If you run rsync -avz --delete "$SRC" "$DEST" against a theme-specific directory, --delete only affects whatever lives under $DEST — it has no effect on sibling directories outside that path (for example, other themes sitting alongside it under a shared themes/ folder). In practice, the blast radius of --delete is entirely determined by how narrowly you scope the destination path.

A real example: this project's theme deployment command

Deploying this blog's theme (wpmm-blog) to the server actually uses this command:

SRC=server/wpmm-blog-theme/wpmm-blog/
DEST=layer2024@layer2024.xsrv.jp:wpmm.jp/public_html/blog/wp-content/themes/wpmm-blog/

rsync -avz --delete \
  -e "ssh -i ~/.ssh/layer2024_xserver.key -p 10022 -o BatchMode=yes" \
  "$SRC" "$DEST"

Here, --delete is scoped to the theme's own directory (wp-content/themes/wpmm-blog/), so the only files it can actually remove are old theme files that have been deleted from the local source but are still lingering on the server. If the destination were mistakenly pointed at wp-content/themes/ (the entire themes folder) instead, other themes — including WordPress's own bundled default themes — would be exposed to deletion too. Scoping the destination down to exactly the directory you intend to deploy is what keeps --delete safe to use in practice.

The -e flag bundles the SSH key file, port number, and BatchMode=yes (which makes SSH fail immediately instead of waiting at an interactive password prompt) into a single connection specification. That matters specifically for unattended scripts — without it, a script running with no one watching could hang indefinitely at a prompt no one is there to answer.

The trailing slash changes the result

rsync has a well-known quirk: whether or not the source path ends in a slash (/) changes what actually gets copied.

rsync -av /path/to/src/ /path/to/dest/ — copies the contents of src directly into dest
rsync -av /path/to/src /path/to/dest/ — copies the src directory itself, landing as dest/src

In the theme deployment example above, SRC=server/wpmm-blog-theme/wpmm-blog/ ends in a slash, so the contents of wpmm-blog/ land directly under the destination's wpmm-blog/ directory rather than nesting one level deeper. Building a command without paying attention to the trailing slash is an easy way to end up with files one directory level off from where you meant them to go.

Summary

Option	In one line
`-a`	Recursive copy that preserves file attributes (bundles `-rlptgoD`)
`-v`	Prints what got transferred
`-z`	Compresses data to save bandwidth
`--delete`	Mirrors the destination to the source — scoping the destination path is the key to using it safely
`-e`	Specifies the connection method (SSH key, port, etc.)

-avz --delete is a common combination, but each character carries its own distinct responsibility. --delete in particular only reaches as far as the destination path you give it, so being deliberate about that scope is the basic safeguard against deleting more than you intended.

HTTP Status Code Basics: What 200/301/403/500 Actually Mean for Maintenance Tools

Susumu Takahashi — Thu, 17 Sep 2026 00:18:16 +0000

WordPress site maintenance constantly involves one basic question: after an update, is the site still working? Instead of relying on a human eyeballing a page and deciding "looks fine," most tooling answers that question mechanically, using the three-digit HTTP status code a web server returns for every request. That single number carries more information than it looks like at first glance.

Note: An HTTP status code is a three-digit number a web server always attaches to its response to a client (a browser or a program). It comes paired with a short phrase describing what it means, like 200 OK.

The leading digit sets the broad category

The hundreds digit of a status code determines its broad meaning.

Range	Category	Meaning
1xx	Informational	Request received, processing continues (rarely relevant in day-to-day work)
2xx	Success	The request was handled successfully
3xx	Redirection	The client needs to be pointed somewhere else
4xx	Client error	Something is wrong on the requesting side
5xx	Server error	Something failed on the server side

Even this broad grouping alone enables a first-pass judgment: "2xx generally means ignore it," "5xx always means investigate." Automated monitoring in maintenance tooling starts from exactly this coarse filter before looking any closer.

Codes you actually run into during maintenance work

Within those broad categories, a handful of specific codes show up constantly in maintenance work.

200 OK — the request succeeded and normal content was returned. The baseline "everything is fine" state
301 Moved Permanently — the requested URL has permanently moved to a different URL. Browsers automatically follow this to the new location. In WordPress this shows up when unifying http to https, or after a URL structure change
403 Forbidden — the server understood the request but is explicitly refusing to grant access. This isn't a login prompt; it's a deliberate "you may not see this." It typically shows up on sites protected by IP restrictions or Basic Auth when accessed unexpectedly
404 Not Found — the requested page doesn't exist. A classic case is following an old link to a post whose URL has since changed
500 Internal Server Error — the server hit an unexpected failure while processing the request. This is frequently how a PHP Fatal Error (a syntax error, a call to an undefined function, exhausted memory) surfaces externally, and it's one of the codes WordPress maintenance work watches for most closely

These numbers come from an RFC (a published internet technical standard), so they mean the same thing regardless of which server software or programming language produced the response — a genuinely shared vocabulary across the entire web.

A sixth status: "0"

In practical monitoring code, you'll often see a special value alongside the standard 1xx–5xx range: 0. This isn't part of the HTTP specification — it's a convention monitoring scripts use to represent no response came back at all. DNS resolution failure, connection timeout, an SSL certificate error — anything that fails before the request even reaches the server lands here.

A server explicitly saying "500" and a server saying nothing at all point to very different root causes, so keeping these two cases distinct matters for how monitoring logic is designed.

A real example: deciding whether to roll back by comparing before and after

This app updates WordPress core and plugins one item at a time, checking the HTTP status right after each individual update to decide whether things got worse — and if so, rolling back only that one update. The decision logic lives in a function called _should_rollback() in maintenance_agent.py, and it can be simplified to this:

def _should_rollback(post_status, prev_status):
    post = int(post_status)
    prev = int(prev_status) if prev_status is not None else 200

    # Server-level failure always triggers a rollback
    if post >= 500 or post == 0:
        return True
    # 4xx regression: only fires if the previous state was below 4xx
    if 400 <= post < 500 and prev < 400:
        return True
    return False

The categories above map directly onto this decision.

500-range or 0 (no response) always triggers a rollback, regardless of what came before. That's a server-level failure, and it's an unambiguous regression no matter what the prior state was
400-range only triggers a rollback if the previous state was below 400. This isn't a blanket "any 4xx means fail" rule, and there's a reason: some maintained sites deliberately sit behind Basic Auth (401) or IP restrictions (403) — staging environments, for instance. If the check simply flagged any post-update 4xx as a failure, a site that already returned 401 before the update would trigger a false rollback on every single run, even though nothing actually changed. By judging "did this get worse compared to right before," a site's own deliberate baseline state gets correctly treated as normal, not as a problem

The function that supplies post_status — _http_status_check_stable() — adds one more layer: it only retries, once, after a short delay, when the status comes back as 0 (no response). The intent is to avoid misreading a brief network blip or a momentary TLS handshake failure as the site being down, which would otherwise trigger an unnecessary rollback. A 500-range response, by contrast, isn't retried — it's treated as a real error immediately. The distinction is between "an uncertain state where we genuinely don't know yet" and "the server is explicitly telling us something is wrong," and the code treats those two situations differently on purpose.

Why this matters for maintenance tooling

Reading this three-digit number mechanically, instead of having a human open every page in a browser to eyeball it, is what makes it possible to check a large number of pages across a large number of sites against a consistent standard. Because status codes are a shared, unambiguous vocabulary, it becomes possible to verify "did this update break anything?" after every single change — without depending on human attention, and while leaving a clear trail of what was checked.

Summary

Code	Meaning	Typical handling in maintenance work
2xx	Success	Normal — generally safe to ignore
3xx	Redirection	Verify the move was intentional
4xx	Client error	Compare against the prior state before treating it as a regression
5xx	Server error	Always a real problem — investigate or roll back first
0 (convention)	No response	A connection-stage failure — retry once to rule out a transient blip

Once you have both the broad category behind the three-digit number and the habit of reading it as "how did this change compared to right before" rather than in isolation, monitoring design gets noticeably more accurate.

Reading `.htaccess` mod_rewrite Rules: A Real `RewriteBase` Trap From a Subdomain Migration

Susumu Takahashi — Wed, 16 Sep 2026 00:28:26 +0000

A WordPress URL like https://example.com/blog/some-post-title/ looks clean, but there's no directory or file on the server that actually matches that path. Behind the scenes, Apache's mod_rewrite module intercepts the request and silently forwards it to index.php. The rules that make this happen live in .htaccess, and when a WordPress site suddenly starts throwing 404s or 500s for no obvious reason, the cause is very often a misread rule in that file.

Note: .htaccess is a configuration file Apache reads on a per-directory basis. On shared hosting environments where you can't edit the server's global configuration directly, dropping this file into a directory is often the only way to change how requests to that directory behave — which is exactly why it's one of the files people touch most often on shared hosting.

The Basic Syntax — Four Building Blocks

The .htaccess block WordPress writes out by default is built from four elements working together:

# BEGIN WordPress
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /blog/
RewriteRule ^index\.php$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /blog/index.php [L]
</IfModule>
# END WordPress

RewriteEngine On — turns on rewriting for this directory. Without it, every line below is ignored.
RewriteCond (condition) — sets a precondition for the RewriteRule immediately following it. %{REQUEST_FILENAME} !-f means "the requested path is not an existing file," and !-d means "not an existing directory." The rule below only fires when both conditions hold.
RewriteRule (the rewrite itself) — takes the form pattern target [flags]. . matches "one or more of any character" — essentially any path — and forwards it internally to /blog/index.php. That single line is the actual mechanism behind WordPress's pretty permalinks.
The [L] flag — short for "Last." Once this rule applies, Apache stops evaluating further rules, which prevents a chain of rules from double-rewriting the same request in unintended ways.

Other flags worth knowing: [R=301] (returns a genuine permanent redirect the browser follows, changing the visible URL, as opposed to a silent internal forward), [NC] (case-insensitive matching), and [QSA] (appends the original query string onto the rewritten target instead of dropping it). A plain internal rewrite and an [R=301]-flagged redirect can look superficially similar in a rule file but behave completely differently — that distinction is worth keeping straight.

`RewriteBase` — the Anchor Point for Relative Paths

The line most often overlooked is RewriteBase /blog/. When a RewriteRule's target is a relative path (one that doesn't start with /), Apache resolves it against this RewriteBase value. The WordPress installer generates this value automatically, based on whatever URL path the install is actually running at (its home_url). That works fine under normal conditions — but if the server structure changes after installation, this one value can be left pointing at a path that no longer exists.

A Real Example — The Trap We Hit During a Subdomain Migration

We hit exactly this trap while setting up the English version of this blog (en.wpmm.jp/blog/). Here's how it played out:

We first installed WordPress at wpmm.jp/public_html/en/blog/ through the hosting provider's one-click installer. At that point the site's URL structure was wpmm.jp/en/blog/ — a subdirectory under the main domain.
We then created a subdomain, en.wpmm.jp, and pointed its docroot at that same wpmm.jp/public_html/en/ directory. The visible URL structure now became en.wpmm.jp/blog/.
We updated WordPress's internal URL settings to match the new subdomain via wp option update home and wp option update siteurl.
But .htaccess's RewriteBase was still holding the value from step 1: /en/blog/.

What happened next was interesting. The homepage (a near-direct hit on index.php) loaded fine, but every individual post, category archive, search result, and 404 page came back as a 500 error. The homepage largely bypasses mod_rewrite and resolves close to a direct file hit, while any permalinked URL has to pass through the RewriteRule internal forward. When that forward resolved paths against the stale RewriteBase /en/blog/, the result no longer matched the actual document root structure, and WordPress couldn't recognize the incoming request as a valid URL.

One more wrinkle: running wp rewrite flush --hard — the WP-CLI command meant to regenerate WordPress's internal routing rules and write them back to .htaccess — didn't fix the file. The shared hosting environment's permission constraints returned a warning ("Regenerating a .htaccess file requires special configuration") without actually modifying anything. The fix ended up being simple but manual: back up .htaccess, then hand-edit RewriteBase to the correct path (/blog/).

The General Lesson

The takeaway generalizes beyond mod_rewrite specifically, to auto-generated configuration files as a category: a config file generated at install time captures a snapshot of the conditions that existed at that moment — it doesn't automatically track the infrastructure changing underneath it later. Even a "regenerate" command like wp rewrite flush can't be trusted blindly, since the permissions of the environment it runs in may quietly prevent it from touching the actual file. After any infrastructure change — subdomain migration, directory move, domain switch — opening .htaccess directly and visually confirming that RewriteBase still matches the real path structure is a small extra step that turns out to be the most reliable way to catch this class of bug.

Summary

Element	Role
`RewriteEngine On`	Turns on rewriting for this directory
`RewriteCond`	Sets a precondition for the `RewriteRule` below it (e.g., only if not an existing file/directory)
`RewriteRule`	Forwards or redirects matching requests to another path
`RewriteBase`	The anchor directory relative paths resolve against — a value frozen at install time
`[L]`	Stops evaluating further rules once this one matches
`[R=301]`	Returns a real permanent redirect (visible URL change), not a silent internal forward

.htaccess reads like an incantation at first glance, but it's decodable once you know what these four elements are each responsible for. RewriteBase in particular is worth checking deliberately any time the underlying infrastructure changes — it's exactly the kind of value that gets left behind.

DEV Community: Susumu Takahashi

DNS Records Explained — What A, CNAME, and TXT Records Actually Point To

What DNS is resolving

A records — a hostname pointing straight at an IPv4 address

CNAME records — a hostname pointing at another hostname

TXT records — arbitrary text attached to a name

Example 1: standing up a subdomain starts with an A record

Example 2: email deliverability comes down to a set of three TXT records

Takeaway

pip Version Specifiers — What `==`, `>=`, and `~=` Actually Commit You To

The question a version specifier is answering

The main operators, compared

Why our own requirements.txt uses >=

What >= gives up in exchange — build reproducibility

Takeaway

Cache-Control vs. ETag: What Each One Actually Controls

The Problem These Headers Solve

What Cache-Control Controls

What ETag Controls — Checking In After Expiration

Why ogp-generator.php Doesn't Use ETag

Takeaway

Exponential Backoff vs. Fixed-Interval Retries: When Growing Wait Times Actually Help

The Problem Exponential Backoff Solves

Example 1: A Single Fixed Retry for HTTP Checks

Example 2: Polling for a File Lock at a Fixed Interval

Example 3: Retrying by Changing Approach, Not by Waiting

Takeaway

Why SSH Key Authentication Beats Password Authentication — What Is Actually Being Proven

Authentication is an act of proof

Password authentication: proving you know a secret by stating it

Public-key authentication: proving possession without ever handing over the secret

What happens if server-side data leaks

A real example: narrowing authentication down to one explicit key

Turning password login off entirely, server-side

How this connects to choosing a key type

Summary

Unit Tests vs. Regression Tests: Why the Same Feature Gets Tested Twice

Unit tests: verifying a function in isolation

Regression tests: sealing off an incident that already happened

Why a "correct" function still broke

What the test filenames themselves signal

The connection to visual regression testing

Summary

How Desktop Apps Detect and Kill Stale Processes on Startup

Why a Process Can Fail to Exit

Separating "the PID is alive" from "the port is responding"

Force-killing also differs by OS

macOS has its own reactivation quirk

A different problem: the browser tab closes, the server doesn't

Summary

Semantic Versioning (SemVer): Why Version Numbers Have Three Parts

What MAJOR.MINOR.PATCH Each Mean

Why a Single Incrementing Number Isn't Enough

Why Version Comparisons Need to Be Numeric

A Version Number Doesn't Live in Just One Place

Summary

How Symmetric Encryption (Fernet) Keeps Local Credentials Safe on Disk

Why symmetric encryption is the right tool here

What Fernet actually bundles together

Where the key lives, and how not to lose it

Letting a value announce its own encryption state

Encrypting fields by allow-list, not by default

Failing soft when decryption goes wrong

Summary

What `rsync -avz --delete` Actually Does

Quick reference

-a isn't one flag — it's a bundle of flags

How far does --delete actually reach?

A real example: this project's theme deployment command

The trailing slash changes the result

Summary

HTTP Status Code Basics: What 200/301/403/500 Actually Mean for Maintenance Tools

The leading digit sets the broad category

Codes you actually run into during maintenance work

A sixth status: "0"

A real example: deciding whether to roll back by comparing before and after

Why this matters for maintenance tooling

Summary

Reading `.htaccess` mod_rewrite Rules: A Real `RewriteBase` Trap From a Subdomain Migration

The Basic Syntax — Four Building Blocks

Why our own requirements.txt uses `>=`

What `>=` gives up in exchange — build reproducibility

`-a` isn't one flag — it's a bundle of flags

How far does `--delete` actually reach?

`RewriteBase` — the Anchor Point for Relative Paths