mchus/bible
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Move inline code examples out of normative contracts

Browse Source 
identifier-normalization, no-hardcoded-vendors,
vendor-installer-verification, and build-version-display follow the
go-database split: rules in contract.md, snippets in README.md. Routed
contract reads get cheaper; examples stay available on demand. Lint now
also rejects stale kit/patterns references.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Michael Chus
2026-06-12 10:00:02 +03:00
parent 421d004faf
commit a44133aff2
9 changed files with 201 additions and 221 deletions
Download Patch File Download Diff File Expand all files Collapse all files

46
rules/patterns/vendor-installer-verification/README.md Normal file
View File

@@ -0,0 +1,46 @@
# Vendor Installer Verification Pattern Notes
This file keeps examples. The normative rules live in `contract.md`.
## Download Order
```sh
BASE_URL="https://vendor.example.com/downloads/${VERSION}"
BIN_FILE="/var/cache/vendor-${VERSION}.run"
SHA_FILE="/var/cache/vendor-${VERSION}.run.sha256sum"
# 1. Download checksum first
wget -q -O "$SHA_FILE" "${BASE_URL}/vendor-${VERSION}.run.sha256sum"
# 2. Download installer
wget --show-progress -O "$BIN_FILE" "${BASE_URL}/vendor-${VERSION}.run"
# 3. Verify
cd /var/cache
sha256sum -c "$SHA_FILE" || { echo "ERROR: sha256 mismatch"; rm -f "$BIN_FILE"; exit 1; }
```
## Cache with Verification
```sh
verify_cached() {
[ -s "$SHA_FILE" ] || return 1 # sha256 file missing or empty
[ -s "$BIN_FILE" ] || return 1 # binary missing or empty
cd "$(dirname "$BIN_FILE")"
sha256sum -c "$SHA_FILE" --status 2>/dev/null
}
if ! verify_cached; then
rm -f "$BIN_FILE" "$SHA_FILE"
# ... download and verify
else
echo "verified from cache"
fi
```
## Version Validation
```sh
curl -sIL "https://vendor.example.com/downloads/${VERSION}/installer.run" \
| grep -i 'http/\|content-length'
```

74
rules/patterns/vendor-installer-verification/contract.md
View File

@@ -1,6 +1,6 @@
# Contract: Vendor Installer Verification
Version: 1.0
Version: 1.1
## Purpose
@@ -8,75 +8,19 @@ Rules for downloading and verifying proprietary vendor installers (`.run`, `.exe
where the vendor publishes a checksum alongside the binary.
Applies to: NVIDIA drivers, vendor CLI tools, firmware packages.
---
## Download Order
Always download the checksum file **before** the installer:
```sh
BASE_URL="https://vendor.example.com/downloads/${VERSION}"
BIN_FILE="/var/cache/vendor-${VERSION}.run"
SHA_FILE="/var/cache/vendor-${VERSION}.run.sha256sum"
# 1. Download checksum first
wget -q -O "$SHA_FILE" "${BASE_URL}/vendor-${VERSION}.run.sha256sum"
# 2. Download installer
wget --show-progress -O "$BIN_FILE" "${BASE_URL}/vendor-${VERSION}.run"
# 3. Verify
cd /var/cache
sha256sum -c "$SHA_FILE" || { echo "ERROR: sha256 mismatch"; rm -f "$BIN_FILE"; exit 1; }
```
Reason: if the download is interrupted, you have the expected checksum to verify against on retry.
---
## Cache with Verification
Never assume a cached file is valid — a previous download may have been interrupted (0-byte file):
```sh
verify_cached() {
[ -s "$SHA_FILE" ] || return 1 # sha256 file missing or empty
[ -s "$BIN_FILE" ] || return 1 # binary missing or empty
cd "$(dirname "$BIN_FILE")"
sha256sum -c "$SHA_FILE" --status 2>/dev/null
}
if ! verify_cached; then
rm -f "$BIN_FILE" "$SHA_FILE"
# ... download and verify
else
echo "verified from cache"
fi
```
**Never check only for file existence.** Check that the file is non-empty (`-s`) AND passes checksum.
---
## Version Validation
Before writing build scripts, verify the version URL actually exists:
```sh
curl -sIL "https://vendor.example.com/downloads/${VERSION}/installer.run" \
| grep -i 'http/\|content-length'
```
A `404` or `content-length: 0` means the version does not exist on that CDN.
Vendor version numbering may have gaps (e.g. NVIDIA skips minor versions on some CDNs).
---
See `README.md` for shell snippets.
## Rules
- Download checksum before installer — never after.
- Download the checksum file **before** the installer — never after. If the download is
interrupted, you still have the expected checksum to verify against on retry.
- Verify checksum before extracting or executing.
- On mismatch: delete the file, exit with error. Never proceed with a bad installer.
- Never assume a cached file is valid — a previous download may have been interrupted.
**Never check only for file existence**: the file must be non-empty (`-s`) AND pass checksum.
- Cache by `version` + any secondary key (e.g. kernel version for compiled modules).
- Before writing build scripts, verify the version URL actually exists (`curl -sIL`).
A `404` or `content-length: 0` means the version is absent on that CDN; vendor version
numbering may have gaps.
- Never commit installer files to git — always download at build time.
- Log the expected hash when downloading so failures are diagnosable.