Skip to content
This repository was archived by the owner on Oct 12, 2026. It is now read-only.

refactor!: rename to brdoc, delete the cache, version the API - #12

Merged
jeferson0306 merged 1 commit into
masterfrom
feat/brdoc-v1
Sep 4, 2026
Merged

jeferson0306 merged 1 commit into
masterfrom
feat/brdoc-v1

Conversation

@jeferson0306

Copy link
Copy Markdown
Collaborator

Three changes that belong together because each one is a break, and a single break is cheaper than three.

github.com/jeferson0306/brdoc

api-data-validator described a service. What this mostly is now is a library, and github.com/jeferson0306/api-data-validator/validate reads badly in an import block.

GitHub redirects the old repository URL, the Render deployment is unaffected (verified — /health answered throughout the rename), and nothing depends on the old module path yet. That is precisely why this is the moment: the same change in a month costs someone else a broken build.

The cache is deleted

#10's benchmarks settled it:

CPF check 522 ns
Redis round trip, measured in production 150–220 ms

Five orders of magnitude, in the wrong direction. And worse than the latency: building the cache key requires the normalised value, and normalising is most of the validation — the answer was already computed before the cache was consulted. It was never an optimisation, only a delay with a name.

from_cache leaves the response with it. /health stops reporting a subsystem that no longer exists and now answers {"status":"ok"}: validation is arithmetic with no dependencies, so if the process is answering, it is working. A health check enumerating subsystems the service does not have is theatre.

This is the breaking change, and the reason the rename rides along with it.

/v1, and the old paths kept forever

GET  /v1/validate?cpf=529.982.247-25
POST /v1/validate/batch
GET  /v1/health

The unversioned /validate, /validate/batch and /health stay permanently. They were published, things point at them — the portfolio console among them — and breaking a URL to tidy a prefix is a cost paid by other people to make my file look neater.

/v1 is not there to move anyone today. It is there so the next breaking change has somewhere to go, which is the whole point of versioning and the reason to add it while there is nothing to migrate.

Verified

Smoke tested against a running binary: both route generations answer 200, from_cache is absent from the response body, /health returns a single field. go test ./... -race and go vet green.

After merging

The portfolio console points at /validate and keeps working unchanged. I will move it to /v1 and update the project links on the site separately — GitHub's redirect means nothing is broken in the meantime.

Three changes that belong together because each is a break, and one break is
cheaper than three.

The module is github.com/jeferson0306/brdoc. api-data-validator described a
service; what this mostly is now is a library, and .../api-data-validator/validate
reads badly in an import block. GitHub redirects the old URL, and nothing
depends on the old module path yet — which is precisely why this is the moment.

The cache is gone. #10's benchmarks put a CPF check at 522ns against a Redis
round trip measured at 150-220ms in production, and building the cache key
required the normalised value, which is most of the validation — the answer was
already computed before the cache was consulted. It was never an optimisation.
from_cache leaves the response with it, and /health stops reporting a subsystem
that no longer exists: validation is arithmetic with no dependencies, so if the
process answers, it works. Enumerating subsystems a service does not have is
theatre.

/v1 is mounted, and the unversioned paths stay permanently. They were
published, things point at them, and breaking a URL to tidy a prefix is a cost
paid by other people. /v1 exists so the next change has somewhere to go rather
than to move anyone today.

Smoke tested against a running binary: both route generations answer, from_cache
is absent from the response, and health reports one field.
@jeferson0306
jeferson0306 merged commit c2788c6 into master Sep 4, 2026
1 check passed
@jeferson0306
jeferson0306 deleted the feat/brdoc-v1 branch September 4, 2026 09:36
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant