# Cloud, IaC & Networking
Infrastructure as code, cloud SDKs, edge runtimes, proxies, gateways and tunnels.
340 instructions from 14 repositories. Last updated 2026-07-27.
---
## Cache Validity Contracts
When caching derived state, you must define (and encode) a validity contract: *what exact changes make the cached data incorrect*, and how that change is detected (keying and/or TTL/refresh).
Practical rules:
1) **Key caches on the right change marker**
- Use config change indices such as `metadata.modifiedIndex` / `conf_version` as part of cache keys (so rebuild happens on metadata/config change, not only on LRU eviction or TTL).
2) **Include secret/external-data drift in validity**
- If the cached output depends on secrets that don’t bump `conf_version`, bound staleness with a TTL/refresh or include a secret version in the validity check.
3) **Treat delete/empty updates as real changes**
- In incremental caches, ensure delete events and “plugins becomes empty” updates still get recorded so the old cached entries are removed; don’t early-return before enqueueing reconciliation.
4) **Normalize entity identifiers across full vs incremental paths**
- Any ID used to add/remove cached entries must be identical in both the incremental update path and the full rebuild path.
5) **Make cache-rebuild side effects idempotent**
- If a cached object refreshes by recreating functions/closures, ensure repeated rebuild doesn’t stack wrappers (capture originals outside the per-build override, or guard with a one-time flag).
Code sketch (keying on a change marker):
```lua
-- Example pattern: include modifiedIndex in the cache key
local tracer, err = core.lrucache.plugin_ctx(
lrucache,
api_ctx,
metadata.modifiedIndex, -- invalidates/rebuilds on metadata change
create_tracer_obj,
conf,
plugin_info
)
```
Code sketch (don’t skip deletes/empty updates in incremental reconciliation):
```lua
local function filter(val)
if not val.value then
pending_delete = true
has_pending = true
-- record delete so reconciliation removes old entries
return
end
-- ... even if val.value.plugins is empty, still record the update for reconciliation
end
```
Adhering to these rules prevents security/auth drift, stale behavior that only clears on TTL, and “rebuild-time” bugs caused by inconsistent IDs or non-idempotent refresh logic.
---
## Accurate Semantic Naming
Use names that reflect the external meaning and documented behavior—not internal implementation details or misleading assumptions.
**Rules**
1. **Match the public/schema concept**: For headers, config flags, schema fields, provider values, and any user-visible identifiers, use names aligned to the schema wording and intent (avoid internal library terms).
2. **Name by protocol/operation when behavior is protocol-specific**: If logic is specifically for a protocol operation (e.g., Bedrock “converse”), name the function/entry points accordingly so future protocol additions don’t force renames or confusion.
3. **Ensure the name is behavior-accurate**: Don’t name a function “is_*” unless it truly performs that check. If existing utilities already “resolve if possible,” prefer using those rather than creating a predicate that can’t actually validate the claim.
4. **Keep parameter/flag naming consistent**: Use one agreed term across the codebase (e.g., `commit` vs `dry_run`) and ensure call sites pass the same parameter.
5. **For transformed identifiers, be deterministic and collision-safe**: When generating names (tool names, mapped identifiers, keys), guarantee uniqueness in a stable way and preserve enough mapping to restore the original.
**Example patterns**
- Avoid internal/external mismatch:
```lua
-- Prefer schema-aligned naming
local raw_id_token = session:get("enc_id_token")
if raw_id_token and conf.set_raw_id_token_header then
core.request.set_header(ctx, "X-Raw-ID-Token", raw_id_token)
end
```
- Don’t create misleading predicates; rely on the resolver:
```lua
-- Instead of a fake validator like is_nginx_variable(), use resolve_var
local resolved, count = core.utils.resolve_var(template)
if count == 0 then
-- leave as-is
end
```
- Deterministic collision-safe suffixing for mapped identifiers:
- Reserve already-valid upstream names and suffix only the rewritten ones, or append a deterministic hash so collisions are impossible by construction while allowing round-trip restoration.
---
## Security Invariants Guardrails
When changing auth/secret/TLS/validation code, treat existing security semantics as invariants: refactors must not weaken them, and config defaults/warnings must be applied after schema normalization.
Apply this checklist:
1) Preserve security-critical behavior (anti-spoofing / header clearing / response withholding)
- Keep the original “remove/clear” semantics when an upstream auth response does not contain a header. Do not replace unconditional logic with guards that allow client-injected values.
Example (anti-spoofing header clearing):
```lua
-- Security invariant: headers not present in auth response must not survive
for _, header in ipairs(conf.upstream_headers) do
local header_value = res.headers[header]
-- keep old behavior: nil clears any client-supplied header
core.request.set_header(ctx, header, header_value)
end
```
2) Ensure fail-open/fail-closed is explicit and testable
- If a guard/plugin withholds output until the “assembled” payload is available, handle missing telemetry/events deterministically; never silently release data due to absent optional signals.
- Add regression tests for missing chunks/events and for the intended open/closed behavior.
3) Encrypt sensitive fields at rest (and verify framework support)
- Add `encrypt_fields` for every secret stored in plugin metadata/config.
- If a secret-ref mechanism bypasses schema constraints, ensure the remaining protections (required fields, allowed formats, dependency checks) still hold.
4) TLS verification warnings/config must reflect reality
- Expose `tls.verify` (default true) and emit warnings using the established helper, placed after schema defaults are applied so `{}` is handled as expected.
- Don’t rely on options that are silently ignored by the HTTP client; document the required CA/trust configuration so TLS verification works with default in-cluster settings.
5) Secret-manager integration must load required config in all subsystems
- If secrets are resolved in stream/worker paths, ensure the init/snapshot preload covers the necessary etcd directories; add coverage for both HTTP and stream secret references.
This prevents common production failures: header spoofing regressions, silent fail-open in guards, plaintext secret persistence, missing/incorrect TLS verification warnings, and secret-resolution breakage due to incomplete preload/config coverage.
---
## Semantics-Correct Algorithms
When implementing or choosing an algorithm (scoring, aggregation, throttling, parsing), ensure it matches the domain semantics and behaves predictably under edge cases.
Guidelines:
- Match the meaning of inputs to the reduction/selection operator. If the decision should succeed when *any* candidate matches, use `max`-style logic; avoid `avg/min`-style dilution unless the semantics truly require “all” or “average.”
- Avoid “knobs” that enable semantically incorrect defaults. Prefer a single safe behavior (or document loudly why each option changes routing/throttling outcomes).
- When offering exact vs approximate algorithms, make the trade-off explicit and bounded:
- Exact algorithms: justify complexity/space and show why state doesn’t grow unbounded.
- Approximate algorithms: quantify error expectations and document intended use cases.
- Ensure deterministic behavior where order matters (e.g., sorting names before returning) and make parsing robust to legal trailing frames/comments/heartbeats.
- Add targeted tests that demonstrate correctness (including numeric counterexamples and realistic protocol edge cases).
Example (semantic routing aggregation):
```lua
-- Scores are for alternative examples of the same intent.
-- Semantics: “any example matches => route succeeds”, so aggregate by max.
local function semantic_pick(scores, threshold)
local best = -math.huge
for _, s in ipairs(scores) do
if s > best then best = s end
end
if best >= threshold then
return true
end
return false
end
```
Apply this standard whenever you change scoring/routing/throttling/parsing logic, especially for user-visible behavior where “almost right” algorithms cause silent misroutes or inconsistent rate-limit outcomes.
---
## Wire-Format Contract Tests
When implementing or modifying any API-facing behavior (endpoint URL construction, request/response mappings, routing encodings, capability expansion), treat the final wire format as the contract. Prevent silent mismatches by combining schema validation, explicit documentation of any byte-exact normalization rules, and end-to-end tests that assert the exact observable output.
Apply these rules:
- Validate early & fail loudly: if a required endpoint/path/query component is missing or cannot be represented (e.g., Azure deployment root vs deployment+embeddings path), reject in schema/checks instead of letting code build the wrong URL.
- Add end-to-end assertions: if mapping/flattening changes how a client-facing redirect URL/query/body is formed, test the real runtime output (not only schema).
- Document byte-exact formatting: if you normalize encodings/casing in a way that affects matching (e.g., kept “%2F” becomes upper-case), document what authors must write.
- Preserve request pass-through semantics: avoid unintentionally narrowing what fields are forwarded; if behavior must change, make it explicit and test it.
Example pattern (Azure-like capability wiring + runtime validation):
- Schema: reject endpoints that don’t include the required deployment path.
- Capability default: avoid “dead” default paths.
- E2E: call the route using an Azure-shaped endpoint and assert the final request lands on the deployment path including the required query params (e.g., `.../deployments/{deployment}/embeddings?api-version=...`).
---
## Harden Errors And Cleanup
Treat any external input (HTTP headers, JSON bodies, provider responses, dynamic config) as untrusted: validate its type/shape before indexing or string operations, and ensure errors don’t turn into uncontrolled 500s or leak state/resources.
Apply these rules:
- Validate before use: check types/structure (e.g., header could be a table; JSON may have unexpected scalar/shape). Return (nil, "…")/bypass with a clear log instead of letting `attempt to index a number/table` or `bad argument` escape.
- Make failures bounded: when reporting errors from third-party bodies, sanitize/bound the content; prefer status + a short reason over embedding full bodies.
- Keep retries correct: reset per-attempt flags/state at the entry of the operation being retried; never reuse a previous attempt’s “aborted/failed” marker.
- Cleanup must be unconditional: teardown and resource release must run even when handlers fail (use pcall for handler calls, then release in a finally-like path).
- Never poison connection pools: only `set_keepalive`/reuse a Redis (or cosocket) connection after the command succeeded; otherwise close.
- Prefer graceful handling over assert on remote data: log and skip/ignore invalid items instead of panicking.
Example pattern (Lua):
```lua
local function parse_embedding_response(core, raw_body)
local data = core.json.decode(raw_body)
if type(data) ~= "table" or type(data.data) ~= "table" then
return nil, "invalid embedding response"
end
local vectors = {}
for i, item in ipairs(data.data) do
if type(item) ~= "table" then
return nil, "invalid embedding entry at index " .. (i - 1)
end
-- safe field access after type checks
end
return vectors
end
local function with_redis(conf, fn)
local red, err = redis_util.new(conf)
if not red then return nil, err end
local ok, res, rerr = pcall(fn, red)
if not ok then
red:close()
return nil, res
end
-- only reuse after success
local ok_keep, kerr = red:set_keepalive(conf.redis_keepalive_timeout, conf.redis_keepalive_pool)
if not ok_keep then red:close() end
return res
end
```
---
## Test isolation and determinism
Tests should be deterministic, isolated, and assert the intended behavior (not just a coincidence or shared prior state). Concretely:
- Reset external/shared state for every test (especially Redis, quotas, counters). Do not rely on the order tests run.
- Avoid vacuous assertions and shared artifacts (e.g., “last line in a shared file”) that can match data from earlier blocks.
- When testing stateful backends, prefer multi-worker coverage so race/state behavior is exercised.
- Keep test scaffolding minimal—remove dead/irrelevant setup that doesn’t actually reach the code under test.
- Use fixed test inputs/identifiers where applicable to avoid flakiness.
Example (state reset + independent setup):
```perl
add_block_preprocessor(sub {
my ($block) = @_;
# Ensure Redis-backed tests start from a known state
require("lib.test_redis").flush_all();
# Optionally set a deterministic default request
if (!$block->request) {
$block->set_value("request", "GET /t");
}
});
```
Example (avoid shared-state/vacuous “tail -n 1”):
- Don’t assert against a shared “last export” file unless you can correlate the export to the current request.
- If you must pattern-match, make the pattern reject the forbidden value (e.g., all-zero) instead of only matching a broad UUID/hex shape.
Apply this standard when adding or modifying tests in the Testing category to reduce CI flakiness and increase confidence in coverage.
---
## Schema-consistent config
When implementing configuration-driven features, make validation/forwarding/runtime consumption strictly follow the schema and any shared capability wrapper. Avoid plugin-specific special casing for generic capabilities, avoid manual per-branch field copying that can silently drop accepted config, and ensure environment-variable access uses the project’s standard env abstraction.
Practical rules:
1) Validate against the exact schema object that runtime uses (including wrapper/enrichment).
- Example (pattern):
```lua
function _M.check_schema(conf, schema_type)
-- if _M.schema is wrapped, validate against _M.schema
return core.schema.check(_M.schema, conf)
end
```
2) Don’t introduce user-facing config knobs that actually belong to a shared batch processor (or other generic capability). Prefer passing the value into the shared manager capability, and replicate schema entries across all plugins that use the same capability.
3) Enforce meaningful constraints in the user-facing schema (e.g., minimum values), and ensure “accepted by schema” fields are never silently dropped at runtime.
- Prefer schema-driven forwarding instead of per-policy hand-copying (so future schema additions don’t get missed).
4) For env-backed defaults, use the project’s env API (e.g., `core.env.get(...)`) and ensure documented defaults are truly available in worker runtime (workers only see env vars declared via the appropriate env directive).
Outcome: configuration is accepted/rejected consistently, validated fields reach the underlying implementation, and env-dependent behavior works reliably across standalone and worker runtimes.
---
## Null Safety Contracts
When handling optional/nil values, treat nil as a real input only if it’s reachable; otherwise remove dead checks. More importantly, enforce clear contracts for types/shapes so nil never reaches code paths that assume a table/string.
Practical rules:
1) Guard before indexing/iteration
- If a value may be nil, check it (and/or its type) before doing `x[y]`, `x:method()`, `pairs(x)`, or `table.concat`.
2) Preserve function return contracts
- Helpers that callers iterate over should return a safe type on all paths (e.g., always return `{}` instead of `nil` if the caller does `pairs(...)`).
3) Match conditional construction with downstream access
- If one branch omits a nested table (e.g., `body.index`), ensure later code doesn’t unconditionally access it. Either build the required structure in all branches or branch the downstream logic too.
4) Prefer explicit fallback over misleading nil branches
- If a nil-check is unreachable, delete it and use a forgiving fallback (e.g., `fetch_secrets(...) or upstream_obj`) to keep behavior correct in failure cases.
5) Tests: avoid vacuous “truthy encryption”
- When asserting that a value is encrypted, first require it’s a non-empty string; otherwise `nil ~= "plaintext"` will incorrectly pass.
Example patterns:
```lua
-- 1) fallback instead of dead nil-check
local new_upstream_ssl = apisix_secret.fetch_secrets(upstream_ssl, true)
new_upstream_ssl = new_upstream_ssl or upstream_ssl
-- 2) return safe type for iteration
local function names_from_proto(proto_obj)
local names = {}
if type(proto_obj) ~= "table" then
return names
end
-- ... fill names
return names
end
-- 3) nil-guard before method call
local data = core.request.get_body()
local ticket = data and data:match("(.+)")
-- 5) test: require non-empty string
local conf = get_conf()
local v = conf.client_rsa_private_key
assert(type(v) == "string" and v ~= "" and v ~= "plaintext")
```
---
## Observability semantic contract
Establish an explicit observability contract in code: tracing spans must be finished centrally with correct semantics; trace context inputs must be validated/formatted to standards; metrics must not mix different meanings across streaming vs non-streaming.
Apply these rules:
1) Centralize span finishing on exit/error
- Finish spans in common response exit paths so you don’t rely on “every caller remembering.” Prefer error/exit thresholds (e.g., `code >= 400`) and/or provide a shared tracer utility to finish any pending spans.
2) Validate/format W3C traceparent inputs
- Never treat arbitrary IDs as `trace_id` unless they match W3C requirements (32 lowercase hex chars). If you must derive from a UUID/request id, transform it (e.g., remove hyphens) or fall back to generated IDs.
3) Use OTEL semantic convention attribute keys
- Prefer the canonical OTEL names (e.g., `http.response.status_code`) to keep dashboards and tools consistent.
4) Define metric meaning per request mode
- Don’t reuse one metric series for multiple “time” definitions. For AI streaming, record TTFT separately from total completion latency; for non-streaming, avoid writing TTFT-at-a-single-moment distributions.
Example patterns (illustrative):
```lua
-- 1) Finish spans on error in a shared exit path
if code and code >= 400 then
tracer.finish_current_span(tracer.status.ERROR, message or ("response code " .. code))
end
-- 2) Validate W3C trace_id when building traceparent
local function is_valid_trace_id(id)
return type(id) == "string" and id:match("^%x%x%x%x%x%x%x%x%x%x%x%x%x%x%x%x%x%x%x%x%x%x%x%x%x%x%x%x%x%x%x%x$")
end
local trace_id = incoming_trace_id
if not is_valid_trace_id(trace_id) then
trace_id = uuid.generate_v4() -- or transform/remove hyphens from UUID
end
-- 3) OTEL semantic convention
span:set_attributes(attr.int("http.response.status_code", upstream_status))
-- 4) Metrics split by request type
if vars.request_type == "ai_stream" then
metrics.apisix_llm_ttft:observe(ttft_ms, labels)
-- apisix_llm_latency should represent total completion latency for streaming
end
```
Result: consistent tracing shutdown, standards-compliant context propagation, tool-friendly semantic attributes, and metric series that remain interpretable for alerts and SLOs.
---
## Avoid Hot-Path Work
When optimizing performance, ensure hot paths do only the minimum required work and never block while holding scarce resources. Apply these rules:
- Gate expensive resolution/processing behind cheap checks (e.g., only resolve secrets if references exist; only buffer/scan when blocking is requested).
- Don’t hold pooled connections (Redis, DB, etc.) across outbound network calls; release/re-acquire around blocking operations.
- Memoize configuration-derived decisions and reuse prepared objects/parsers; avoid recomputing defaults and deep-copying large structures per request.
- Preserve fast paths by scoping changes to the exact feature flags/conditions; avoid broad behavior changes that remove optimizations.
- Avoid “fetch everything” background patterns; query/cache only the entities actually in use.
Example (secret gating + pooled Redis around outbound call):
```lua
-- Guard per-request deep work
if secret.has_secret_ref(upstream_ssl) then
local resolved = apisix_secret.fetch_secrets(upstream_ssl, true)
upstream_ssl = resolved
end
-- Release pooled Redis before outbound embedding request
local res = red:get(key)
if miss then
local embedding = do_outbound_http_request(body) -- no Redis held
-- re-acquire only for Redis writes/search
-- e.g., ensure_index/knn_search using a fresh/checked-out connection
end
```
Use lightweight checks + memoization to keep latency stable under load, and structure code so scarce pools aren’t drained by long waits.
---
## Actionable logging rules
Adopt consistent logging practices:
- **Never allow correctness-affecting failures to be silent**, especially inside OpenResty async callbacks (e.g., `ngx.timer.at`, log phase). Log each error path *inside* the callback.
- **Avoid noisy logs for expected/controlled conditions** (e.g., rate/connection limits being reached as part of normal operation). If it will spam, downgrade/remove it.
- **Use the correct log level**: errors for unexpected failures; warn for expected degradation or shutdown paths where tests/operators shouldn’t treat it as an error.
- **Include actionable context** in every message (limits/thresholds, computed values, relevant identifiers like `service_name`), and don’t log “mystery failures.”
- **Prevent duplicate logging**: if a helper already logs, don’t log again at the caller.
Example pattern (async callback):
```lua
local function log_phase_work()
local red, err = redis.new(conf)
if not red then
core.log.error("failed to create redis in log phase: ", err)
return
end
local ok, incoming_err = red:do_incoming(...)
if not ok or incoming_err then
core.log.error("failed to deduct tokens in log phase: ", incoming_err)
return
end
-- release connection etc.
end
-- If you create a timer, still log inside the callback:
ngx.timer.at(0, log_phase_work)
```
Checklist for any new log line:
1) Will it help someone detect/triage a problem?
2) Could it otherwise be silently swallowed (async)?
3) Is it expected (don’t spam WARN/ERROR)?
4) Is the level appropriate (WARN vs ERROR)?
5) Does it include the key context needed to debug (ids/values)?
6) Does another function already log the same failure?
---
## Concurrency-Safe State Ownership
In code that runs across multiple concurrent requests/workers (OpenResty/Nginx), make state ownership and lifecycle explicit: use one writer/immutable shared snapshots, keep request/per-plugin state per-instance or per-request, and design timer/event flows to avoid race windows.
Apply this standard:
- **No shared mutable module state across configurations/requests**: any counter/buffer must live on the specific instance (per plugin config), not in a module-level closure shared by all `require()` users.
- **No cross-request mutation**: deep-copy config tables or other structures before mutating them inside request paths.
- **Request-bound uniqueness**: when using shared data structures (e.g., Redis ZSET members) under concurrency, include a per-request unique value (e.g., `ngx.var.request_id`) in the member.
- **Safe async/timer semantics**: when updates are asynchronous (timers, reload events), ensure correctness during the transition. Rebuild should “publish new then stop old” atomically, and tests should wait until the system is truly quiescent (not just after sending an event).
- **Avoid lock contention in hot paths**: shdict operations can lock; avoid frequent `shdict:get` in request-critical functions, or add worker-local TTL caching.
- **Avoid shared-variable execution-order races**: don’t use a process-local variable (like `all_services`) as a read/write bridge with workers; make the shared dict the source of truth and keep it immutable per update.
Example patterns:
```lua
-- 1) Per-request uniqueness in Redis ZSET members
local request_id = ngx.var.request_id
redis.call('ZADD', KEYS[1], now, request_id .. ':' .. i)
-- 2) Per-instance counter (conceptually)
local obj = {
total_pushed_entries = 0,
-- ... per-config buffers/state
}
-- 3) Avoid cross-request mutation
local checks = core.table.deepcopy(instance.checks)
-- mutate 'checks' safely
-- 4) Hot path: avoid locking shdict.get; use worker-local cache (conceptually)
-- local cached = cache:get(key) with TTL; only fall back to shdict on miss
```
Rule of thumb: if something can be observed/updated by more than one request concurrently, document its owner (which function/process writes), its lifecycle (when it can be reused), and its synchronization strategy (atomic publish, stop flags, immutable snapshots).
---
## Avoid Duplication, Extract Helpers
Keep code readable and maintainable by (1) extracting complex or phase-specific logic into dedicated helper functions, (2) removing duplicated logic/schema/label definitions in favor of shared helpers or a single source of truth, and (3) following existing project idioms/utilities to stay consistent.
How to apply:
- Extract when a function becomes long, heavily nested, or mixes concerns (e.g., operational logic vs logging/secondary phases). Create helpers like `log_phase_incoming(...)` and call them from the main path.
- Prevent drift-prone duplication: define label lists/schemas/paths once and reuse the same structure for both registration and value handling.
- Follow established conventions: use the existing utility functions for string operations (e.g., `core.string.find`), prefer the project’s standard concatenation/operator style (`..`), and use consistent response/header utilities (`core.response.set_header`).
- Scope refactors: do small, high-impact extractions/dedupes together, but avoid unrelated large structural changes in the same PR.
Example (helper extraction + phase separation):
```lua
local function log_phase_incoming_thread(premature, self, key, cost)
local conf = self.conf
local red, err = redis.new(conf)
if not red then
return red, err
end
return util.redis_log_phase_incoming(self, red, key, cost)
end
local function log_phase_incoming(self, key, cost, dry_run)
if dry_run then
return true
end
local ok, err = ngx_timer_at(0, log_phase_incoming_thread, self, key, cost)
if not ok then
core.log.error("failed to create timer: ", err)
return nil, err
end
return ok
end
function _M.incoming(self, key, cost, dry_run)
if get_phase() == "log" then
return log_phase_incoming(self, key, cost, dry_run)
end
-- main phase logic...
end
```
---
## Protocol phase correctness
When writing networking plugins/adapters, make behavior consistent with the request/stream lifecycle and the actual protocol/runtime semantics—then lock it with targeted regression tests.
Apply these rules:
1) Run auth/identity work in the correct phase for downstream lifecycle
- If other plugin outputs (e.g., Consumer/Consumer Group) must see the result, ensure the network call completes before the core merge point.
- If multiple plugins may attach the same identity, document the ordering/merge model and add a guard if conflicts are possible.
2) Don’t keep outdated or transport-specific protocol guards
- For H2/H3, implement body/read logic based on current runtime behavior (e.g., don’t block valid requests due to legacy Content-Length assumptions).
3) Streaming must be event-correct (one-shot + EOF/terminal events)
- Gate “scan/replace/release” logic so it executes exactly once per response (especially when protocol converters emit multiple terminal events).
Example (one-shot release pattern):
```lua
-- before buffering/replacing chunks
if not ctx.lakera_response_released then
ctx.lakera_response_released = false
end
-- on any terminal condition that indicates end-of-stream assembly
if ctx.lakera_response_released == false then
ctx.lakera_response_released = true
-- scan+release (or deny) exactly once
end
```
4) Avoid hardcoding transport assumptions; make scheme/endpoint configurable
- Don’t hardcode `https://` if deployments/tests may use plain HTTP (or configure an override similar to other managers).
5) Centralize forwarded address/host handling; fix at the root cause
- If the platform already normalizes `X-Forwarded-*`, reuse that canonical form rather than duplicating trust/untrust branching across features.
6) Connection lifecycle: use keepalive pooling and treat abort hooks as singletons
- Prefer `connect -> request -> set_keepalive` to avoid per-call TCP overhead.
- If you use `ngx.on_abort`, document that it’s a single registration per request and ensure this endpoint/plugin lifecycle is dedicated or otherwise guarded.
Always add targeted tests around the networking edge you’re touching: H2/H3 body handling, streaming duplication/drop scenarios (with converters), forwarded-host/redirect behavior, and TLS vs non-TLS transport expectations.
---
## Deterministic, scoped CI
CI jobs that build artifacts must be deterministic and guarded, and CI tests must be scoped to avoid unnecessary heavy work.
**Apply these rules**
1) **Guard CI assumptions (fail loudly):** If a build-time tweak is required (e.g., removing -march=native leakage), make the script error when the expected input/state isn’t found—never allow a “no-op” edit that silently produces a different binary.
2) **Keep scripts portable and version-stable:** Use portable tooling options (e.g., sed -i.bak) and pin dependency/build versions so pattern matches don’t break unexpectedly.
3) **Avoid rebuilding heavyweight dependencies in-line:** Prefer prebuilt images/artifacts, caching, or reusing a prior build.
4) **Scope expensive tests by change set:** Move costly jobs (like Docker image build + integration runs) into separate workflows/jobs and run them only when relevant files change.
**Example: fail loudly + portable edit (bash)**
```bash
set -euo pipefail
# ... obtain/extract source at a pinned version ...
file="CMakeLists.txt"
needle='add_compile_options(-march=native)'
# Portable in-place edit with backup, and verify the line existed.
if ! grep -qF "${needle}" "${file}"; then
echo "Expected line not found: ${needle} (refusing to build native-leaking artifact)" >&2
exit 1
fi
sed -i.bak "/${needle//\//\\\/}/d" "${file}"
```
**Example: run expensive workflow only when relevant paths change (GitHub Actions)**
```yaml
on:
push:
paths:
- 'ops.lua'
- 'docker-entrypoint.sh'
- 't/cli/test_standalone_docker.sh'
- 'ci/**'
```
This standard prevents silent build drift and keeps pipelines fast by doing the minimum necessary work per change.
---
## Consistent Error Propagation
When handling failures, choose behavior intentionally: either propagate a real error in a consistent format, or gracefully degrade only for *explicitly non-error* cases (e.g., notifications, permission edge cases). Avoid masking, asserting, or continuing after validation/parsing fails.
Apply:
- **Never silently continue after an invalid input parse/match.** If a header/path/config is invalid, either `return nil, err` (or an appropriate response) or explicitly default while logging.
- **Use consistent error return contracts:** prefer `return nil, err` for failure; avoid returning booleans where callers expect `nil, err`.
- **Don’t use `assert` for expected client/invalid-data scenarios.** Return an error response / `nil, err` instead, so failures become controlled.
- **If you must use `pcall` for environment/phase constraints, handle failures explicitly** (e.g., separate “pcall failed due to missing subsystem” from “real operational error”). Don’t let `pcall` collapse meaningful errors into success paths.
- **Match error handling to context** (HTTP vs stream/subsystem; notification vs request).
Example (Lua error contract + explicit fallback):
```lua
local function get_context(headers)
local trace_id = headers["x-instana-t"]
if not trace_id then return nil end
local parsed = trace_id:match("^(%x+)")
if not parsed then
-- invalid input: don't proceed with raw value
return nil, "x-instana-t header invalid"
end
return parsed
end
-- usage
local trace_id, err = get_context(ngx.req.get_headers())
if err then
ngx_log(ngx.WARN, err)
return nil -- or propagate: return nil, err
end
```
Use logging only when it’s part of the chosen error-handling policy (e.g., non-fatal notification missing handler), and keep error strings consistently formatted (e.g., lowercase-leading).
---
## Verify Download Integrity
When your code/CI downloads third-party binaries or packages and then installs them, verify integrity before installation (preferably SHA256/SHA256+signature). Store the expected checksum in versioned configuration keyed by the artifact/runtime version, and update it whenever you bump that version. Fail closed on mismatch.
Example (pattern):
```sh
# expected SHA256 for this APISIX_RUNTIME lives in versioned config (.requirements)
APISIX_RUNTIME="${APISIX_RUNTIME}"
EXPECTED_SHA256="$(lookup_expected_sha256_for_runtime "$APISIX_RUNTIME")"
RELEASE_URL=".../${APISIX_RUNTIME}..."
DEB_NAME="..."
TMP_PATH="/tmp/$DEB_NAME"
wget --no-verbose --tries=3 --retry-connrefused "$RELEASE_URL" -O "$TMP_PATH"
ACTUAL_SHA256="$(sha256sum "$TMP_PATH" | awk '{print $1}')"
if [ "$ACTUAL_SHA256" != "$EXPECTED_SHA256" ]; then
echo "Checksum mismatch for $DEB_NAME" >&2
exit 1
fi
sudo apt-get install -y "$TMP_PATH"
rm -f "$TMP_PATH"
```
This prevents supply-chain/tampering attacks from being converted into installed code, and ensures upgrades remain secure by forcing explicit hash updates during runtime bumps.
---
## Fail-fast artifact downloads
For required build/CI artifacts, make the reference configurable (with a sensible default) and fetch them with fail-fast settings so HTTP errors, missing files, or bad refs stop the build immediately.
Apply this rule by:
- Defining the artifact ref via an environment variable with a fallback.
- Using `curl -fsSL` for downloads (fail on HTTP errors, show errors, follow redirects as needed), and avoid commands that allow silent/partial failures.
Example pattern:
```sh
APISIX_BUILD_TOOLS_REF="${APISIX_BUILD_TOOLS_REF:-apisix-runtime/${APISIX_RUNTIME}}"
curl -fsSL -o /usr/local/openresty/openssl3/ssl/openssl.cnf \
"https://raw.githubusercontent.com/api7/apisix-build-tools/${APISIX_BUILD_TOOLS_REF}/conf/openssl3/openssl.cnf"
```
This improves error handling by ensuring failure scenarios (missing artifact, incorrect ref, HTTP 404/500) are detected and propagated immediately rather than producing misleading downstream errors.
---
## Config Contract Accuracy
Ensure configuration documentation and validation rules match the real runtime contract: types/structures, default values, actual scope, and when validation happens.
Apply these checks to every configurable field:
1) **Type/shape must support the operational use-case**
- If the setting naturally represents multi-dimensional filtering or staged rollouts, document/implement it as a multi-value structure (e.g., arrays) rather than forcing single-string workarounds.
```json
// Prefer multi-value matching to support canary/prod-blue/prod-green without extra keys
"discovery_args": {
"metadata_match": {
"env": ["canary", "prod-blue", "prod-green"],
"version": ["v1", "v2"]
}
}
```
2) **Be explicit about validation bypass vs runtime resolution**
- If config loading bypasses schema constraints due to secret/env reference resolution, state it clearly and rely on runtime validation after resolution.
```text
Use $secret://... or $env://... in plugin string fields.
Schema constraints apply to the resolved value at runtime, not during config loading.
```
3) **Document true blast radius (shared/core toggles)**
- If a configuration value is implemented via a shared core helper used by multiple plugins/features, document that it impacts all of them—do not scope it to the feature name in the doc.
4) **Align documented defaults with code**
- Verify every documented default equals the implementation default (including nested/batch helper defaults). If other components already fixed mismatches, update the remaining ones the same way.
This prevents configuration drift, misleading docs, and rollout-time surprises—especially for environment-specific settings and feature flags.
---
## Secure examples correctness
When implementing or documenting security-related plugins/features, ensure examples are both *secure* and *operationally correct*: avoid leaking sensitive data, match cookie/transport settings, use the correct authentication header formats, and ensure authentication happens before authorization/restriction.
Apply these rules:
- **Redact/flag sensitive inputs**: If a feature can forward request bodies or headers (e.g., `with_body`), explicitly warn that it may contain secrets (passwords/API keys) and ensure the option is used only when safe.
- **Match Secure transport semantics**: If cookies/sessions are configured with `secure=true`, examples must use **HTTPS** or explicitly set `secure=false` for local HTTP testing.
- **Use correct auth header scheme**: For bearer tokens, always set `Authorization: Bearer ` (not just the raw token).
- **Auth before authz**: Authorization/restriction logic must run only after the identity is resolved by an authentication plugin; examples should configure auth (e.g., `key-auth`) so the Consumer is determined before applying restriction rules.
Example (Bearer token correctness):
```sh
curl -i "http://127.0.0.1:9080/get" \
-H "Authorization: Bearer ${john_jwt_token}"
```
Example (Secure cookie guidance):
- For **HTTPS** examples: keep `cookie.secure=true`.
- For **HTTP** local testing: set `cookie.secure=false` or switch the example to HTTPS.
Example (auth-before-restriction):
- Configure an authentication plugin (e.g., `key-auth`) so the gateway can resolve the Consumer, then apply `consumer-restriction` based on that resolved identity.
---
## API contract consistency
When defining or documenting APIs/plugins, ensure the declared contract matches how the system actually resolves requests and config fields. Validate examples and client expectations against these checks:
1) Route matching must cover the real request path
- If users will request `/prefix/suffix`, don’t configure only `/prefix`; use `/prefix/*` (or the equivalent wildcard/prefix controller syntax).
2) Request body/encoding must match extraction rules
- If a config uses `$post_arg.`, the request must send form-style POST args (typically `application/x-www-form-urlencoded`).
- If the client sends JSON, you must either switch the approach to JSON extraction (where supported) or change the example to form encoding.
Example (consistent with `$post_arg.tenant_id`):
```sh
curl -i "http://127.0.0.1:9080/post" -X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d 'tenant_id=000'
```
3) Keep API config field types aligned with upstream/integration contracts
- Prefer the simplest type that matches what upstream systems naturally provide (e.g., `string:string` metadata).
- If you must support multiple shapes later, introduce a documented union (e.g., `string|string[]`) rather than silently mixing incompatible formats.
4) Use the correct framework primitives/wiring
- For request mutation, prefer the dedicated setter APIs (e.g., setting URI args via `core.request.set_uri_args`) rather than relying on side effects.
- For interface integrations (e.g., Gateway API), use the correct extension/wiring pattern for that API surface.
Adopt this as a “pre-merge” checklist item for any API-facing documentation or examples: run through the exact request path and encoding, confirm the resolved variables/fields, and ensure the config schema types reflect the real integration contract.
---
## Docs Match Implementation
Docs must be verifiable against the actual plugin/runtime behavior: schemas (fields/types/requiredness), defaults, and example outputs. Additionally, follow the repo’s established doc formatting conventions for things like canonical tags and secret-value prefixes.
Apply this standard as a pre-merge checklist:
- Schema accuracy: ensure every documented config key exists in the plugin schema and has correct type/valid-values.
- If a field isn’t user-configurable (even if set internally), don’t document it as an input (e.g., don’t advertise `field.type` for `elasticsearch-logger` if only `field.index` is supported).
- Defaults accuracy: if a plugin relies on shared batch-processor defaults, the docs must match the shared default (e.g., don’t claim `max_retry_count=60` when code defaults to `0`).
- Table semantics: keep “Required” as a boolean; move conditional prose into the “Description” column.
- Behavior-faithful examples: example request/response transformations must match real behavior (e.g., regex-based URI rewrites must use patterns that yield exactly what the docs claim, given the runtime replace/match semantics).
- Executable examples: code samples must fully demonstrate the behavior being tested (e.g., streaming handlers must include `data/end/error`, not only metadata).
- Formatting conventions: keep canonical-link markup and other doc wrappers consistent with the rest of the documentation set; use the documented secret prefix conventions (e.g., `$env://...` / `$secret://...`).
Quick example (schema-vs-docs):
```json
// Good: only document fields that the schema actually accepts.
{
"elasticsearch-logger": {
"field": {
"index": "gateway" // documented + schema-backed
// DO NOT document "type": "logs" if not accepted by the schema
}
}
}
```
Quick example (behavior-faithful rewrite):
- If the runtime only replaces the matched part of the upstream URI, the documented example must use a regex that consumes the segments required to produce the stated final path; otherwise the doc is incorrect.
---
## Trace semconv and completeness
Make observability outputs standards-compliant and fully observable.
Apply this when writing instrumentation and when publishing tracing/telemetry examples:
1) **Validate semantic conventions**: For HTTP-related telemetry, ensure attributes conform to the OpenTelemetry HTTP semantic conventions (semconv). If you have older non-compliant attributes, you may keep them (deprecated/legacy), but **add new compliant attributes** so downstream analysis remains correct.
2) **Handle the complete signal in examples**: Code samples that demonstrate telemetry must log/handle the primary emitted data and lifecycle events—at minimum **data** plus **end** (and **error**), not just headers/metadata.
Example (stream handling in an observability-oriented gRPC-Web example):
```js
const stream = client.lotsOfReplies(req, {});
stream.on('metadata', (metadata) => {
console.log('Response headers:', metadata);
});
stream.on('data', (response) => {
console.log('Reply:', response.getReply());
});
stream.on('end', () => {
console.log('Stream ended');
});
stream.on('error', (err) => {
console.error('Error:', err);
});
```
Example (semantic convention compliance principle):
- When your trace/log sample shows HTTP attributes that don’t match the http semconv registry, add the correct semconv-aligned attribute(s) (and keep legacy ones if needed), so observability tooling can reliably interpret fields.
---
## Self-Contained Secure Networking
Ensure networking-related docs/examples and configurations are both runnable and secure: (1) every referenced endpoint/service/backend in an example manifest must be defined so the config works when copied, and (2) TLS-related defaults (e.g., certificate verification) must default to secure behavior and be treated as potentially breaking—clearly documented/announced when changing defaults.
Example (Gateway API backend wiring, self-contained):
```yaml
apiVersion: v1
kind: Service
metadata:
namespace: aic
name: httpbin-external-domain
spec:
type: ExternalName
externalName: httpbin.org
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
namespace: aic
name: authz-keycloak-route
spec:
parentRefs:
- name: apisix
rules:
- matches:
- path:
type: Exact
value: /anything
backendRefs:
- name: httpbin-external-domain
```
Example (secure TLS verification default, explicit in config):
```yaml
plugins:
- name: openid-connect
config:
ssl_verify: true # keep secure default; if changing this default, announce as breaking
```
Practical checklist:
- Docs/manifests: verify every `backendRefs.name` (or host) has a corresponding `Service`/DNS target in the same example set.
- Networking security: when TLS verification/scheme defaults change, mark as breaking in changelog and ensure templates/docs show the effective default (`ssl_verify: true`) explicitly.
---
## prioritize code clarity
Write code that prioritizes readability and explicitness over brevity. This includes using explicit type conversions instead of implicit ones, extracting magic values to named constants, creating helper functions for repetitive operations, and organizing code logic clearly.
Key practices:
- Use explicit conversions like `B256::from(raw_slot)` instead of `raw_slot.into()` for clarity
- Extract hardcoded values to named constants: `const CODE_OK: u32 = 0;` instead of inline `0`
- Create helper functions for repetitive operations rather than duplicating complex logic
- Use direct, simple approaches like `.map()` instead of `.and_then(|s| Some(s))`
- Pull complex conditional logic out of control flow guards for better readability
- Prefer `.is_ok()` over pattern matching `Ok(_)` when the value isn't used
Example of improving clarity:
```rust
// Before: implicit conversion and magic number
let raw_slot: B256 = raw_slot.into();
if tx.tx_result.code == 0 {
// After: explicit conversion and named constant
const CODE_OK: u32 = 0;
let raw_slot: B256 = B256::from(raw_slot);
if tx.tx_result.code == CODE_OK {
```
This approach makes code more maintainable, reduces cognitive load for reviewers, and prevents subtle bugs from unclear operations.
---
## Use descriptive semantic names
Choose names that clearly communicate purpose, intent, and functionality rather than generic or abbreviated alternatives. Names should follow Rust conventions (snake_case for variables, functions, modules) and accurately describe what they represent or do.
Key principles:
- Use descriptive field names: `cw20_impl` instead of `cw20_base`
- Method names should reflect their actual behavior: `GetStatusCommitment` instead of `GetCommittedStatus` when returning a hash commitment
- Follow Rust naming conventions: `consensus_state_bytes` not `consensusStateBytes`
- Use proper types with semantic names: `Address` and `B256` instead of generic `&[u8]`
- Choose meaningful type aliases: avoid generic names like `SharedMap` without context
Example:
```rust
// Poor naming
pub fn new_beacon_light_client_update() -> BeaconUpdate { ... }
pub const UNION_IBC: &str = "union:union-ibc";
struct MsgCreateClient {
bytes consensusStateBytes; // camelCase, unclear
}
// Better naming
pub fn into_beacon_light_client_update() -> BeaconUpdate { ... }
pub const UNION_IBC: &str = "union:ibc-union";
struct MsgCreateClient {
bytes consensus_state_bytes; // snake_case, clear
}
```
Names are the primary way developers understand code intent - invest in clarity over brevity.
---
## YAML Message Folding
When writing YAML string fields intended for one-line or sentence-like messages, prefer folded block scalars (`>`) so embedded newlines render as spaces. Use literal block scalars (`|`) only when you explicitly need to preserve line breaks.
Example:
```yaml
# Fold newlines into spaces (recommended for sentence-style messages)
message: >
Fix TCP error
with updated restriction handling
# Preserve line breaks exactly
message: |
Fix TCP error
with updated restriction handling
```
If you see changelog entries using `|` where the message should read as a single paragraph, switch to `>` to match the intended formatting.
---
## Ensure comprehensive test coverage
All new functionality must include corresponding tests that verify both success and failure scenarios. When adding new functions or modifying existing behavior, write tests that cover the main functionality as well as edge cases and error conditions.
Key requirements:
- New functions should have dedicated tests (like the `execute_burn` function that "needs to be tested to ensure it works correctly")
- Test edge cases and validation logic (such as "sync committee bits vector length is checked correctly")
- Include both positive and negative test cases to ensure proper error handling
- Avoid deploying untested code to production environments
Example of comprehensive test coverage:
```rust
#[test]
fn execute_burn_works() {
// Test successful burn operation
let result = execute_burn(deps, env, info, amount);
assert!(result.is_ok());
}
#[test]
fn execute_burn_fails_with_invalid_amount() {
// Test edge case with invalid input
let result = execute_burn(deps, env, info, Uint128::zero());
assert!(result.is_err());
}
#[test]
fn validate_sync_committee_bits_length() {
// Test vector length validation
let mut update = valid_update.clone();
update.sync_aggregate.sync_committee_bits.clear();
assert!(validate_update(&update).is_err());
}
```
This practice prevents issues from reaching production and ensures code reliability through thorough validation of all code paths.
---
## Document compatibility flags comprehensively
All compatibility flags must include comprehensive documentation that clearly explains their purpose, behavior, timing, and relationships with other flags. This documentation should follow a consistent format and provide sufficient context for developers to understand the flag's impact.
Required documentation elements:
- Clear description of what the flag enables or disables
- Explanation of when the flag takes effect (dates, conditions)
- Relationships with other flags (mutual exclusivity, dependencies, implications)
- Impact on existing functionality and backward compatibility
Example of proper flag documentation:
```
removeNodejsCompatEOLv22 @117 :Bool
$compatEnableFlag("remove_nodejs_compat_eol_v22")
$compatDisableFlag("add_nodejs_compat_eol_v22")
$impliedByAfterDate(name = "removeNodejsCompatEOL", date = "2027-04-30");
# Removes APIs that reached end-of-life in Node.js 22.x. When using the
# removeNodejsCompatEOL flag, this will default enable on/after 2027-04-30.
```
For complex flag relationships, document dependencies explicitly:
```
# Requires both "enable_nodejs_http_modules" and "enable_nodejs_http_server_modules"
# to be enabled. The type stripping flag is mutually exclusive and will take
# precedence if both happen to be defined.
```
This ensures developers understand flag behavior, prevents configuration errors, and maintains consistency across the codebase.
---
## Node.js API compatibility
When implementing Node.js-compatible APIs, ensure exact behavioral matching with Node.js, including export structures, method signatures, return types, and property availability. This maintains compatibility with existing Node.js code and meets developer expectations.
Key areas to verify:
- **Default exports**: Match Node.js module export patterns (e.g., `node:module` should export `Module` as default)
- **Method availability**: Implement expected methods even as no-ops to prevent runtime errors (e.g., `server.address().port` for logging code)
- **Property structures**: Ensure objects have the same shape and property names as Node.js equivalents
- **Version-specific behavior**: Use appropriate compatibility flags to match Node.js version behavior (e.g., deprecated APIs exported as `undefined` in newer versions)
Example from the discussions:
```typescript
// Correct: Match Node.js default export expectation
export default Module; // Instead of object with methods
// Correct: Provide expected methods even if not fully implemented
server.address(): AddressInfo | string | null {
return { port: this.port, family: 'IPv4', address: '0.0.0.0' };
}
// Correct: Use version-appropriate compatibility flags
if (!Cloudflare.compatibilityFlags.remove_nodejs_compat_eol_v22) {
// Export as undefined in v22 to match Node.js behavior
}
```
This ensures seamless migration of existing Node.js applications and prevents unexpected runtime failures due to missing properties or methods.
---
## compatibility flag consistency
Ensure compatibility flags follow consistent naming conventions, use explicit typing, and maintain proper usage patterns throughout the codebase. Compatibility flags should use descriptive, version-specific names that accurately reflect their purpose and lifecycle.
**Naming Convention:**
- Use systematic versioning for EOL flags (e.g., `remove_nodejs_compat_eol_v22` for even releases)
- Follow hierarchical flag relationships where odd-numbered versions are implied by the next even-numbered version
- Use specific flag names rather than generic terms (e.g., `jsWeakRef` instead of "a specific flag")
**Type Safety:**
- Define explicit interfaces for compatibility flags rather than using generic `Record`
- Consider auto-generating flag definitions from source files to avoid manual maintenance
- Use `Cloudflare.compatibilityFlags` consistently instead of alternative approaches
**Documentation:**
- Document flag interactions and dependencies, especially when flags affect each other
- Include examples showing which flags should or should not be used together
- Clearly state when flags are intentionally omitted and provide alternatives
**Example:**
```typescript
// Good: Explicit flag usage with clear naming
if (!Cloudflare.compatibilityFlags.remove_nodejs_compat_eol_v22) {
// Implementation for Node.js compatibility
}
// Good: Document flag interactions
// Note: The disallow_importable_env flag should NOT be set
// when using this feature as it prevents env access
```
This ensures configuration management remains maintainable, predictable, and well-documented as the system evolves.
---
## JSDoc documentation standards
All public functions and complex code should have proper JSDoc documentation. Functions must include clear descriptions of their purpose, parameters, and return values. Ensure JSDoc comments are accurate, well-formatted, and kept up-to-date with code changes.
For JSDoc formatting:
- Use backticks around code references like `worker-configuration.d.ts`
- Keep descriptions concise but complete
- Update documentation when functionality changes
Example of proper JSDoc:
```typescript
/**
* Unified function to handle binding name validation, prompting, and config updates
* for all resource creation commands. This eliminates code duplication across
* KV, D1, R2, Vectorize, and Hyperdrive commands.
*
* @param args - Configuration arguments including optional binding name and environment
* @param config - Raw configuration object with optional config path
* @param resource - Resource binding information
*/
export async function handleResourceBindingAndConfigUpdate(
args: { configBindingName?: string; env?: string },
config: RawConfig & { configPath?: string },
resource: ResourceBinding
): Promise
```
Additionally, add explanatory comments for non-obvious code logic, complex algorithms, or when the purpose isn't immediately clear from the code itself.
---
## avoid error display duplication
When using thiserror for error handling, avoid displaying source errors in both the error message and the source attribute, as this creates duplicated error messages when printing the full error trace.
**The Problem:**
Using `#[from]` (which sets the source) while also including the error in the display message causes the same error to appear twice in error traces.
**Bad Example:**
```rust
#[derive(Debug, thiserror::Error)]
pub enum Error {
#[error("database error creation transaction for dependency {0}: {1}")]
CreateTransaction(AbiDependency, #[source] sqlx::Error),
}
```
**Good Examples:**
```rust
// Option 1: Use #[source] without displaying the error
#[derive(Debug, thiserror::Error)]
pub enum Error {
#[error("database error creation transaction for dependency {0}")]
CreateTransaction(AbiDependency, #[source] sqlx::Error),
}
// Option 2: Use #[from] for automatic conversion (implies #[source])
#[derive(Debug, thiserror::Error)]
pub enum Error {
#[error("database error creation transaction for dependency {0}")]
CreateTransaction(AbiDependency, #[from] sqlx::Error),
}
// Option 3: Use #[error(transparent)] to pass through the source error entirely
#[derive(Debug, thiserror::Error)]
pub enum Error {
#[error(transparent)]
Database(#[from] sqlx::Error),
}
```
**Key Rule:** Either set the source OR print it in display, but not both. The error chain will handle displaying source errors when the full trace is printed.
---
## Respect automated tooling
Avoid manually updating files or configurations that are managed by automated CI/CD tools. Many modern development workflows rely on automated systems like dependabot for dependency updates, changesets for version management, and other tools for consistent builds and releases.
Manual interventions can break these automated processes and create inconsistencies across packages or deployments. Instead of manually editing these managed files, use the proper channels provided by the automation tools.
Examples of what to avoid:
- Manually updating dependency versions in package.json when dependabot manages them
- Manually bumping version numbers in package.json when using changesets for release management
- Bypassing established automated workflows for critical CI/CD processes
When you need to make changes that affect automated tooling, first understand how the automation works and whether there's a proper way to achieve your goal through the automated system rather than working around it.
---
## Configuration validation messages
Ensure configuration validation provides clear, actionable error messages that guide users toward correct configuration. Validation should be comprehensive, checking not only types but also value ranges, logical consistency, and edge cases like undefined vs explicitly set values.
When validating configuration:
- Provide specific error messages that include the expected format and actual received value
- Include examples of valid configuration when possible
- Handle edge cases like undefined values explicitly rather than assuming they're equivalent to false/empty
- Validate logical consistency between related configuration options
- Use consistent error message formatting across the codebase
Example of good validation:
```typescript
if (typeof rolloutStep === "number") {
const allowedSingleValues = [5, 10, 20, 25, 50, 100];
if (!allowedSingleValues.includes(rolloutStep)) {
diagnostics.errors.push(
`"containers.rollout_step_percentage" must be one of [5, 10, 20, 25, 50, 100], but got ${rolloutStep}`
);
}
} else if (Array.isArray(rolloutStep)) {
// Validate array elements and their sum
const sum = rolloutStep.reduce((acc, step) => acc + step, 0);
if (sum !== 100) {
diagnostics.errors.push(
`"containers.rollout_step_percentage" array elements must sum to 100, but values summed to "${sum}"`
);
}
} else {
diagnostics.errors.push(
`"containers.rollout_step_percentage" should be an array of numbers or a single number, but got ${JSON.stringify(rolloutStep)}`
);
}
```
This approach helps users understand exactly what went wrong and how to fix their configuration, reducing support burden and improving developer experience.
---
## prioritize code clarity
Write code that prioritizes readability and clarity over minor optimizations or clever shortcuts. When faced with choices between concise but obscure code and more explicit but readable code, choose readability.
Key principles:
- Avoid unnecessary operators or shortcuts that don't improve clarity (e.g., `!!` when a simple boolean check suffices)
- Structure functions with clear control flow - prefer early returns and explicit else clauses when they improve readability
- Add explanatory comments for non-obvious behavior, especially when preserving legacy behavior or making design tradeoffs
- Eliminate code duplication through helper functions rather than copy-paste
- Remove unnecessary code entirely rather than leaving empty implementations
Example of applying this principle:
```cpp
// Less clear - uses unnecessary !! operator
if (!!requireEsm) {
// ...
}
// More clear - direct boolean check
if (requireEsm) {
// ...
}
// Less clear - complex nested logic
ptr->setModuleRegistry(([&]() -> kj::Own {
KJ_IF_SOME(newModuleRegistry, options.newModuleRegistry) {
return JSG_WITHIN_CONTEXT_SCOPE(js, context, [&](jsg::Lock& js) {
return newModuleRegistry.attachToIsolate(js, compilationObserver);
});
}
return ModuleRegistryImpl::install(isolate, context, compilationObserver);
})());
// More clear - explicit else clause for readability
ptr->setModuleRegistry(([&]() -> kj::Own {
KJ_IF_SOME(newModuleRegistry, options.newModuleRegistry) {
return JSG_WITHIN_CONTEXT_SCOPE(js, context, [&](jsg::Lock& js) {
return newModuleRegistry.attachToIsolate(js, compilationObserver);
});
} else {
return ModuleRegistryImpl::install(isolate, context, compilationObserver);
}
})());
```
Remember: code is read far more often than it's written. Optimize for the reader, not the writer.
---
## Validate production configurations
Always validate configuration values and ensure production safety by avoiding hardcoded values, implementing proper defaults, and requiring explicit configuration for production-critical settings. Configuration should be validated at runtime to prevent deployment of incorrect values.
Key practices:
- Use placeholder variables instead of hardcoded addresses or tokens: `$CONTRACT_ADDRESS` instead of specific addresses
- Make production-critical configurations required rather than optional with unsafe defaults: "required BC the default is intended for local devnet scenarios, and is not viable for production"
- Validate configuration constraints: "The `path` field in the packet must be zero for staking operations. The staked token must match the governance token configured for the channel"
- Verify configuration values are correct: ensure constants like `keccak256("wasm")` vs just `"wasm"` are accurate
- Test configuration updates safely before deployment, especially for dependency versions
Example:
```rust
// Bad - hardcoded production address
contract_addr: "union1m87a5scxnnk83wfwapxlufzm58qe2v65985exff70z95a2yr86yq7hl08h"
// Good - configurable with validation
contract_addr: env::var("CONTRACT_ADDRESS")
.expect("CONTRACT_ADDRESS must be set for production")
```
This prevents production footguns and ensures configurations are explicit, validated, and safe for deployment.
---
## workspace dependency consistency
All internal project dependencies should use workspace configuration instead of direct path or git references to ensure consistent versioning and build behavior across the monorepo. Maintain the standard `{ workspace = true }` syntax format and avoid redundant configuration options when using workspace dependencies.
When adding new internal dependencies, always check if they can be configured in the workspace root and referenced consistently. Avoid specifying `default-features = false` or other options that may conflict with workspace-level configuration.
Example of correct workspace dependency usage:
```toml
[dependencies]
# Correct - uses workspace configuration
ibc-events = { workspace = true }
unionlabs = { workspace = true }
# Incorrect - direct path reference
# ibc-events = { version = "0.1.0", path = "../ibc-events" }
# Incorrect - direct git reference
# sui_sdk = { git = "https://github.com/mystenlabs/sui", package = "sui-sdk" }
# Incorrect - redundant configuration with workspace
# unionlabs = { workspace = true, default-features = false }
```
This approach centralizes dependency management, reduces configuration drift, and ensures all modules use compatible versions of shared dependencies.
---
## optimize CI resource usage
{% raw %}
Design CI workflows to maximize resource efficiency by reusing build artifacts across jobs whenever possible, while carefully evaluating when separate builds are truly necessary. Before creating duplicate build jobs, assess whether different compilation flags or configurations genuinely require separate builds, or if the same artifacts can be reused with additional steps.
Consider these strategies:
- Reuse existing job artifacts for additional testing or analysis steps
- Evaluate whether custom build configurations justify separate jobs
- Use larger runners when build duplication is unavoidable to reduce overall duration
- Take incremental approaches to dependency updates to maintain stability
Example from workflow optimization:
```yaml
# Instead of separate benchmark build job
- name: Build benchmarks
run: bazel build ${{ env.BAZEL_ARGS }} //src/workerd/tests:all_benchmarks
# Consider reusing existing build artifacts:
- name: Run benchmarks
uses: existing-build-artifacts
run: ./run-benchmarks-on-existing-binary
```
This approach reduces CI costs, improves pipeline efficiency, and minimizes resource waste while ensuring all build requirements are met.
{% endraw %}
---
## proper span lifecycle management
Ensure spans are properly created, attached to async operations, and reported at appropriate times to maintain accurate tracing data. Spans that are not properly managed will result in incorrect durations, missing trace data, or unreliable observability metrics.
Key practices:
1. **Attach spans to promises**: For JSG methods returning promises, use `context.attachSpans()` to ensure spans remain active for the duration of the async operation
2. **Report events promptly**: Avoid deferring trace event reporting to destructors or cleanup phases where timing information may be stale
3. **Maintain span context**: Pass trace context through call chains to prevent spans from falling out of scope prematurely
Example of correct span attachment:
```cpp
jsg::Promise> DurableObjectStorageOperations::get(jsg::Lock& js,
kj::OneOf> keys,
jsg::Optional maybeOptions) {
auto& context = IoContext::current();
auto userSpan = context.makeUserTraceSpan("durable_object_storage.get"_kjc);
// Correct: attach span to promise to maintain lifecycle
return context.attachSpans(js, getOne(js, kj::mv(s), options), kj::mv(userSpan));
}
```
Avoid patterns where spans immediately fall out of scope or where trace events are reported with stale timing information, as this compromises the accuracy and usefulness of observability data.
---
## minimize memory operations
Avoid unnecessary memory allocations, copies, and inefficient memory usage patterns that can impact performance. This includes several key practices:
**Avoid unnecessary allocations:**
- Use static allocation instead of heap allocation when possible: `static NullIoStream globalNullStream;` instead of `static auto globalNullStream = kj::heap();`
- Avoid intermediate string copies: prefer direct construction over `kj::str(...)` when the result is immediately wrapped
**Optimize parameter passing:**
- Use const references for non-trivial types to prevent copies: `const tracing::TraceId& traceId` instead of `tracing::TraceId traceId`
- Use move semantics appropriately, but be aware that explicit `kj::mv()` can interfere with NRVO (Named Return Value Optimization)
**Pre-allocate when size is known:**
```cpp
// Instead of letting vector grow dynamically
kj::Vector> promises;
// Reserve space when size is known
promises.reserve(filenames.size());
```
**Choose efficient memory usage patterns:**
- Pump data to null streams instead of buffering in memory when data will be discarded: avoid `readAllBytes()` that buffers unnecessarily
- Use more efficient construction methods: `kj::Path({"tmp"})` instead of `kj::Path::parse("tmp")`
These optimizations are particularly important in hot paths or when processing large amounts of data, as small inefficiencies can compound significantly.
---
## Format observability test data
When writing tests for observability systems (tracing, metrics, logging), structure test assertions to be easily readable and debuggable. Instead of placing complex JSON outputs or structured data on single lines, split them across multiple lines with proper formatting.
This approach significantly improves the debugging experience when tests fail, as diff outputs clearly show which specific parts of the observability data don't match expectations. For example, instead of:
```javascript
let expected = [
'{"type":"onset","executionModel":"stateless","scriptTags":[],"info":{"type":"custom"}}{"type":"spanOpen","name":"fetch","parentSpanId":"0"}{"type":"spanClose","outcome":"ok"}{"type":"outcome","outcome":"ok","cpuTime":0,"wallTime":0}'
];
```
Format it as:
```javascript
let expected = [
`{"type":"onset","executionModel":"stateless","scriptTags":[],"info":{"type":"custom"}}
{"type":"spanOpen","name":"fetch","parentSpanId":"0"}
{"type":"attributes","info":[{"name":"http.request.method","value":"POST"}]}
{"type":"spanClose","outcome":"ok"}
{"type":"outcome","outcome":"ok","cpuTime":0,"wallTime":0}`
];
```
This formatting makes future instrumentation changes much easier to inspect and produces clear, line-by-line diff outputs when assertions fail, allowing developers to quickly identify exactly which observability events or attributes are incorrect.
---
## isolate lock safety
Always ensure proper isolate lock management and thread-safe access patterns when working with JavaScript contexts and cross-thread operations. Accessing JSG objects, IoContext, or V8 handles without holding the isolate lock leads to undefined behavior and crashes.
Key requirements:
1. **Use explicit capture lists** in async lambdas instead of `[&]` - reference capture is only safe for synchronous execution
2. **Use `ctx.run()` for isolate entry** - manually acquiring locks misses critical setup like setting current IoContext and honoring input locks
3. **Capture weak references for cross-thread access** - use `IoContext::current().getWeakRef()` and check validity before accessing
4. **Avoid blocking I/O in sync functions** - use proper async patterns instead of `.wait()` or threads
5. **Mark thread-sensitive resources clearly** - use concrete names like `ownContentIsRpcResponse` to indicate thread affinity requirements
Example of unsafe vs safe patterns:
```cpp
// UNSAFE: Reference capture in async lambda
return context.awaitIo(js, kj::mv(promise), [&](jsg::Lock& js, kj::String text) mutable {
// [&] is unsafe when lambda executes asynchronously
});
// SAFE: Explicit capture list
return context.awaitIo(js, kj::mv(promise), [context = &context](jsg::Lock& js, kj::String text) mutable {
// Explicit capture is safe
});
// UNSAFE: Manual isolate lock without proper context
auto lock = co_await ctx.getWorker()->takeAsyncLockWithoutRequest(nullptr);
// SAFE: Use ctx.run() for proper isolate entry
co_await ctx.run([](Worker::Lock& lock) {
// Proper context setup with IoContext, input locks, etc.
});
```
This prevents data races, use-after-free bugs, and ensures proper resource lifecycle management across thread boundaries.
---
## Prioritize descriptive naming
Choose clear, self-explanatory names that prioritize readability over brevity. Avoid abbreviations, obscure identifiers, and names that require domain knowledge to understand. Names should be immediately comprehensible to newcomers and future maintainers.
Key principles:
- Expand abbreviations to full words (e.g., `toNetworkOrderHex()` instead of `toNEHex()`)
- Use semantically meaningful names that describe purpose (e.g., `kjExceptionToJs()` instead of `makeInternalError()`)
- Avoid double negatives in boolean names (e.g., `allowNonObjects` instead of `ignoreNonObjects`)
- Add comments for unavoidably obscure identifiers like `$class` that use special syntax
- Choose familiar terminology over internal jargon (e.g., `typescriptErasableSyntax` over custom terms)
Example:
```cpp
// Poor: Abbreviation unclear to newcomers
kj::String toNEHex() const;
// Better: Full descriptive name
kj::String toNetworkOrderHex() const;
// Poor: Obscure identifier without context
auto actorClass = options.$class->getChannel(ioCtx);
// Better: Add explanatory comment
// $class uses $ prefix to avoid keyword conflicts in JSG API
auto actorClass = options.$class->getChannel(ioCtx);
```
This approach reduces cognitive load, improves code maintainability, and helps onboard new team members more effectively.
---
## maintain consistent patterns
Ensure consistent coding patterns and approaches are used throughout the codebase, even when multiple valid alternatives exist. This improves code readability, reduces cognitive load for developers, and makes the codebase easier to maintain.
Key areas to focus on:
1. **Object Creation Patterns**: Use the same approach for creating objects with null prototypes consistently across files. If `Object.create(null)` is used in some places, avoid mixing it with `{ __proto__: null }` unless there's a specific technical reason.
2. **Type Handling**: Maintain consistent approaches for TypeScript type assertions and const assertions. When `as const` provides better type precision, apply it consistently across similar object definitions.
3. **Code Organization**: Follow established patterns for organizing utility functions, global declarations, and shared logic. If similar functionality exists elsewhere, extract it to a shared location rather than duplicating the pattern.
4. **API Compatibility**: When implementing Node.js-compatible APIs, preserve the mutability characteristics of the original APIs even if immutability would be preferred from a design perspective.
Example from the discussions:
```typescript
// Instead of mixing patterns:
export const _cache = { __proto__: null }; // In one file
const other = Object.create(null); // In another file
// Use consistent approach:
export const _cache = Object.create(null); // Everywhere
const other = Object.create(null); // Everywhere
```
Before introducing a new pattern, check if similar functionality already exists and follow the established approach. When there's no clear precedent, document the chosen pattern and apply it consistently across related code.
---
## prefer higher-level APIs
When designing APIs, prefer using higher-level abstractions and established patterns over direct low-level handle manipulation. This improves code maintainability, reduces complexity, and ensures consistency across the codebase.
Key principles:
- Use framework-provided APIs instead of direct V8 handles when available
- Maintain consistent patterns across similar functionality
- Design APIs that follow established conventions in the codebase
For example, instead of manually extracting V8 function names:
```cpp
// Avoid: Direct V8 handle manipulation
v8::Local handle = constructor;
auto func = handle.As();
v8::String::Utf8Value name(js.v8Isolate, func->GetName());
```
Prefer using higher-level APIs:
```cpp
// Better: Use JsValue APIs
auto name = constructor.get(js, "name"_kj);
```
Similarly, use `js.global()` instead of extracting global objects manually, and prefer `JsObject` APIs for prototype and constructor operations rather than working with raw V8 objects.
This approach reduces the likelihood of errors, makes code more readable, and ensures that future API changes in the underlying framework don't break your implementation.
---
## validate post-manipulation state
Always explicitly validate object state after performing manipulations that could potentially result in null or undefined values. This is especially critical when dealing with global objects, parsing operations, or any transformation that might leave objects in an unexpected state.
When manipulating global objects or performing parsing operations, include explicit assertions or checks to verify the object is in the expected state and hasn't become null or undefined:
```javascript
// Good: Explicit validation after global object manipulation
const originalProcess = process;
globalThis.process = 123;
assert.strictEqual(globalThis.process, 123); // Validate intermediate state
globalThis.process = originalProcess;
assert.strictEqual(globalThis.process, process); // Validate final restoration
// Good: Test edge cases in parsing that might produce null/undefined
const headers = parseHeaders('Content-Type: text/plain; f="a, b, \\"c\\""');
assert(headers['content-type'] !== null, 'Header should not be null after parsing');
assert(headers['content-type'] !== undefined, 'Header should be defined after parsing');
```
This practice prevents silent failures where objects become unexpectedly null or undefined, making issues immediately visible through explicit validation rather than allowing them to propagate and cause harder-to-debug problems downstream.
---
## changeset validation standards
Establish comprehensive validation for changesets to ensure reliable release automation. Changesets are required for all releasable artifacts, including internal refactors, as they drive the release process. Implement validation to enforce proper changeset format, meaningful descriptions, and correct semantic versioning.
Key requirements:
- All changes intended for release must include a changeset, even internal refactors
- Changeset types must be one of: major, minor, or patch (not custom types like "docs")
- Descriptions should be clear and specific, avoiding placeholders like ""
- Version type selection should follow semantic versioning principles based on actual impact
Example validation in CI workflow:
```yaml
- name: Validate changesets
run: |
# Check changeset format and required fields
pnpm changeset status
# Validate no placeholder content
! grep -r "" .changeset/
```
This prevents deployment failures, ensures consistent release notes, and maintains proper version semantics in automated release pipelines.
---
## Balance configuration automation complexity
When implementing configuration management solutions, carefully weigh the benefits of automation against the complexity and maintenance burden it introduces. For infrequent configuration updates, prefer simple manual approaches over complex automated solutions that may break unexpectedly. For frequent updates or version-specific configurations, automation and environment variables can be justified.
Consider these factors when deciding on configuration management approaches:
- **Update frequency**: Automate only when updates happen regularly
- **Complexity cost**: Avoid regex-heavy or brittle automation for simple tasks
- **Fallback options**: Ensure manual alternatives remain viable
- **Environment variables**: Use them for version-specific or runtime configurations
Example of appropriate environment variable usage for configuration:
```python
def run_with_config(work_dir: Path, python: str | None) -> None:
env = os.environ.copy()
env["_PYODIDE_EXTRA_MOUNTS"] = str(work_dir)
if python:
env["_PYWRANGLER_PYTHON_VERSION"] = python
run(["tool", "command"], cwd=work_dir, env=env)
```
Avoid over-engineering configuration updates with complex regex patterns when the update frequency doesn't justify the maintenance overhead. The goal is reliable, maintainable configuration management that serves the team's actual needs.
---
## Centralize error handling
Consolidate error handling logic into central, unavoidable locations rather than scattering it across multiple functions or requiring manual setup. This prevents cases where error handling can be bypassed or forgotten.
When you have error handling setup, exception conversion, or similar logic that must always execute, place it in functions that are guaranteed to be called rather than relying on developers to remember to call constructors or helper functions.
For example, instead of requiring users to call a constructor that sets up error handling:
```python
def __init__(self, ctx, env):
_pyodide_entrypoint_helper.patchWaitUntil(ctx) # Can be missed if super() not called
```
Move the setup to a central function that cannot be bypassed:
```python
# In doPyCallHelper() - always called, impossible to miss
_pyodide_entrypoint_helper.patchWaitUntil(ctx)
```
Similarly, consolidate exception conversion logic into existing central functions like `_to_python_exception()` rather than creating separate functions that handle overlapping cases. This ensures consistent error handling and reduces the chance of missing edge cases.
---
## Network resource state validation
Always validate the state of network resources (sockets, streams, connections) before performing operations to prevent errors, resource leaks, and ensure proper connection reuse.
Network resources have complex lifecycles and can be in various states (pending, active, closed, locked, disturbed). Performing operations on resources in invalid states can lead to connection failures, resource leaks, or security issues.
Key validations to perform:
1. **Socket state before conversion**: Check that sockets are not locked, disturbed, or closed before wrapping them in HTTP clients
2. **Stream state before detachment**: Ensure no pending reads/writes are in flight before detaching streams from their JavaScript wrappers
3. **Connection completion before reuse**: Fully consume response bodies before following redirects to allow connection reuse
4. **Resource ownership during operations**: Prevent destruction of underlying resources (HttpClient, streams) while requests are in progress
Example implementation:
```cpp
kj::Own Socket::takeConnectionStream(jsg::Lock& js) {
// Validate no pending operations before detaching
writable->detach(js); // Will throw if pending writes
readable->detach(js); // Will throw if pending reads
// Update state to prevent further use
upgraded = true;
closedResolver.resolve(js);
return connectionStream->addWrappedRef();
}
// Before creating HTTP client from socket
JSG_ASSERT(!socket->isLocked(), Error, "Socket streams are locked");
JSG_ASSERT(!socket->isClosed(), Error, "Socket is already closed");
```
This validation prevents runtime errors, ensures proper resource cleanup, and maintains connection reuse capabilities essential for network performance.
---
## Use KJ_UNWRAP_OR pattern
When handling potentially null values from functions like `tryParse()` or `tryCast()`, avoid the pattern of checking for null/none and then immediately using `KJ_ASSERT_NONNULL` or `JSG_REQUIRE_NONNULL`. This creates redundant checks that make code harder to read and understand.
Instead, use the `KJ_UNWRAP_OR` macro to handle the null case directly and extract the value in one step. This pattern is cleaner, more efficient, and eliminates the cognitive overhead of tracking whether a value can be null.
**Problematic pattern:**
```cpp
auto currentUrl = jsg::Url::tryParse(base.asPtr());
if (currentUrl == kj::none) {
auto exception = JSG_KJ_EXCEPTION(FAILED, TypeError, "Invalid current URL");
return js.rejectedPromise>(kj::mv(exception));
}
// Later: KJ_ASSERT_NONNULL(currentUrl) - redundant since we already checked
```
**Preferred pattern:**
```cpp
auto currentUrl = KJ_UNWRAP_OR(jsg::Url::tryParse(base.asPtr()), {
auto exception = JSG_KJ_EXCEPTION(FAILED, TypeError, "Invalid current URL");
return js.rejectedPromise>(kj::mv(exception));
});
// Now currentUrl can be used directly without null checks
```
This approach makes the code more readable by eliminating the need to verify that null checks guarantee non-null values later in the code.
---
## Test comprehensive error scenarios
When implementing error handling, ensure comprehensive test coverage by testing multiple error scenarios, edge cases, and boundary conditions. Don't just test the happy path - validate that your code properly handles invalid inputs, out-of-range values, and error propagation.
Test cases should verify:
- Specific error codes and messages are returned correctly
- Custom error properties are preserved during propagation
- Edge cases like invalid values (NaN, Infinity, negative numbers, non-integers)
- Boundary conditions and out-of-range inputs
- Error state transitions (e.g., operations after stream end)
Example from the discussions:
```javascript
// Test multiple invalid port scenarios
for (const value of [NaN, Infinity, -1, -Infinity, 1.1, 9999999]) {
// Test each invalid case
}
// Verify specific error codes
res.write('world', (err) => {
strictEqual(err.code, 'ERR_STREAM_WRITE_AFTER_END');
});
// Test custom error properties are preserved
assert.strictEqual(e.abc, 123);
assert.strictEqual(e.stack.includes('at async Object.test'), true);
```
This approach ensures robust error handling that gracefully manages failure scenarios and provides meaningful feedback to users and developers.
---
## ensure test cleanup
Tests must properly clean up resources and handle conditional execution regardless of test outcome. This includes removing temporary files, resetting global state, and gracefully handling feature flag conditions.
For file-based tests, use RAII patterns or explicit cleanup in finally blocks to ensure resources are released even when tests fail:
```cpp
KJ_TEST("PerfettoSession basic functionality") {
auto traceFile = getTempFileName("perfetto-test");
// Use RAII or try-finally pattern
KJ_DEFER(removeFile(traceFile.cStr()));
{
PerfettoSession session(traceFile, "workerd");
// ... test operations
}
KJ_ASSERT(fileExists(traceFile.cStr()));
// File automatically cleaned up by KJ_DEFER
}
```
For tests that depend on feature flags or autogates, check conditions early and skip gracefully rather than creating complex conditional logic:
```cpp
KJ_TEST("feature dependent test") {
if (util::Autogate::isEnabled("feature-flag")) {
KJ_LOG(INFO, "Skipping test due to autogate being enabled");
return;
}
// ... rest of test
}
```
This prevents resource leaks, reduces flaky tests, and makes test behavior predictable across different environments and configurations.
---
## Informative error messages
Error messages should provide specific context and actionable guidance to help developers understand and resolve issues effectively. Include relevant identifiers (class names, file paths, method names) and clear recovery instructions when possible.
Key practices:
- Add contextual identifiers to error messages for better debugging (e.g., include class name and method: `Cannot access "MyDurableObject#ping"`)
- Provide specific, actionable guidance rather than generic error descriptions
- Include recovery information when operations can be resumed (e.g., "assets already uploaded have been saved, so the next attempt will automatically resume")
- Ensure error attribution is correct - clearly identify which component or rule is causing the issue
- Validate critical data and throw explicit errors rather than proceeding with invalid state
Example:
```typescript
// Poor: Generic error without context
throw new Error("Upload failed");
// Better: Specific context and recovery guidance
throw new FatalError(
`Asset upload took too long on bucket ${bucketIndex + 1}/${totalBuckets}. ` +
`Please try again - assets already uploaded have been saved, so the next attempt will automatically resume from this point.`
);
```
This approach reduces debugging time and improves the developer experience by making failures self-explanatory and recoverable.
---
## document security-sensitive features
When introducing compatibility flags, feature toggles, or APIs that have security implications, use self-documenting names that explicitly warn about risks and provide comprehensive documentation explaining the security concerns.
Feature names should include descriptive terms like "insecure", "unsafe", or specific risk indicators. For example, use `allow_insecure_inefficient_logged_eval` instead of just `allow_eval` to immediately signal to developers that this feature carries security risks.
Documentation should clearly explain:
- What security risks the feature introduces
- Why the feature exists despite the risks
- When it's appropriate to use (if ever)
- What precautions developers must take
Example from compatibility flags:
```cpp
experimentalAllowEvalAlways @113 :Bool
$compatEnableFlag("allow_insecure_inefficient_logged_eval")
// Comment should explain:
// * insecure: Disastrous for security if eval content is attacker-controlled
// * inefficient: Poor fit for Workers architecture with many instances
// * logged: Code passed to eval() will be logged for forensics
```
This approach helps prevent security vulnerabilities by making risks explicit and ensuring developers make informed decisions rather than accidentally enabling dangerous features.
---
## Wrap throwing operations
Always wrap potentially throwing operations in try/catch blocks to prevent unhandled exceptions from crashing the application or causing unexpected behavior. This includes property access on unknown objects, API calls, and resource initialization.
Many operations that appear safe can actually throw exceptions. Property access like `val.stack` can throw, method calls like `getReader()` can throw, and even seemingly simple operations may have hidden failure modes. Failing to catch these exceptions can lead to application crashes or inconsistent state.
Example of defensive error handling:
```typescript
// Before - risky property access
if (val && isObject && val.stack && typeof val.stack === 'string') {
out.push(`Stack:\n${val.stack}`);
}
// After - defensive with try/catch
if (val && isObject && val.stack && typeof val.stack === 'string') {
try {
out.push(`Stack:\n${val.stack}`);
} catch {
// Ignore errors when accessing stack property
}
}
// Before - risky method call
this.#reader ??= this._stream.getReader();
const data = await this.#reader.read();
// After - wrapped in try/catch
try {
this.#reader ??= this._stream.getReader();
const data = await this.#reader.read();
// ... handle success
} catch (error) {
this.destroy(error);
}
```
When catching exceptions, decide whether to ignore them silently, log them, or propagate them up the call stack based on the context and severity of the failure.
---
## comprehensive assertion testing
Ensure test assertions are thorough and complete by testing both expected behavior and error conditions with specific error types and messages. Tests should cover edge cases, boundary conditions, and all relevant code branches rather than just happy path scenarios.
When using `assert.throws()`, always include a second argument to verify the specific error type and message:
```javascript
// Instead of just:
assert.throws(() => {
env.ns.jurisdiction('foo');
});
// Do this:
assert.throws(() => {
env.ns.jurisdiction('foo');
}, {
code: 'ERR_INVALID_JURISDICTION',
message: 'Invalid jurisdiction specified'
});
```
Test boundary conditions and edge cases systematically:
- Invalid input values (NaN, Infinity, out-of-range numbers)
- Both error and non-error scenarios for the same function
- Multiple variations of similar inputs (e.g., single vs multiple newlines)
- All code branches, including error handling paths
Use appropriate assertion methods for different scenarios - `assert.rejects()` for async operations that should fail, `assert.strictEqual()` for exact matches, and verify that expected ranges or types are properly validated rather than just checking for existence.
---
## Remove unnecessary configurations
Configuration files should only include options that are supported in production and work out of the box. Remove configuration fields that are unsupported in production environments, comment out configurations that require external provisioning, and maintain consistency across templates by removing redundant or debugging-specific settings.
Key principles:
- Remove production-unsupported options (like worker loader `id` fields)
- Comment out configurations requiring external setup (like R2 buckets) to prevent broken out-of-box experiences
- Remove debugging/development-specific settings for template consistency (like `minify: true`)
Example from wrangler.jsonc:
```jsonc
{
"name": "my-worker",
"main": "src/index.ts",
"compatibility_date": "2024-09-26",
// Remove unsupported production options
// "unsafe": {
// "bindings": [
// {
// "name": "LOADER",
// "type": "worker-loader"
// // "id": "random-id" <- Remove this
// }
// ]
// },
// Comment out configs requiring external provisioning
// "r2_buckets": [
// {
// "binding": "CACHE_BUCKET",
// "bucket_name": ""
// }
// ]
}
```
This ensures templates work immediately after creation and don't include configurations that will fail in production deployments.
---
## Choose appropriate logging functions
Select the correct logging function based on frequency, severity, and destination to avoid log spam and ensure proper routing. Use LOG_ONCE or LOG_PERIODICALLY for repeated warnings that could spam logs, KJ_LOG(ERROR) for general error logging, and LOG_EXCEPTION only for exceptions intended for Sentry monitoring.
For repeated warnings that could spam logs:
```cpp
// Instead of:
KJ_LOG(WARNING, "jurisdiction restrictions have no affect in workerd", jurisdiction);
// Use:
KJ_LOG_ONCE(WARNING, "jurisdiction restrictions have no affect in workerd", jurisdiction);
// or
KJ_LOG_PERIODICALLY(WARNING, "jurisdiction restrictions have no affect in workerd", jurisdiction);
```
For exception logging, choose based on destination:
```cpp
// For general error logging:
KJ_LOG(ERROR, "test failed with exception", exception);
// Only for Sentry-bound exceptions:
LOG_EXCEPTION("test", exception);
```
This prevents log flooding, ensures appropriate log routing, and maintains clean, actionable log output across different environments.
---
## Choose efficient algorithms
When implementing algorithms, prioritize efficiency in both time and space complexity. Consider these specific optimizations:
1. **Use bitwise operations** for mathematical computations when appropriate. For random number generation in ranges, bitwise operations can be more efficient than arithmetic expressions:
```javascript
// Instead of: Math.floor(Math.random() * (65535 - 32768 + 1)) + 32768
// Use: Math.random() * 0x8000 | 0x8000
```
2. **Prefer iterative solutions** over recursive ones when the recursion depth could be problematic or when a simple loop would be more efficient and readable. Even if recursion is unlikely to cause issues, iterative approaches often have better performance characteristics and avoid potential stack overflow risks.
3. **Understand memory implications** of data structure operations. When working with TypedArrays, use `subarray()` to create views instead of `slice()` to create copies, unless you specifically need a copy. This avoids unnecessary memory allocation and copying:
```javascript
// For views (no copy): array.subarray(start, end)
// For copies (when needed): array.slice(start, end)
```
These optimizations become particularly important in performance-critical code paths, large datasets, or resource-constrained environments.
---
## extract repeated expressions
When the same expression or computation appears multiple times within a code block, extract it to a variable to improve maintainability and readability. This reduces the risk of inconsistencies when the logic needs to be updated and makes the code's intent clearer.
Example:
```javascript
// Before - repeated computation
switch (event.event.type) {
case 'spanOpen':
spans.set(event.invocationId + event.spanId, { name: event.event.name });
break;
case 'attributes':
let span = spans.get(event.invocationId + event.spanId);
break;
}
// After - extract to variable
const spanKey = event.invocationId + event.spanId;
switch (event.event.type) {
case 'spanOpen':
spans.set(spanKey, { name: event.event.name });
break;
case 'attributes':
let span = spans.get(spanKey);
break;
}
```
This practice also applies to formatting consistency - use clear, readable formats like `10_000` instead of `10000` for large numbers to improve code readability.
---
## Choose efficient data structures
Select data structures and algorithms that optimize for the specific use case rather than defaulting to generic collections. Consider computational complexity, memory usage, and access patterns when making these choices.
Key principles:
- Use HashMap/BTreeMap for key-value lookups instead of Vec when you need efficient searching: `HashMap` instead of `Vec<(String, i32)>`
- Choose fixed-size types when the size is known: use `[u8; 32]` for commit hashes instead of `Vec`
- Use appropriate algorithms for bit manipulation: `i.count_ones()` instead of casting to usize for bit counting
- Leverage established, well-tested libraries for complex parsing instead of custom implementations (e.g., use `peg` for grammar parsing)
- Design enums with non-zero discriminants when differentiating from empty storage values: `Active = 1` instead of `Active = 0`
- Avoid redundant computations by using operations that combine checks: use `checked_sub()` and match on the result instead of separate comparison and subtraction
Example of efficient data structure selection:
```rust
// Instead of this:
let chain_ids_and_ids: Vec<(String, i32)> = fetch_data();
// Use this for lookups:
let chain_lookup: HashMap = fetch_data().into_iter().collect();
// Instead of this for bit counting:
sync_committee_bits.iter().map(|i| *i as usize).sum::()
// Use this:
sync_committee_bits.iter().map(|i| i.count_ones() as usize).sum::()
```
---
## HTTP protocol compliance
Ensure HTTP protocol implementations strictly follow RFC standards and handle edge cases correctly. This includes proper header parsing that respects quoted-string constructions, realistic port value assignments, and appropriate status code filtering.
Key areas to verify:
1. **Header parsing**: Avoid naive string splitting for headers that may contain quoted strings with commas. Headers like `content-type` and `authorization` can include quoted parameters that contain commas, requiring RFC 7230-compliant parsing that handles optional whitespace (OWS) and quoted-string constructions.
2. **Port value realism**: Use realistic port numbers for network simulation. Ephemeral source ports should be in the range 32768-65535 (2^15 to 2^16), not standard service ports like 80.
3. **Status code support**: Filter out unsupported HTTP status codes early in the implementation. For example, if 1xx status codes aren't supported by the runtime, validate and reject them at the protocol level.
4. **Node.js compatibility**: Support standard Node.js networking behaviors like automatic port assignment (port 0) where the system assigns an available port.
Example of problematic header parsing:
```typescript
// Incorrect - breaks on quoted strings
headers.push(key, value.split(', ').at(0) as string);
// Better approach needed for headers like:
// content-type: text/plain; f="a, b, c", text/foo; a="1, 2, 3"
```
Example of realistic port assignment:
```typescript
// Instead of hardcoded 80
get remotePort(): number {
return 80; // Unrealistic for source ports
}
// Use realistic ephemeral port range
get remotePort(): number {
return 32768; // Realistic source port
}
```
This ensures network protocol implementations are robust, standards-compliant, and handle real-world edge cases that could cause parsing failures or compatibility issues.
---
## HTTP response construction
Use appropriate HTTP response construction methods and status codes for API endpoints. Prefer `Response.json()` over manual JSON stringification, return appropriate status codes (like 404 for unmatched routes), and avoid unnecessary response complexity when simple status codes suffice.
**Key practices:**
- Use `Response.json(data)` instead of `new Response(JSON.stringify(data), { headers: { "Content-Type": "application/json" } })`
- Return appropriate HTTP status codes (404 for not found, 2xx for success)
- Consider whether detailed response bodies are actually needed - some clients only care about status codes
**Example:**
```typescript
// ❌ Avoid manual JSON construction
return new Response(JSON.stringify({ success: true }), {
status: 200,
headers: { "Content-Type": "application/json" }
});
// ✅ Use Response.json() for JSON responses
return Response.json({ success: true });
// ✅ Return appropriate status codes for unmatched routes
if (!matchedRoute) {
return new Response(null, { status: 404 });
}
// ✅ Simple responses when only status matters (e.g., webhooks)
return new Response("", { status: 200 });
```
---
## Connection reuse safety
When implementing network connection reuse, prioritize safety over performance by enforcing sequential request patterns and clear resource ownership. Connection reuse should be supported to avoid the overhead of creating new connections for each request, but must include proper safeguards to prevent concurrency issues and resource conflicts.
Key principles:
- Allow only sequential requests on reused connections, never concurrent ones
- Implement clear ownership semantics where HTTP clients take full control of underlying sockets
- Provide explicit error handling when connections are in invalid states
- Document the single-request-at-a-time limitation clearly for developers
Example implementation pattern:
```javascript
// Each call to fetch should:
// 1. Check if a client currently exists, if so, error
// 2. Create a new client over the stream
// 3. Perform the fetch
// 4. Release the stream when done (unless errored)
const httpClient = await internalNewHttpClient(socket);
const response1 = await httpClient.fetch('https://example.com/ping');
// Second request should fail with clear error message
await assert.rejects(httpClient.fetch('https://example.com/json'), {
message: 'Fetcher created from internalNewHttpClient can only be used once'
});
```
This approach balances the performance benefits of connection reuse with the safety requirements of preventing undefined behavior from overlapping network operations. The connection lifecycle should be deterministic and well-documented to avoid developer confusion about resource ownership.
---
## Use appropriate exception types
Choose the correct exception handling mechanism and type based on the error condition's nature and audience. Use JSG_REQUIRE for user-controllable conditions that should result in JavaScript exceptions, and KJ_ASSERT for internal invariants that indicate programming errors. Provide friendly, actionable error messages for user-facing exceptions.
For reachable error paths that users might trigger, use JSG_FAIL_REQUIRE with descriptive messages instead of KJ_UNIMPLEMENTED, which generates internal Sentry errors. When constructing error messages, avoid kj::str() in KJ_ASSERT/KJ_LOG calls as this creates different Sentry fingerprints for each unique message and wastes allocations.
Example of proper exception type usage:
```cpp
// Good: User-controllable condition
JSG_REQUIRE(constructor.isFunction(), TypeError, "registerRpcTargetClass() requires a constructor function");
// Good: Internal invariant
KJ_ASSERT(console->IsObject());
// Bad: Reachable user error as internal error
KJ_UNIMPLEMENTED("connect() not supported on StreamWorkerInterface");
// Good: Reachable user error with friendly message
JSG_FAIL_REQUIRE(Error, "connect() not supported on StreamWorkerInterface");
// Bad: String allocation in assertion
KJ_ASSERT(res.statusCode == 200, kj::str("Request failed with status ", res.statusCode));
// Good: Let KJ_ASSERT format the message
KJ_ASSERT(res.statusCode == 200, "Request failed", res.statusCode);
```
This approach ensures appropriate error handling for different audiences (users vs developers), improves error reporting and debugging, and avoids unnecessary performance overhead.
---
## Add explanatory comments
When code behavior, limitations, or implementation decisions are not immediately obvious from reading the code itself, add explanatory comments to clarify the reasoning and context. This is especially important for:
- **API limitations and scope**: Document when functions or classes have restricted functionality or are not part of standard APIs
- **Implementation decisions**: Explain why certain approaches were chosen, especially when they might seem unusual
- **Disabled linting rules**: Always explain why specific linting rules are disabled
- **Placeholder or unused code**: Clarify the purpose of code that exists for compatibility but isn't functionally used
Example from the codebase:
```typescript
// @ts-expect-error TS2416 Types insist value is a Socket, but it's actually unknown
set connection(value: unknown) {
// Note: #socket is not actually used for anything other than making
// the property available for compatibility
this.#socket = value;
}
/* eslint-disable @typescript-eslint/no-deprecated */
// Disabling deprecated warnings for this.finished and other attributes
// which are deprecated in types/node package but required for compatibility
```
This practice prevents confusion for future maintainers and helps reviewers understand the context behind implementation choices.
---
## Configure secret scanning exceptions
When embedding test certificates or cryptographic keys in code for testing purposes, configure secret scanning tools to exclude these legitimate test artifacts to prevent false positive alerts. This ensures security tooling remains effective while avoiding alert fatigue that could lead to ignoring genuine security issues.
Test certificates and keys should be added to your repository's secret scanning configuration file (e.g., `.github/secret_scanning.yml`) to explicitly mark them as safe. This practice maintains the integrity of automated security scanning while allowing necessary test infrastructure.
Example configuration:
```yaml
# .github/secret_scanning.yml
paths-ignore:
- "src/workerd/api/tests/starttls-try-server.js"
```
This approach balances security automation with development needs, ensuring that security tools continue to catch real secrets while not flagging intentional test data.
---
## Validate before type conversions
Always validate input constraints and use safe conversion methods before performing type conversions that could fail or produce undefined behavior. Avoid arbitrary casting with `as` operators, especially when the source value range may not fit the target type.
**Prefer safe conversion patterns:**
- Use `try_into().expect()` instead of `as` casting for fallible conversions
- Validate input constraints before conversion (e.g., array lengths, value ranges)
- Consider all possible input values when designing conversions
**Example of unsafe vs safe conversion:**
```rust
// Unsafe - arbitrary casting without validation
let raw = val.to_le_bytes()[0];
let status = Status::try_from(raw as u32)?;
// Safe - validate constraints and use proper error handling
let raw = val.to_le_bytes()[0];
let status = Status::try_from(raw)
.map_err(|_| ContractError::InvalidClientStatusValue { value: raw })?;
// For address conversions - validate length first
if address_bytes.len() != 20 {
return Err(eyre!("Invalid address length"));
}
let address = Address::new(address_bytes);
```
This prevents runtime panics, data corruption, and undefined behavior that can occur when conversions fail silently or when input constraints are violated.
---
## organize code for readability
Structure code to maximize readability and maintainability through clear organization patterns. Use top-level control flow structures (like switch/match statements) to make logic paths obvious and easy to follow. Extract reusable functionality into separate modules or helper libraries to promote code reuse and reduce duplication. Isolate different concerns into their own components or functions to maintain clear boundaries and responsibilities.
For example, instead of nested conditional logic, prefer top-level pattern matching:
```solidity
function _verifyTokenOrderV2(
uint32 channelId,
uint256 path,
TokenOrderV2 calldata order
) internal {
// Switch on order.kind at top level for clarity
if (order.kind == TokenKind.FUNGIBLE) {
// Handle fungible token logic
} else if (order.kind == TokenKind.NON_FUNGIBLE) {
// Handle NFT logic
}
// This approach is easier to read, more gas-efficient, and less error-prone
}
```
When you notice repeated patterns or functionality that could benefit multiple parts of the codebase, extract them into dedicated modules or helper libraries. This makes the code more modular and allows developers to "plug and go" with proven solutions.
---
## defer async callbacks
Always ensure callbacks and event emissions are executed asynchronously to maintain proper timing and Node.js compatibility. Even when operations appear to complete synchronously, callbacks should be deferred using `queueMicrotask()` or `process.nextTick()` to match expected async behavior.
This is critical for maintaining consistent execution order and preventing timing-related bugs. Synchronous callback execution can break assumptions about when code runs relative to other async operations.
Example of proper async callback deferral:
```javascript
// Instead of calling callback immediately
callback?.();
// Defer the callback execution
queueMicrotask(() => callback?.());
```
The key principle is that callbacks should execute after the current execution context completes, allowing other queued operations to run in the expected order. This ensures compatibility with Node.js behavior where callbacks are typically asynchronous even for operations that complete immediately.
---
## Clear descriptive naming
Choose names that clearly communicate intent without requiring mental gymnastics to understand. Avoid double negatives in variable names, maintain consistent naming patterns across the codebase, and ensure names accurately describe their purpose and context.
Key principles:
- **Avoid double negatives**: Instead of `pythonNoGlobalHandlers` requiring `!pythonNoGlobalHandlers`, use positive naming like `legacyGlobalHandlers`
- **Be descriptive and contextual**: Function names should clearly indicate what they do and include relevant context (e.g., `nodeCompatHttpServerHandler` instead of generic `registerFetchEvents`)
- **Maintain consistency**: If using `Module` as a parameter name throughout the codebase, stick with it consistently, or rename the type to `ModuleType` to allow lowercase `module` parameters
Example of improvement:
```typescript
// Avoid - requires double negative
export const pythonNoGlobalHandlers: boolean = !!compatibilityFlags.python_no_global_handlers;
if (!pythonNoGlobalHandlers) { ... }
// Prefer - clear positive naming
export const legacyGlobalHandlers: boolean = !compatibilityFlags.python_no_global_handlers;
if (legacyGlobalHandlers) { ... }
```
---
## avoid unnecessary allocations
Minimize object creation and memory copying operations to improve performance. Cache and reuse objects when possible, use buffer views instead of copying data, and avoid creating temporary objects that will be immediately discarded.
Key practices:
- Cache expensive objects like Readers instead of creating new ones on each call
- Use buffer views (`new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength)`) instead of copying data twice
- Avoid creating objects that are immediately overwritten or discarded
- Use efficient concatenation methods like `Buffer.concat()` instead of manual array operations
Example of inefficient allocation:
```js
// Creates unnecessary ReadableStream that gets overwritten
let stream = this.bindingsResponse.body || new ReadableStream();
if (options?.encoding === 'base64') {
stream = stream.pipeThrough(createBase64EncoderTransformStream());
}
// Creates new Reader on every call
const reader = this._stream.getReader();
```
Example of optimized allocation:
```js
// Only create ReadableStream when needed
const stream = options?.encoding === 'base64'
? (this.bindingsResponse.body || new ReadableStream()).pipeThrough(createBase64EncoderTransformStream())
: (this.bindingsResponse.body || new ReadableStream());
// Cache and reuse Reader
if (!this._cachedReader) {
this._cachedReader = this._stream.getReader();
}
```
---
## API interface simplification
Design APIs with clean, minimal interfaces that encapsulate internal logic and avoid exposing unnecessary complexity to consumers. Prefer methods that internally handle implementation details over exposing flags or parameters that clients must manage.
Key principles:
- Encapsulate internal logic rather than exposing implementation details through exported functions or flags
- Remove unnecessary parameters when they serve no functional purpose (e.g., always-constant values)
- Maintain consistency across similar API components by extracting common functionality
- Ensure proper interface compliance when implementing required methods
Example of good encapsulation:
```go
// Instead of exposing internal state checking
if !p.k8sClient.IngressClassesIgnored() {
ingressClasses = p.k8sClient.GetIngressClasses()
}
// Prefer encapsulated methods that handle logic internally
ingressClasses := p.k8sClient.ListIngressClasses() // internally checks ignored state
```
Example of parameter simplification:
```go
// Instead of passing unnecessary constant parameters
func AllowTokenBucketN(key string, limit, burst, ttl, t, n int) // n is always 1
// Simplify to essential parameters only
func Allow(key string, limit, burst, ttl, t int)
```
This approach reduces cognitive load on API consumers, prevents misuse of internal implementation details, and creates more maintainable interfaces that are easier to evolve over time.
---
## Optimize algorithm performance
When implementing algorithms, prioritize performance by using batching techniques to reduce API call overhead and avoiding unnecessary memory allocations. Convert recursive algorithms to iterative ones when dealing with large datasets, and process elements in batches rather than individually.
Key optimization strategies:
1. **Batch processing**: Group operations to reduce overhead from repeated API calls
2. **Avoid unnecessary allocations**: Use efficient string/memory operations (e.g., `js.str()` instead of `kj::str()`, `chars.first()` instead of `chars.slice()`)
3. **Queue management**: Pre-reserve capacity and filter out null/undefined values early
Example from recursive to iterative optimization:
```cpp
// Instead of recursive calls, use iterative approach with batching
kj::Vector> queue;
queue.reserve(128);
while (!queue.empty()) {
auto item = queue.back();
queue.removeLast();
if (item->IsArray()) {
auto arr = item.As();
constexpr uint32_t BATCH_SIZE = 32;
for (uint32_t i = 0; i < length;) {
uint32_t batchEnd = kj::min(i + BATCH_SIZE, length);
queue.reserve(queue.size() + (batchEnd - i));
for (; i < batchEnd; ++i) {
auto element = check(arr->Get(context, i));
if (!element->IsNullOrUndefined()) {
queue.add(element);
}
}
}
}
}
```
This approach reduces V8 API call overhead and manages memory more efficiently than naive recursive implementations.
---
## validate file paths
Always validate and sanitize file paths when processing external input to prevent directory traversal attacks, zip slip vulnerabilities, and other path-based security issues. Check for minimum required path components, reject paths with suspicious patterns, and ensure paths stay within expected boundaries.
Example from zip extraction:
```go
// Split to discard the first part of the path, which is [organization]-[project]-[release commit sha1] when the archive is a Yaegi go plugin with vendoring.
pathParts := strings.SplitN(f.Name, "/", 2)
if len(pathParts) < 2 {
return fmt.Errorf("no root directory: %s", f.Name)
}
// Validate and sanitize the file path
p := filepath.Join(dest, pathParts[1])
```
This pattern should be applied whenever processing file paths from archives, user uploads, API requests, or any external source where malicious paths could be injected.
---
## Simplify async patterns
Use modern promise utilities and clean async patterns instead of manual promise construction. Prefer Promise.withResolvers() over manual promise creation with resolve/reject callbacks, and chain promises directly rather than wrapping them in unnecessary async functions.
When testing async operations, ensure the tests actually validate the intended concurrency behavior. Async tests should verify that operations complete at the right time and in the right sequence, not just that they eventually resolve.
Example of preferred patterns:
```javascript
// Good: Clean and readable
const { promise, resolve } = Promise.withResolvers();
waitUntil(scheduler.wait(100).then(resolve));
await promise;
// Avoid: Manual promise construction
let resolve;
const promise = new Promise((r) => { resolve = r; });
waitUntil((async () => {
await scheduler.wait(100);
resolve();
})());
```
This approach reduces complexity, improves readability, and ensures async operations are tested meaningfully rather than just checking that promises eventually resolve.
---
## avoid external dependencies
Unit tests should not depend on external components like databases, Redis, or Kubernetes clusters. Instead, create fake implementations or use mocks to isolate the code under test. Reserve integration tests for scenarios that require real external services.
When testing against external components is necessary, implement fake clients that simulate the external service behavior. For example, when testing Redis rate limiting:
```go
type FakeRedisClient struct{
script string
keys *ttlmap.TtlMap
}
func (m FakeRedisClient) EvalSha(ctx context.Context, _ string, keys []string, args ...interface{}) *redis.Cmd {
state := lua.NewState()
defer state.Close()
// Set up Lua environment with KEYS and ARGV
tableKeys := state.NewTable()
for _, key := range keys {
tableKeys.Append(lua.LString(key))
}
state.SetGlobal("KEYS", tableKeys)
// Implement Redis commands like GET, SET
mod := state.SetFuncs(state.NewTable(), map[string]lua.LGFunction{
"call": func(state *lua.LState) int {
switch state.Get(1).String() {
case "GET":
key := state.Get(2).String()
value, ok := m.keys.Get(key)
if !ok {
state.Push(lua.LNil)
} else {
state.Push(lua.LString(value.(string)))
}
case "SET":
// Handle SET operations
}
return 1
},
})
state.SetGlobal("redis", mod)
// Execute and return result
cmd := redis.NewCmd(ctx)
// ... execute Lua script and set result
return cmd
}
```
This approach keeps unit tests fast, reliable, and independent while still validating the core logic. Use integration tests in the `integration` directory when you need to verify behavior against actual external services.
---
## proper context handling
Always propagate contexts consistently throughout the call chain and handle context cancellation properly in concurrent operations. When a context is available in the current scope, reuse it instead of creating a new background context. For operations that may block (like time.Sleep), use context-aware alternatives to prevent goroutine leaks when requests are cancelled.
Example of proper context cancellation handling:
```go
// Instead of:
time.Sleep(res.Delay)
// Use:
select {
case <-ctx.Done():
return Result{Ok: false}, nil
case <-time.After(res.Delay):
}
```
This ensures that goroutines don't remain active after their associated request context has been cancelled, preventing resource leaks and improving application responsiveness.
---
## Environment-specific configuration values
Avoid hardcoding configuration values that should vary between different deployment environments (testnet, mainnet, development). Instead, use environment variables, configuration files, or conditional logic to handle environment-specific settings.
Hardcoded values like network addresses, token supplies, or feature flags create deployment issues and require code changes for different environments. Use environment variables for optional features and implement proper branching logic for environment-specific constants.
Example of problematic hardcoded values:
```go
const U_BASE_DENOM = "au"
const ONE_U = 1000000000000000000
const UNION_FOUNDATION_MULTI_SIG = "union1cpz5fhesgjcv2q0640uxtyur5ju65av6r8fem0"
```
Better approach using environment variables:
```go
if depinjectOutPath, ok := os.LookupEnv("DEPINJECT_OUT_PATH"); ok {
os.WriteFile(depinjectOutPath, []byte(dotGraph), 0644)
}
```
Consider implementing environment detection logic or configuration files to manage different settings for testnet versus mainnet deployments.
---
## Use descriptive names
Choose names that clearly describe their purpose, behavior, and data type rather than generic or ambiguous alternatives. Function names should reflect what they actually do, variables should indicate their specific role, and parameter names should convey semantic meaning.
**Key principles:**
- **Functions**: Name based on actual behavior, not outdated descriptions
- **Variables**: Use specific, descriptive terms over generic ones
- **Parameters**: Prefer named object parameters over positional booleans for clarity
- **Types**: Avoid names that suggest incorrect data types
**Examples:**
```typescript
// ❌ Generic/misleading names
function deserializeToJson(message) { return JSON.parse(message.toString()); }
const directory = "/path/to/project";
const pinFrameworkCli = "1.2.3"; // suggests boolean
updateTsConfig(ctx, true); // unclear what true means
// ✅ Descriptive names
function deserializeJson(message) { return JSON.parse(message.toString()); }
const projectRoot = "/path/to/project";
const frameworkCliPinnedVersion = "1.2.3";
updateTsConfig(ctx, { usesNodeCompat: true });
```
This approach reduces cognitive load, prevents misunderstandings about data types and behavior, and makes code self-documenting. When reviewing code, ask: "Does this name clearly communicate what this thing is or does?"
---
## prefer nullish coalescing operators
Use nullish coalescing operators (`??`) and logical OR with safe defaults (`|| {}`) to handle null and undefined values more safely and concisely. This prevents runtime errors when accessing properties on potentially null/undefined objects and provides cleaner, more readable code.
Instead of explicit null/undefined checks:
```typescript
// Avoid
return this._eventsCount > 0 && this._events !== undefined
? Reflect.ownKeys(this._events)
: [];
// Prefer
return this._eventsCount > 0 ? Reflect.ownKeys(this._events || {}) : [];
```
For numeric values, use nullish coalescing to distinguish between falsy values and null/undefined:
```typescript
// Avoid - treats 0 as falsy
this.errno = options.errno || 1;
// Prefer - only coalesces null/undefined
this.errno = options.errno ?? 1;
```
This approach reduces boilerplate code while providing better null safety and more predictable behavior when dealing with optional properties and parameters.
---
## Complete network configurations
Network configuration examples and documentation should include all essential networking components such as ports, protocols, timeouts, and security considerations. Incomplete configurations can lead to connection failures, security vulnerabilities, or unexpected behavior.
When documenting network configurations:
1. **Include all required ports**: Specify both HTTP and HTTPS ports when TLS is configured
2. **Specify protocols explicitly**: Clearly indicate TCP/UDP protocols and default behaviors
3. **Provide complete timeout configurations**: Include relationship warnings between related timeouts
4. **Add security warnings**: Highlight security implications of configuration options
5. **Use accurate networking terminology**: Distinguish between connections and requests, especially for TCP
Example of complete network configuration:
```yaml
entryPoints:
web:
address: ":80"
http:
redirections:
entryPoint:
to: websecure
scheme: https
websecure:
address: ":443" # Include HTTPS port when TLS is configured
tls: {}
# For Tailscale configurations, specify directory requirements
entryPoints:
tailscale:
tsnet:
dir: /var/lib/tailscale # For multiple entrypoints, use different directories
# Include security warnings for path sanitization
http:
entryPoints:
web:
sanitizePath: false # Warning: Can lead to unsafe routing with base64 data containing "/"
```
This ensures users have complete, working configurations and understand the security implications of their networking choices.
---
## Health check lifecycle completeness
Ensure health check systems are not only created but also properly launched and integrated with observability infrastructure. Health checkers must follow the complete lifecycle: creation, launch, and metrics integration.
When implementing health checks, verify that:
1. Health checkers are created during service setup
2. Health checkers are explicitly launched (not just instantiated)
3. Metrics collection is properly integrated
4. The implementation follows established patterns from similar components
Example of incomplete implementation:
```go
// TCP health checkers created but never launched
if conf.LoadBalancer.HealthCheck != nil {
m.healthCheckers[serviceName] = healthcheck.NewServiceTCPHealthChecker(
ctx,
m.dialerManager,
nil, // metrics parameter passed as nil
// ... other params
)
// Missing: no launch call equivalent to serviceManager.LaunchHealthCheck(ctx)
}
```
Compare this with HTTP health checkers that properly launch via `serviceManager.LaunchHealthCheck(ctx)` and integrate metrics. TCP health checks should follow the same complete lifecycle pattern to ensure proper observability and functionality.
---
## provide contextual error information
Ensure error messages and logging provide sufficient context to understand what failed and why. Include relevant details such as server addresses, operation types, configuration values, or other identifying information that helps with debugging and troubleshooting.
When handling errors, especially in network operations, health checks, or resource management:
1. **Include identifying information** in error messages (server addresses, service names, etc.)
2. **Specify which operation failed** (connection, payload write, response read, etc.)
3. **Log errors with appropriate context** using structured logging
4. **Handle resource cleanup errors** explicitly rather than ignoring them
Example from health check implementation:
```go
// Instead of generic error handling
if err := thc.executeHealthCheck(ctx, thc.config, target); err != nil {
log.Warn().Err(err).Msg("Health check failed.")
}
// Provide specific context about what failed
if err := thc.executeHealthCheck(ctx, thc.config, target); err != nil {
log.Ctx(ctx).Warn().
Str("targetURL", target.String()).
Str("service", thc.serviceName).
Err(err).
Msg("Health check failed.")
}
// Handle resource cleanup with error context
defer func() {
if err := conn.Close(); err != nil {
log.Ctx(ctx).Warn().
Err(err).
Str("target", target.String()).
Msg("Failed to close health check connection")
}
}()
```
This approach significantly improves debugging capabilities and system observability by making it clear which specific component, server, or operation encountered the error.
---
## Contextual null checks
Use type-appropriate null checking strategies based on the context of your data. For primitive values, ensure they exist before accessing properties. For complex nested structures, use more comprehensive checks like `IsWhollyKnown()` instead of simple `IsKnown()` to verify all nested attributes.
When designing interfaces:
- Return `nil` when it leads to clearer calling code (e.g., `if result == nil` vs `if len(result) == 0`)
- Use pointers for optional fields when you need to distinguish between "not set" and "explicitly set to zero value"
- Implement defensive checks before accessing potentially null values
```go
// BAD: May panic if importTarget is not a string type
h.println(fmt.Sprintf("%s: Preparing import... [id=%s]", id.Addr, importTarget.AsString()))
// GOOD: Check type before calling type-specific methods
if importTarget.Type().IsObjectType() {
h.println(fmt.Sprintf("%s: Preparing import... [identity=%s]", id.Addr, importTarget.GoString()))
} else {
h.println(fmt.Sprintf("%s: Preparing import... [id=%s]", id.Addr, importTarget.AsString()))
}
// BAD: Using IsKnown() for complex nested structures
if i.Target.IsKnown() {
// Some attributes might still be unknown
}
// GOOD: Using IsWhollyKnown() for complex nested structures
if i.Target.IsWhollyKnown() {
// All attributes are guaranteed to be known
}
```
Be consistent in your approach to null handling throughout the codebase, and document expectations about null values in interface definitions.
---
## Descriptive purpose-driven naming
Choose identifiers that accurately describe their purpose and behavior, not just their type or how they're used. Names should be specific enough to understand their role without requiring additional context.
When naming methods, focus on what they actually do: 'AddAll' is more accurate than 'Merge' for a method that adds items from one set to another without creating a new set. For parameters and fields, use prefixes to clarify their scope or target: 'object_tags' is clearer than just 'tags' when specifically tagging an object.
For type or class names that represent specialized versions of concepts, use standard prefixes consistently (e.g., 'Abs' prefix for absolute references):
```go
// Good
type AbsActionInvocation struct {
TriggeringResource AbsResourceInstance
Action AbsActionInstance
}
// Avoid
type ActionInvocation struct {
// Unclear whether these are absolute or relative references
}
```
For configuration attributes and flags, choose names that communicate their effect clearly:
```hcl
# Good: Clearly indicates when the override applies
override_during = "plan"
# Avoid: Vague about what is being affected
override_computed = true
```
Avoid variable names that are common English words ('said') or ambiguous acronyms. Instead use descriptive compound names ('storageAccountId') that precisely communicate intent.
---
## Document function behavior completely
Function and method documentation should accurately describe behavior, parameters, and any non-obvious aspects of the implementation. Documentation should evolve alongside code changes.
When writing function documentation:
1. Clearly explain the purpose and intended behavior of the function
2. Document all parameters, including unused ones (consider using underscore notation in parameter names to reinforce documentation)
```go
// As backends are not implemented by providers, the provider schema argument should always be nil
func (s *BackendConfigState) PlanData(schema *configschema.Block, _ *configschema.Block, workspaceName string) (*plans.Backend, error) {
```
3. Note any limitations, requirements, or special conditions (like type requirements for comparisons)
```go
// AppendWithoutDuplicates only classifies "duplicates" as diagnostics which
// implement ComparableDiagnostic and return true for Equals
func (diags Diagnostics) AppendWithoutDuplicates(newDiags ...Diagnostic) Diagnostics {
```
4. When deprecating functionality, always provide the recommended alternative
```go
"endpoint": {
Type: schema.TypeString,
Optional: true,
Deprecated: "`endpoint` is deprecated and superseded by `msi_endpoint`, please update your configuration to use `msi_endpoint` instead",
}
```
5. Explain counter-intuitive implementations that might confuse future developers
```go
// Note: we need to parse the test block before the run blocks
// because run blocks depend on test configuration
```
Proper documentation reduces onboarding time for new developers, prevents misuse of functions, and makes code maintenance easier over time.
---
## Clear concise documentation
Write documentation that is direct, consistent, and appropriately detailed. Follow these principles:
1. **Use direct language** - Prefer straightforward assertions over gentle phrasing. Instead of "Please be cautious when..." use "Use caution when..." or simply state facts and instructions directly.
2. **Maintain consistent structure** - Place similar elements (notes, warnings, etc.) in the same position across documents. For example, place note sections consistently within the "Usage" section of command documentation.
3. **Format for readability** - For terminal output examples, use consistent formatting with line markers (like │) and limit width to approximately 72 columns to prevent horizontal scrolling:
```
Error: Provider instance not present
│
│ To work with aws_cloudwatch_log_group.lambda_cloudfront["sa-east-1"] its original provider instance at
│ provider["registry.opentofu.org/hashicorp/aws"].by_region["sa-east-1"] is required, but it has been removed.
```
4. **Avoid unnecessary examples** - Only include examples that provide significant context or clarity. Remove content that increases complexity without adding value.
5. **Balance detail with brevity** - Keep documentation concise since readers tend to skip overly long sections. Include essential information while avoiding excessive detail that can overwhelm users.
---
## Choose appropriate API types
Select the simplest data types that satisfy requirements when designing API signatures. Avoid using complex types (like cty.Value) when simpler types (like string, int, bool) would suffice. This improves API usability, reduces complexity, and simplifies client implementations while maintaining consistent patterns across the API.
For example, prefer:
```go
type GetStatesResponse struct {
// States is a list of state names
States []string
}
```
Instead of:
```go
type GetStatesResponse struct {
// States is a list of state names
States []cty.Value
}
```
When extending existing APIs or adding new functionality, follow established naming and structural conventions to create a cohesive and predictable interface. Use helper functions provided by the API rather than reimplementing functionality, and ensure documentation accurately reflects method signatures, parameters, and return types to prevent confusion.
---
## Simplify conditional logic
Prefer concise conditional expressions over verbose nested conditions and unnecessary boolean variables. This improves readability and reduces cognitive overhead.
**Key practices:**
- Combine multiple related conditions into a single statement
- Remove redundant type checks when more specific checks are sufficient
- Use direct assignment instead of conditional blocks when possible
- Eliminate unnecessary boolean variables in favor of direct control flow
**Examples:**
Instead of nested conditions:
```typescript
if (binding.binding && typeof binding.binding === "string") {
if (binding.binding.toUpperCase() === normalizedName) {
return true;
}
}
```
Combine into single condition:
```typescript
if (typeof binding.binding === "string" && binding.binding.toUpperCase() === normalizedName) {
return true;
}
```
Instead of boolean tracking variables:
```typescript
let isValid = false;
while (!isValid) {
// validation logic
if (validation.valid) {
isValid = true;
}
}
```
Use direct control flow:
```typescript
while (true) {
// validation logic
if (validation.valid) {
return bindingName;
}
}
```
Instead of conditional assignment:
```typescript
if (match) {
const cachedAssetKey = await match.text();
if (cachedAssetKey === assetKey) {
shouldUpdateCache = false;
}
}
```
Use direct assignment:
```typescript
if (match) {
const cachedAssetKey = await match.text();
shouldUpdateCache = cachedAssetKey !== assetKey;
}
```
---
## Validate security-critical inputs
Always implement thorough validation for user-controllable inputs that could pose security risks. Particularly:
1. **Path validation**: Protect against path traversal attacks by rejecting paths containing directory traversal sequences (`..`) or by resolving paths against a safe base directory.
2. **Domain/subdomain validation**: Validate domain-related inputs against potentially dangerous characters (like `.` or `*` in subdomains) that could be used for attacks.
Example for path validation:
```go
// Incorrect - vulnerable to path traversal
func (f *FileSource) Validate() error {
if f.Path == "" {
return errors.New("file path cannot be empty")
}
return nil
}
// Better - validates against path traversal attempts
func (f *FileSource) Validate() error {
if f.Path == "" {
return errors.New("file path cannot be empty")
}
if strings.Contains(f.Path, "..") {
return errors.New("path cannot contain directory traversal sequences")
}
// Consider additional checks like absolute path resolution
return nil
}
```
Failing to validate these inputs can lead to serious security vulnerabilities including unauthorized file access, server-side request forgery, or other injection-based attacks.
---
## Design stable APIs
When creating or modifying APIs, carefully consider what becomes part of your public API surface to ensure backward compatibility and consistent developer experience.
Key practices:
1. Use specific, descriptive names for API elements that follow established patterns (e.g., `TerraformAuthorizationScopeFilter` instead of generic `AuthorizationScopeFilter`)
2. Avoid exposing implementation details or utility methods that might need to change later
3. Ensure consistent behavior between related API methods (e.g., streaming and non-streaming variants should follow similar patterns)
4. Prefer strongly-typed parameters over generic types like Dictionary when possible
5. Maintain consistent terminology throughout code and documentation
Example:
```csharp
// GOOD: Specific, descriptive client name with consistent method naming
PersistentAgentsClient agentClient = projectClient.GetPersistentAgentsClient();
// BAD: Generic naming or inconsistent patterns
AgentsClient agentClient = projectClient.GetAgentsClient();
// GOOD: Strongly-typed parameters
private int GetHumidityByAddress(Address address)
{
return (address.City == "Seattle") ? 60 : 80;
}
// BAD: Generic dictionary parameters that hide the actual structure
private int GetHumidityByAddress(Dictionary address)
{
return (address["City"] == "Seattle") ? 60 : 80;
}
```
Before adding new public API members, consider if they're truly necessary and ensure they won't need breaking changes in the future.
---
## Minimize memory allocations
Reduce garbage collection pressure and improve application performance by avoiding unnecessary memory allocations. This significantly impacts overall system responsiveness, especially for high-throughput services.
Key practices to follow:
1. **Use shared buffers and specialized APIs** - Prefer operations that leverage pre-allocated memory:
```csharp
// Instead of this (creates allocations):
var binaryData = ModelReaderWriter.Write(model);
return RequestContent.Create(binaryData);
// Use this (leverages shared buffers):
return BinaryContent.Create(model); // Uses UnsafeBufferSequence internally
```
2. **Work directly with Spans** - Avoid copying when operating on memory regions:
```csharp
// Instead of this (allocates new array):
json.WriteString("certificate", Convert.ToBase64String(data.ToArray()));
// Use this (avoids allocation):
json.WriteString("certificate", Convert.ToBase64String(data.Span));
```
3. **Cache infrequently-changing data** - Balance freshness with performance:
```csharp
// Cache agent tools to avoid API calls on every request
if (_agentTools is null)
{
PersistentAgent agent = await _client.Administration.GetAgentAsync(_agentId);
_agentTools = agent.Tools;
}
```
4. **Use streaming APIs for large data** - Process data incrementally instead of loading everything into memory:
```csharp
// Instead of loading the whole stream:
var allProfile = BinaryData.FromStream(stream).ToObjectFromJson>>();
// Use streaming deserialization:
var allProfile = await JsonSerializer.DeserializeAsync>>(stream, options);
```
5. **Reuse objects** for repeated operations rather than creating new instances each time.
These optimizations are particularly important in high-throughput scenarios where allocation pressure can cause frequent garbage collections, leading to performance degradation.
---
## Use domain-specific type names
Types should be named with clear domain context rather than generic terms. Avoid single-word or overly generic names that could be ambiguous or conflict with other types. Instead, prefix type names with their domain or service name to provide clear context and prevent naming collisions.
Example - Instead of:
```csharp
public class ConnectorData { }
public class Performance { }
public class HttpGet { }
```
Use domain-specific names:
```csharp
public class ImpactReportingConnector { }
public class WorkloadPerformanceMetrics { }
public class HttpGetOperation { }
```
This makes the code more maintainable by:
- Preventing naming conflicts across different services/domains
- Making type purposes immediately clear from their names
- Improving code searchability and navigation
- Reducing cognitive load when reading code
---
## Consolidate related code
Organize code to keep related functionality together. When functions serve similar purposes or operate on the same data, combine them rather than creating separate implementations. Position validation and condition checks before execution to allow early returns and avoid unnecessary processing. This improves code readability, maintainability, and reduces duplication.
For example, instead of having separate validation functions:
```go
func (n *NodeAbstractResourceInstance) validateIdentity(newIdentity cty.Value) (diags tfdiags.Diagnostics) {
// Validate marks
// ...
return diags
}
func (n *NodeAbstractResourceInstance) validateIdentityMatchesSchema(newIdentity cty.Value, identitySchema *configschema.Object) (diags tfdiags.Diagnostics) {
// Validate schema
// ...
return diags
}
```
Prefer consolidating them into a single function:
```go
func (n *NodeAbstractResourceInstance) validateIdentity(newIdentity cty.Value, identitySchema *configschema.Object) (diags tfdiags.Diagnostics) {
// Validate marks
// ...
// Validate schema
// ...
return diags
}
```
Similarly, perform condition checks early in functions to avoid unnecessary work, as seen in discussion 9 where condition checks were moved before execution calls.
---
## Use configuration service injection
Replace mutable singletons and getter functions with dependency injection services for configuration-dependent components. This approach eliminates race conditions, provides proper initialization guarantees, and enables environment-specific configuration management.
Instead of using mutable globals or getter functions:
```typescript
let client: ReturnType> | null = null
export const getSupabaseClient = () =>
Effect.gen(function*() {
if (client) {
return client
}
// initialization logic...
client = createClient(url, anonKey)
return client
})
```
Use Effect services with proper environment variable validation:
```typescript
export class SupabaseClient extends Effect.Service()("SupabaseClient", {
scoped: (options?: SupabaseOptions | undefined) =>
Effect.gen(function*() {
const url = yield* S.decode(S.URL)(PUBLIC_SUPABASE_URL).pipe(
Effect.mapError((cause) =>
new SupabaseClientError({
operation: "init",
message: "Could not decode PUBLIC_SUPABASE_URL to URL",
cause,
})
),
)
const anonKey = yield* S.decode(S.NonEmptyString)(PUBLIC_SUPABASE_ANON_KEY).pipe(
Effect.mapError((cause) =>
new SupabaseClientError({
operation: "init",
message: "Could not decode PUBLIC_SUPABASE_ANON_KEY to non-empty string",
cause,
})
),
)
return createClient(url.toString(), anonKey, options)
}),
}) {}
```
This pattern ensures configuration is validated at startup, supports environment-specific layers (test vs production), and provides type-safe dependency injection throughout the application.
---
## Limit token permissions
Always specify the minimum required permissions for the GITHUB_TOKEN in GitHub Actions workflows to enhance security. By default, the GITHUB_TOKEN has broad permissions that could potentially be exploited if a workflow is compromised.
Add an explicit permissions block at the workflow level or per job with only the necessary permissions:
```yaml
name: Verify
on:
push:
branches: [main]
pull_request:
branches: [main]
# Add a permissions block at the workflow level
permissions:
contents: read
# Only add other permissions as strictly needed
env:
CHEF_LICENSE: accept-no-persist
jobs:
linux-matrix:
# Job configuration follows...
```
This practice follows the principle of least privilege and reduces the potential impact if a workflow is compromised by a malicious pull request or action.
---
## Eliminate repeated code
Reduce code duplication by extracting repeated patterns into variables, loops, or helper functions. When you find yourself writing similar lines of code multiple times, refactor to a more DRY (Don't Repeat Yourself) approach to improve maintainability and readability.
Example 1 - Refactor repetitive logging:
```powershell
# Before
Write-Host "Configuration File: $ConfigPath"
Write-Host $rawConfig
Write-Host "SelectionType: $Selection"
Write-Host "DisplayNameFilter: $DisplayNameFilter"
Write-Host "Filters: $Filters"
# After
$logEntries = @{
"Configuration File" = $ConfigPath
"Raw Configuration" = $rawConfig
"SelectionType" = $Selection
"DisplayNameFilter" = $DisplayNameFilter
"Filters" = $Filters
}
foreach ($key in $logEntries.Keys) {
Write-Host "$key: $($logEntries[$key])"
}
```
Example 2 - Store nested paths in variables:
```powershell
# Before
if ($yml["options"]["@azure-tools/typespec-csharp"]["package-dir"]) {
$packageDir = $yml["options"]["@azure-tools/typespec-csharp"]["package-dir"]
}
if ($yml["options"]["@azure-tools/typespec-csharp"]["service-dir"]) {
$service = $yml["options"]["@azure-tools/typespec-csharp"]["service-dir"]
}
# After
$csharpOpts = $yml["options"]["@azure-tools/typespec-csharp"]
if ($csharpOpts["package-dir"]) {
$packageDir = $csharpOpts["package-dir"]
}
if ($csharpOpts["service-dir"]) {
$service = $csharpOpts["service-dir"]
}
```
---
## Redact sensitive information
Always sanitize configuration data or any potentially sensitive information before logging or displaying it. When logging configurations, API responses, or user inputs, use pattern matching to identify and redact secrets, passwords, API keys, and other credentials.
Example implementation:
```powershell
# WRONG: Directly logging raw configuration
Write-Host $rawConfig
# CORRECT: Redacting sensitive information before logging
$safeConfig = $rawConfig -replace '(?i)(\"(password|secret|key)\":\s*\".*?\")', '"$1":"[REDACTED]"'
Write-Host $safeConfig
```
This pattern prevents accidental exposure of sensitive information in logs, console output, or error messages that might be viewed by unauthorized personnel or stored in insecure locations. Implement similar redaction mechanisms in all logging and output systems across your codebase.
---
## Check before dereferencing
Always verify objects are not null before dereferencing them, particularly when using methods that might return null like FirstOrDefault(), LastOrDefault(), or 'as' casts. Prevent NullReferenceExceptions by adding explicit null checks before accessing members.
// Risky code:
var lastContextualParameter = ContextualParameters.LastOrDefault();
if (parameter.Name.Equals(lastContextualParameter, StringComparison.InvariantCultureIgnoreCase))
{
// This will throw if lastContextualParameter is null
}
// Safe code:
var lastContextualParameter = ContextualParameters.LastOrDefault();
if (lastContextualParameter != null && parameter.Name.Equals(lastContextualParameter, StringComparison.InvariantCultureIgnoreCase))
{
// Only executes if lastContextualParameter is not null
}
For type conversions, prefer direct casts over 'as' when you expect the type to be present:
// Risky code:
(content.HttpContent as System.Net.Http.MultipartFormDataContent).Add(_dataStream, "file");
// Safe code - option 1 (direct cast):
((System.Net.Http.MultipartFormDataContent)content.HttpContent).Add(_dataStream, "file");
// Safe code - option 2 (explicit check):
var multipartContent = content.HttpContent as System.Net.Http.MultipartFormDataContent;
if (multipartContent != null)
{
multipartContent.Add(_dataStream, "file");
}
When using LINQ's Single() method, consider using FirstOrDefault() with null checking instead to handle cases where the element might not exist:
// Risky code:
var resource = convenienceMethod.Signature.Parameters
.Single(p => p.Type.Equals(ResourceData.Type));
// Safe code:
var resource = convenienceMethod.Signature.Parameters
.FirstOrDefault(p => p.Type.Equals(ResourceData.Type));
if (resource != null)
{
// Use resource
}
else
{
// Handle the case where no matching parameter exists
}
---
## Specific exceptions for clarity
Use specific exception types with meaningful error messages rather than generic exceptions to improve error handling, debugging, and API usability. This allows callers to distinguish between different error conditions and respond appropriately.
Instead of:
```csharp
if (string.IsNullOrEmpty(serviceEndpoint))
throw new Exception("Invalid service endpoint");
```
Prefer:
```csharp
if (string.IsNullOrEmpty(serviceEndpoint))
throw new ArgumentException("The service endpoint must be a valid URL", nameof(serviceEndpoint));
```
Key practices:
1. Match exception types to error conditions: Use `ArgumentException` for invalid arguments, `InvalidOperationException` for improper state, and `NotSupportedException` instead of `NotImplementedException` for unsupported operations.
2. Include actionable details in error messages: Specify what went wrong and how to fix it.
3. Use reliable error detection: Check specific exception properties or error codes rather than string matching:
```csharp
// Instead of:
catch (Exception ex) when (ex.Message.Contains("timed out"))
// Prefer:
catch (RequestFailedException ex) when (ex.Status == 408)
```
4. Validate assumptions explicitly: Check for null or invalid values before operations that assume they exist.
```csharp
// Instead of:
arguments.Add(methodParameters.Single(p => p.Name == parameter.Name));
// Prefer:
var matchingParameter = methodParameters.SingleOrDefault(p => p.Name == parameter.Name);
if (matchingParameter == null)
{
throw new InvalidOperationException($"No matching parameter found for '{parameter.Name}' in methodParameters.");
}
arguments.Add(matchingParameter);
```
---
## Approve AI dependencies conditionally
All AI-related dependencies (Microsoft.Extensions.AI.*, etc.) require explicit approval before inclusion and must be restricted to specific packages using conditional blocks in Packages.Data.props. Prefer version 8.x dependencies when available, and document any exceptions (such as using 9.x) with clear comments explaining the approval scope and reasoning.
```xml
```
---
## Configuration file completeness
Ensure all configuration files contain required fields, maintain proper structure, and follow consistent formatting standards. Configuration files should be complete with all mandatory nodes present, properly sorted for consistency, and preserve critical values that shouldn't be auto-updated.
Key practices:
- Validate that all required configuration nodes are present (e.g., chain_id, ibc_interface, channels)
- Maintain consistent JSON formatting using tools like `jq . config.json -S | sponge config.json`
- Categorize dependencies correctly (devDependencies vs dependencies in package.json)
- Preserve static configuration values that shouldn't change automatically (like deployment heights)
Example of proper structure validation:
```json
{
"deployments": {
"chain_id": "required-value",
"ibc_interface": "required-interface",
"channels": [1, 2, 3],
"core": {
"address": "0x...",
"height": 22242649 // should not auto-update
}
}
}
```
This prevents runtime errors, ensures environment consistency, and maintains configuration integrity across deployments.
---
## Document AI changes thoroughly
When updating AI libraries and SDKs, ensure all changes are thoroughly documented in changelogs with clear categorizations (Features Added, Breaking Changes) and explicit migration paths for breaking changes. For complex AI features, include links to detailed documentation.
Example of good documentation:
```markdown
## 1.1.0-beta.3 (2025-06-27)
### Features Added
- Tracing for Agents. More information [here](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/ai/Azure.AI.Agents.Persistent/README.md#tracing).
- Automatically function toolcalls. More information [here](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/ai/Azure.AI.Agents.Persistent/README.md#function-call-executed-automatically).
### Breaking Changes
- Support for project connection string and hub-based projects has been discontinued.
We recommend creating a new Azure AI Foundry resource utilizing project endpoint.
If this is not possible, please pin the version to `1.0.0-beta.8` or earlier.
```
For AI systems where behavior might not be immediately intuitive (like automatic function execution or new endpoint requirements), clear documentation helps users understand system capabilities and limitations, and reduces integration challenges.
---
## configuration value consistency
Ensure configuration values follow consistent formats, use meaningful defaults, and accurately distinguish between required and optional fields across all documentation.
Configuration inconsistencies can lead to user confusion and deployment failures. This standard addresses several critical areas:
**Format Consistency:**
- Time durations should include units: `deadPeriod: 2d` not `deadPeriod: 2`
- Environment variables should use proper syntax: `TRAEFIK_LOG_LEVEL="INFO"` not `TRAEFIK_LOG_LEVEL=INFO`
- CLI arguments should be properly quoted: `--providers.ecs.constraints="Label(\`key\`,\`value\`)"` not `--providers.ecs.constraints=Label(\`key\`,\`value\`)`
**Default Value Accuracy:**
- Avoid "N/A" or meaningless defaults in configuration tables
- Mark options as "Required" only when no meaningful default exists
- Use empty strings `""` for truly optional string fields
- Document when default values are environment-specific (e.g., `127.0.0.1:2379` for local testing only)
**Provider-Specific Differences:**
- Clearly document when Kubernetes CRD providers use different field names (e.g., `secret` instead of `users` for authentication)
- Include provider-specific examples for cross-provider configurations
- Note when certain options don't apply to specific providers
**Example of proper configuration documentation:**
```yaml
| Field | Description | Default | Required |
|-------|-------------|---------|----------|
| `redis.endpoints` | Redis server endpoints | `""` | Yes |
| `redis.db` | Database number | `0` | No |
| `redis.tls.insecureSkipVerify` | Skip TLS verification | `false` | No |
```
This approach prevents configuration errors and provides clear guidance for users across different deployment scenarios.
---
## Document code reasoning
Add clear, concise comments that explain the "why" behind complex logic, non-obvious decisions, and implicit behaviors. Focus on documenting:
1. **Algorithmic choices and control flow** - Explain why loops are broken, conditions are checked, or specific approaches are used.
```csharp
// Break if the next page is null
// Break the loop if the next page variable is null, indicating no more pages to process.
```
2. **Parameter handling details** - Document implicit conversions, default values, and edge cases.
```csharp
// The premiumPageBlobAccessTier parameter specifies the access tier for the page blob.
// If null, the REST API will apply the default tier or handle it gracefully.
```
3. **Version-specific logic or format handling** - Explain format parsing, version checks, or compatibility code.
```csharp
// This method checks if the format string in options.Format ends with the "|v3" suffix.
// The "|v3" suffix indicates that the ManagedServiceIdentity format is version 3.
// If the suffix is present, it is removed, and the base format is returned.
```
4. **Complex operations or type conversions** - Make non-obvious operations clear to future maintainers.
```csharp
// Convert ShareProtocols (multi-valued) to ShareProtocol (single-valued).
// If effectiveProtocol is ShareProtocols.Smb, map to ShareProtocol.Smb.
// Otherwise, default to ShareProtocol.Nfs.
```
Comments should benefit future maintainers by providing context that isn't immediately obvious from the code itself. When complex code can't be simplified, comprehensive documentation becomes essential for long-term maintainability.
---
## Standardize environment variables
Ensure environment variable names are consistently spelled, properly referenced, and follow established naming conventions across test files. Replace hardcoded values with environment variables for credentials, endpoints, and other configurable test parameters. Always provide meaningful defaults when environment variables aren't available to ensure tests can run in various environments.
```csharp
// Instead of hardcoding test values:
var principalId = "22fdaec1-8b9f-49dc-bd72-ddaf8f215577";
var tenantId = "72f988af-86f1-41af-91ab-2d7cd011db47";
var connectionId = TestEnvironment.SHAREPOINT_CONECTION_ID; // Typo!
// Use environment variables with fallbacks and correct naming:
var principalId = Environment.GetEnvironmentVariable("TEST_PRINCIPAL_ID") ?? "22fdaec1-8b9f-49dc-bd72-ddaf8f215577";
var tenantId = Environment.GetEnvironmentVariable("TEST_TENANT_ID") ?? "72f988af-86f1-41af-91ab-2d7cd011db47";
var connectionId = TestEnvironment.SHAREPOINT_CONNECTION_ID; // Fixed spelling
```
When defining environment variable names in test environments or documentation, follow consistent naming patterns like using all caps with underscores for separators. Double-check for typos, as misspelled environment variable names will silently return null values and may cause tests to fail in unexpected ways.
---
## Externalize configuration values
Store configuration values (URLs, demands, pool names) in centralized variables rather than hardcoding them inline. This improves maintainability, ensures consistency across the codebase, and simplifies future updates. When possible, group related configurations in dedicated template files or variable groups.
Example:
```yaml
# Instead of:
pool:
name: $(WINDOWSPOOL)
demands: ImageOverride -equals $(WINDOWSVMIMAGE)
# Prefer:
pool:
name: $(WINDOWSPOOL)
demands: $(IMAGE_DEMAND)
variables:
- name: IMAGE_DEMAND
value: ImageOverride -equals $(WINDOWSVMIMAGE)
```
For API endpoints, pipeline definitions, and other configuration values that may change over time, always use variables rather than hardcoding values directly in scripts or pipeline definitions.
---
## Descriptive consistent identifiers
Use clear, descriptive identifiers that accurately reflect their purpose, and maintain consistent naming patterns throughout the codebase. This applies to variables, parameters, methods, and configuration elements.
For variables:
- Choose names that convey the variable's specific role and content
- Avoid generic names like `$params` in favor of more specific names like `$invokeParams`
- Ensure variable names match their intended usage to prevent errors
For configuration elements:
- Maintain consistent patterns (singular/plural forms, prefixes/suffixes)
- Follow established conventions already present in surrounding code
Example of improved variable naming:
```powershell
# Poor naming - generic and potentially confusing
$params = @{
Method = 'GET'
Uri = $uri
}
return Invoke-RestMethod @params
# Better naming - clearly indicates purpose
$invokeParams = @{
Method = 'GET'
Uri = $uri
}
return Invoke-RestMethod @invokeParams
```
Example of consistent naming in configuration:
```xml
```
Descriptive and consistent naming reduces cognitive load for readers, prevents errors from misused variables, and makes the codebase more maintainable.
---
## Surface errors appropriately
Ensure errors are visible and properly handled rather than silently processed or hidden. Provide mechanisms for developers to handle errors explicitly, especially in libraries or frameworks with automated processes. Hidden or automatically handled errors can mask bugs and make debugging difficult.
When implementing automated processes:
1. Offer explicit error handling hooks or overridable methods
2. Consider logging errors appropriately before taking automated action
3. For retry mechanisms, follow service documentation for proper backoff strategies and durations
Example:
```csharp
// Instead of auto-handling errors silently:
options.EnableAutoFunctionCalls(delegates);
// Provide an override mechanism for error handling:
options.EnableAutoFunctionCalls(delegates, errorHandler: (exception, context) => {
// Log the error
logger.LogWarning($"Function call error: {exception.Message}");
// Allow custom handling logic
if (exception is TimeoutException)
return ErrorResolution.Retry;
else
return ErrorResolution.Rethrow;
});
```
When dealing with transient errors like throttling or service unavailability, implement retry policies that respect documented service requirements (e.g., retrying for adequate duration) rather than failing immediately or using generic retry strategies.
---
## Address not mask
Always address the root cause of CI/CD pipeline issues rather than masking them with quick fixes. This applies to encoding problems, build failures, and other CI-related issues.
Examples:
1. Remove BOM characters that cause encoding issues:
```diff
-
+
```
2. Don't remove configuration that causes build failures - fix the underlying issue instead:
```diff
1.2.0-beta.1
+
+ 1.1.2
```
When CI/CD pipelines fail, investigate the root cause rather than making superficial changes that only hide the problem. This ensures that real issues are properly addressed, maintaining the integrity and reliability of your build and deployment processes.
---
## Never commit secrets
Private cryptographic keys, certificates with private keys, and other secrets must never be committed to source code repositories, even in test or spec files. This is a critical security vulnerability that could lead to unauthorized access, impersonation, or system compromise.
When finding private keys in code like this:
```
-----BEGIN CERTIFICATE-----
MIIDRDCCAiygAwIBAgIBAzANBgkqhkiG9w0BAQsFADA4MQswCQYDVQQGEwJVUzEQ
...certificate content...
-----END CERTIFICATE-----
-----BEGIN RSA PRIVATE KEY-----
... private key content ...
```
Take immediate action:
1. Revoke the exposed keys to invalidate them
2. Generate new keys/credentials to replace the compromised ones
3. Remove all secrets from the codebase
4. Implement secure secret management
Security best practices for handling secrets:
- Use environment variables for sensitive information
- Implement dedicated secret management tools (HashiCorp Vault, AWS Secrets Manager, etc.)
- For test environments, use clearly marked dummy values or mock security components
- Add secret detection to CI/CD pipelines and pre-commit hooks
- Include secret files in .gitignore to prevent accidental commits
Properly managing cryptographic material ensures your systems remain secure and prevents costly security incidents resulting from leaked credentials.
---
## Use higher-level telemetry
When implementing observability for Azure services, prefer higher-level telemetry packages and configuration methods over low-level implementations. For Azure Monitor integration, use the Azure.Monitor.OpenTelemetry.AspNetCore package instead of the lower-level Azure.Monitor.OpenTelemetry.Exporter, as it provides simpler integration and is the recommended approach for most scenarios.
For enabling OpenTelemetry support, you can use either environment variables or programmatic configuration:
```csharp
// Option 1: Set environment variable (before application starts)
// AZURE_EXPERIMENTAL_ENABLE_ACTIVITY_SOURCE=true
// Option 2: Use AppContext.SetSwitch (preferred for programmatic control)
AppContext.SetSwitch("Azure.Experimental.EnableActivitySource", true);
// Use the recommended higher-level package
// Install: dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore
// Instead of the lower-level: Azure.Monitor.OpenTelemetry.Exporter
```
Using higher-level telemetry packages simplifies implementation, provides better defaults, and follows Azure SDK best practices for observability. This approach reduces the complexity of monitoring code and improves maintainability while ensuring comprehensive system visibility.
---
## User-friendly configuration values
Prefer intuitive, user-friendly values for configuration options over technical "magic strings" or codes that require special knowledge. This applies to both environment variables and programmatic configuration options.
When designing configuration options:
1. Use descriptive enumeration-like values when possible (e.g., 'global', 'usgov', 'china') rather than requiring users to remember specific technical identifiers
2. Document all valid values explicitly with proper code formatting
3. Support multiple configuration methods for the same setting when appropriate (environment variables and programmatic options)
4. Include clear examples in documentation
**Example:**
```csharp
// Instead of requiring a specific audience string:
clientOptions.AzureCloud = "https://management.azure.com/.default"; // Difficult to remember
// Provide user-friendly enumerated values:
clientOptions.AzureCloud = AzureCloudType.Global; // More intuitive
// Support both environment variables and programmatic configuration:
// In code:
clientOptions.Diagnostics = { IsTelemetryEnabled = false };
// Or via environment variable (documented in README):
// Set AZURE_TELEMETRY_DISABLED=true
```
For environment variables, document all accepted values and include examples showing both the variable name and possible values.
---
## ensure documentation completeness
Documentation should include all necessary information for users to successfully implement features. This includes providing complete configuration examples in all supported formats, documenting all available options, including prerequisites and setup requirements, and adding proper metadata.
Key completeness requirements:
- **Configuration formats**: Include examples for all applicable formats (YAML, TOML, CLI, Labels, Tags)
- **All options**: Document every configuration parameter, including optional ones with correct default values
- **Prerequisites**: Clearly state setup requirements (e.g., "Before creating IngressRoute objects, you need to apply the Traefik Kubernetes CRDs")
- **Metadata**: Include title and description meta tags for all documentation pages
- **Complete examples**: Show full working examples, not just partial configurations
Example of complete configuration documentation:
```yaml
# Configuration Options
| Field | Description | Default | Required |
|:------|:------------|:--------|:---------|
| `endpoint` | Server endpoint URL | "127.0.0.1:6379" | Yes |
| `headers` | Custom headers to send | {} | No |
# Examples
```yaml tab="File (YAML)"
providers:
http:
endpoint: "http://127.0.0.1:9000/api"
headers:
Authorization: "Bearer token"
```
```toml tab="File (TOML)"
[providers.http]
endpoint = "http://127.0.0.1:9000/api"
[providers.http.headers]
Authorization = "Bearer token"
```
```bash tab="CLI"
--providers.http.endpoint=http://127.0.0.1:9000/api
--providers.http.headers.Authorization="Bearer token"
```
Incomplete documentation forces users to search elsewhere or make assumptions, leading to implementation errors and poor user experience.
---
## Complete pipeline configurations
Ensure all CI/CD configuration files have their required fields properly populated with specific values rather than empty strings or placeholders. Missing or incomplete configuration values can cause pipeline failures, prevent proper asset publishing, or create unnecessary maintenance overhead. Regularly review configurations to validate they're accurate and still necessary.
**Example:**
```json
{
"AssetsRepo": "Azure/azure-sdk-assets",
"AssetsRepoPrefixPath": "net",
"TagPrefix": "net/bicep/Azure.ResourceManager.Resources.Bicep",
"Tag": "1.0.0" // Always include specific version tags, not empty strings
}
```
When specifying environment resources such as VM images or test pools, ensure they reference valid, current resources and periodically evaluate if custom resources are still needed to avoid maintaining unnecessary infrastructure.
---
## Version serializable structures
All serializable data structures that may evolve over time must include explicit versioning to enable backward and forward compatibility during migrations. This prevents breaking changes when schemas need to evolve and allows for graceful handling of different versions.
Implement versioning using enums that wrap versioned variants:
```rust
// Instead of this:
#[derive(serde::Serialize, serde::Deserialize)]
pub struct ClientState {
pub chain_id: U256,
pub latest_height: u64,
pub ibc_contract_address: H160,
}
// Do this:
#[derive(serde::Serialize, serde::Deserialize)]
pub enum ClientState {
V1(ClientStateV1),
}
#[derive(serde::Serialize, serde::Deserialize)]
pub struct ClientStateV1 {
pub chain_id: U256,
pub latest_height: u64,
pub ibc_contract_address: H160,
}
```
For message-based systems, include a version field and define compatibility rules - consumers should reject unsupported versions while maintaining backward compatibility for supported ones. This approach enables controlled schema evolution and prevents runtime failures during system upgrades.
---
## Write deterministic tests
Tests should be deterministic, reliable, and isolated from external dependencies to ensure consistent results across environments. To achieve this:
1. **Avoid direct network calls** that can introduce flakiness and slow down tests. Instead:
```csharp
// Don't do this in tests:
message.Request.Uri.Reset(new Uri("https://www.example.com"));
// Use one of these approaches instead:
// Option 1: Mock the transport
var mockTransport = new MockHttpClientTransport();
var options = new ClientOptions { Transport = mockTransport };
// Option 2: Use TestServer
var server = new TestServer();
var client = new Client(server.BaseAddress, options);
```
2. **Avoid using reflection in tests** as it creates brittle code that breaks when implementation details change. Instead, expose test-friendly mechanisms:
```csharp
// Avoid this:
var field = typeof(ServiceBusRetryPolicy).GetField("_serverBusyState",
System.Reflection.BindingFlags.NonPublic | System.Reflection.BindingFlags.Instance);
field.SetValue(policy, 1);
// Better approach: Add internal/protected methods for testing
// In production code:
internal void SetServerBusyStateForTesting(bool isBusy) { _serverBusyState = isBusy ? 1 : 0; }
```
3. **Use proper content comparison** for complex objects instead of reference equality:
```csharp
// Incorrect:
Assert.AreEqual(sourceStream, destinationStream); // Checks reference equality
// Correct:
byte[] sourceBytes = sourceStream.ReadAllBytes();
byte[] destinationBytes = destinationStream.ReadAllBytes();
Assert.AreEqual(sourceBytes.Length, destinationBytes.Length);
CollectionAssert.AreEqual(sourceBytes, destinationBytes);
```
4. **Replace fixed delays with polling** to avoid flaky tests and unnecessary wait times:
```csharp
// Avoid:
await Task.Delay(TimeSpan.FromSeconds(5));
// Better approach:
await WaitForConditionAsync(
async () => await client.GetStatus() == ExpectedStatus,
TimeSpan.FromSeconds(10), // Timeout
TimeSpan.FromMilliseconds(500) // Polling interval
);
```
These practices ensure tests remain stable across environments and over time, reducing maintenance costs and improving developer productivity.
---
## Pin and Inline CI
Harden CI/CD workflows by (1) pinning external actions/tool versions, (2) minimizing opaque third-party action wrappers when the underlying steps are small and deterministic, and (3) scoping dependency installation to the right workflow (local dev vs CI).
Apply these rules:
- Pin official actions/tooling to a specific version (avoid floating tags). If the organization has a policy for commit SHAs, follow it; otherwise use the action’s explicit version label for consistency.
- For simple tasks implemented by a third-party action that mainly runs a short command sequence, prefer maintaining the equivalent commands directly in your workflow (or a small in-repo script) to reduce audit/lock-down surface.
- Only add dependencies to common developer targets (e.g., `make dev`) when they are broadly needed. If a dependency is specialized/soon-to-change, keep it in CI where it’s required.
Example pattern:
```yaml
- name: Lock Go version
uses: actions/setup-go@v5
with:
go-version: '1.21'
- name: Install CI-only test dependency
run: |
make dev
pip install kong-pdk
```
---
## Complete authentication testing
Always verify both positive and negative authentication scenarios in your security tests. For each authentication mechanism, test that credentials are properly included when required and correctly absent when not needed. This comprehensive approach prevents potential authentication bypasses and ensures proper access control.
For example, when testing Authorization headers:
```csharp
// Test when authentication should NOT be applied
if (noAuthCondition)
{
Assert.IsFalse(request.Headers.TryGetValue("Authorization", out _),
"Request should not have an Authorization header.");
}
// Test when authentication SHOULD be applied
else
{
Assert.IsTrue(request.Headers.TryGetValue("Authorization", out var authHeader),
"Request should have an Authorization header.");
Assert.IsFalse(string.IsNullOrEmpty(authHeader),
"Authorization header should be populated.");
}
```
This pattern ensures your authentication mechanisms work correctly in all scenarios, which is critical for maintaining security boundaries.
---
## Preserve protocol data integrity
When working with network protocols (like AMQP, NFS, or SMB), maintain the integrity of the original protocol data structures during serialization, deserialization, and transformation operations. Modifying protocol-specific data can lead to unintended changes in the service contract and unexpected behavior for clients.
For message-based protocols:
- Avoid mutating the underlying protocol representation when converting to language-specific objects
- Perform type normalization only on your application's representation of the data, not on the protocol layer
- Document how special cases are handled when converting between protocol formats
Example from AMQP handling:
```csharp
// Incorrect: Directly modifying protocol data
amqpMessage.Properties.ContentType = normalizedContentType; // Mutates original AMQP data
// Correct: Keep protocol representation intact, normalize only in your model
EventData eventData = new EventData(amqpMessage);
eventData.ContentType = normalizedContentType; // Only the .NET projection is affected
```
For file transfer protocols:
- Clearly document how specialized elements (like symbolic links, hard links) are handled
- Ensure consistent behavior across different transfer operations
- Preserve protocol-specific properties where possible to maintain compatibility
---
## Use descriptive names
Choose names that clearly express the purpose, behavior, or semantic meaning of variables, functions, and types. Avoid ambiguous or generic names that require additional context to understand their role.
Key principles:
- Make boolean nature explicit: `regex` → `isRegex`
- Describe actual functionality: `ParseDomainsAndRegex` → `ParseHostMatchers`
- Clarify behavior over generic terms: `CustomResponseWriter` → `StatusRecorder`
- Distinguish between similar concepts: `FailTimeout` → `FailureWindow` (time window vs timeout duration)
- Be explicit about quantities: `MaxFails` → `MaxFailedAttempts`
- Align with actual logic: `down` → `up` when variable represents "up" status
- Use explicit constants over magic values: `defaultCacheDuration` instead of `cache.DefaultExpiration`
Example:
```go
// Ambiguous - what kind of timeout?
type PassiveHealthCheck struct {
FailTimeout ptypes.Duration
MaxFails int
}
// Clear - describes the time window and explicit count
type PassiveHealthCheck struct {
FailureWindow ptypes.Duration
MaxFailedAttempts int
}
```
This approach reduces cognitive load, prevents misunderstandings, and makes code self-documenting.
---
## Centralize pipeline configurations
Use centralized templates and variables for pipeline configurations instead of duplicating or hardcoding values. This improves maintainability, ensures consistency, and makes platform-specific adaptations easier to manage.
Key practices:
1. Reference existing templates from `/eng/pipelines/templates/` instead of creating duplicates
2. Include the image variables template `/eng/pipelines/templates/variables/image.yml` in pipelines that reference VM images
3. Use pool variables (LINUXPOOL, WINDOWSPOOL, MACPOOL) for pool names
4. Use demand-based configuration for Windows/Linux and vmImage pattern for Mac
Example:
```yaml
# Good practice
variables:
- template: /eng/pipelines/templates/variables/image.yml
jobs:
- job: BuildAndTest
pool:
name: $(WINDOWSPOOL)
demands: $(WindowsImageDemand)
```
Instead of:
```yaml
# Avoid this approach
jobs:
- job: BuildAndTest
pool:
name: azsdk-pool-mms-win-2022-general
vmImage: windows-2022
```
This approach makes it easier to update image configurations across all pipelines and supports platform-specific configuration patterns.
---
## Document non-obvious code
Add clarifying comments to code elements whose purpose or behavior may not be immediately apparent to other developers. This includes conditional logic blocks, empty configuration properties, and any code structures whose intent requires context to understand.
For conditional logic:
```yaml
steps:
# Restrict the following steps to pull request builds only
- task: PowerShell@2
condition: eq(variables['Build.Reason'], 'PullRequest')
# ... remainder of task
```
For configuration properties:
```yaml
directory: specification/liftrmongodb/MongoDB.Atlas.Management
commit: 6a4f32353ce0eb59d33fd785a512cd487b81814f
repo: Azure/azure-rest-api-specs
# Reserved for specifying additional specification directories if needed
additionalDirectories:
```
Clear documentation reduces the cognitive load for reviewers and future maintainers, helping them understand the code's purpose without needing to infer it from implementation details.
---
## Match CI commands locally
Always use the same build and test commands locally that are used in your CI pipeline to ensure consistency between environments. This practice significantly increases the likelihood that code passing locally will also pass in CI, reducing integration delays and failed builds.
For example, instead of using custom build commands or shortcuts, use the exact commands from your pipeline:
```bash
# Instead of:
dotnet build ./myproject.csproj
# Use the CI-equivalent command:
dotnet pack eng/service.proj /p:ServiceDirectory=
dotnet test eng/services.proj /p:ServiceDirectory=
```
This approach helps identify issues earlier in the development process and prevents situations where code passes locally but fails in CI due to environmental differences or non-standard configurations. When everyone on the team follows this practice, it also ensures consistency across developer environments and reduces troubleshooting time for CI failures.
---
## Standardize shell flags
Always use `set -eou pipefail` at the beginning of shell scripts to ensure consistent error handling and behavior across the codebase. This combination provides important safety guarantees:
- `-e`: Exit immediately if any command exits with non-zero status
- `-o`: Error on undefined variables instead of treating them as empty
- `-u`: Treat unset variables as an error
- `pipefail`: Return value of a pipeline is the status of the last command to exit with non-zero status
Example:
```sh
# Incorrect
set -eu -o pipefail
# or
set -evx
# Correct
set -eou pipefail
```
This standard helps prevent subtle bugs caused by unhandled errors or undefined variables and makes scripts more robust and predictable.
---
## Standardize bash error-handling
Always use `set -eou pipefail` at the beginning of bash scripts to ensure consistent and robust error handling. This combination ensures scripts fail immediately on errors (`-e`), treat unset variables as errors (`-u`), and properly handle pipeline failures (`-o pipefail`), preventing silent failures and making debugging easier.
```bash
# Good practice
#!/bin/bash
set -eou pipefail
# Rest of your script
```
---
## Handle external process errors
When calling external processes (like dotnet, msbuild, etc.), always implement proper error handling and output management:
1. Check exit codes to detect failures and propagate errors
2. Display command output to users for visibility
3. Prevent command output from polluting the PowerShell pipeline
4. Ensure proper cleanup of resources even when errors occur
```powershell
# Bad practice - no error handling, output pollutes pipeline
dotnet msbuild $ServiceProj /p:ServiceDirectory=$serviceDirectory
# Good practice - handles errors, displays output, doesn't pollute pipeline
$outputFilePath = Join-Path ([System.IO.Path]::GetTempPath()) "temp-$([System.Guid]::NewGuid()).txt"
try {
# Display output but don't pollute pipeline
dotnet msbuild $ServiceProj /p:ServiceDirectory=$serviceDirectory | Out-Host
if ($LASTEXITCODE -ne 0) {
throw "MSBuild failed with exit code $LASTEXITCODE"
}
# Process results...
}
finally {
# Clean up resources even if an error occurred
if (Test-Path $outputFilePath) {
Remove-Item -Path $outputFilePath -Force | Out-Host
}
}
```
This approach ensures scripts fail fast when external processes fail, preserves error visibility, maintains clean function return values, and properly manages resources.
---
## validate input uniqueness
Always validate that input data is unique and matches expected values to prevent replay attacks and data manipulation vulnerabilities. This includes checking for duplicate submissions and verifying data integrity through hash comparisons.
Key validation patterns:
1. **Prevent duplicate data attacks**: Ensure that the same data cannot be submitted multiple times to create false evidence or bypass security checks
2. **Verify data consistency**: Confirm that related data fields match expected values (e.g., block hashes match attestation data)
3. **Implement uniqueness checks**: Add explicit validation to reject identical inputs that could be used maliciously
Example implementation:
```rust
// Prevent duplicate attestation attacks
if misbehaviour.attestation_1.number != misbehaviour.attestation_2.number {
// Additional checks needed here to ensure attestations are truly different
// and not the same data provided twice
}
// Verify hash consistency
if block.hash() != vote_attestation.data.source_hash {
return Err(Error::HashMismatch);
}
```
This validation is critical for preventing attackers from exploiting duplicate or inconsistent data to bypass security mechanisms or create false evidence of misbehaviour.
---
## Log effectively for debugging
Always include meaningful log messages at appropriate levels to aid in debugging and system monitoring. Follow these guidelines:
1. **Never silently swallow errors** - Even during cleanup operations, log errors that might be helpful for debugging:
```go
// Bad: Silently ignoring errors
os.Chdir(oldDir)
// Good: Log errors even if they're not fatal
if err := os.Chdir(oldDir); err != nil {
log.Printf("[WARN] cleanup error during directory change: %v", err)
}
```
2. **Use appropriate log levels** based on severity:
- `[TRACE]` - For detailed debugging information
- `[DEBUG]` - For information useful during development
- `[INFO]` - For normal operations that completed successfully
- `[WARN]` - For recoverable problems or retryable operations
- `[ERROR]` - For failures that impact functionality
```go
// Bad: Using INFO for a failure condition
logger.Printf("[INFO] failed to fetch provider package; retrying")
// Good: Using WARN for a retryable failure
logger.Printf("[WARN] failed to fetch provider package; retrying attempt %d/%d", i, maxHTTPPackageRetryCount)
```
3. **Include sufficient context** in log messages to make them actionable:
- Identify the component/function in the message
- Include relevant variables and state information
- For complex operations, log inputs and outputs
```go
// Bad: Generic log message
log.Printf("[ERROR] no module call found")
// Good: Contextual log message
log.Printf("[ERROR] %s: no module call found in %q for %q", funcName, parent.Path, calledModuleName)
```
4. **Add trace logs for complex operations** that might need debugging in the future:
```go
// In functions with complex parsing or processing
log.Printf("[TRACE] extractImportPath input: %q", fullName)
```
Always consider how logs will be used by developers, operators, and users when troubleshooting issues in production environments.
---
## Prefer identity-based authentication
Always prioritize modern identity-based authentication methods over traditional username/password credentials. This improves security by reducing credential exposure and management overhead.
Specifically:
- Use managed identities where available in Azure services
- Consider federated identity credentials for cross-service authentication
- Leverage Entra User authentication instead of username/password for administrative access
This approach eliminates the need to store and manage sensitive credentials in your code or configuration files, reducing the risk of credential leakage.
Example implementation for using managed identity with a client factory:
```csharp
// Configure the client factory to use managed identity
builder.Services.AddAzureClients(clientBuilder =>
{
// Using managed identity as a federated identity credential
clientBuilder.UseCredential("managedidentityasfederatedidentity")
.ConfigureDefaults(azureDefaults =>
{
azureDefaults.Authentication.ManagedIdentityClientId = "your-client-id";
});
});
```
When creating services like HDInsight clusters, prefer specifying Entra User as the administrator credential rather than username/password combinations.
---
## use Effect Option consistently
Replace null, undefined, and error throwing with Effect's Option type for handling potentially missing values. This provides better type safety, composability, and prevents null reference errors.
Instead of returning null:
```typescript
// ❌ Avoid
getBannerForEdition(edition: "app" | "btc"): BannerConfig | null {
// ...
}
// ✅ Prefer
getBannerForEdition(edition: "app" | "btc"): Option.Option {
// ...
}
```
Instead of using undefined:
```typescript
// ❌ Avoid
address = $state(undefined)
// ✅ Prefer
address = $state>(Option.none())
```
Instead of throwing errors for missing values:
```typescript
// ❌ Avoid
export function evmDisplayToCanonical(displayAddress: string): Uint8Array {
if (!/^0x[0-9a-fA-F]{40}$/.test(displayAddress)) {
throw new Error("EVM address must be 0x followed by 40 hex characters")
}
// ...
}
// ✅ Prefer
export function evmDisplayToCanonical(displayAddress: AddressEvmDisplay): Option.Option {
// validation handled by schema, return Option for safety
// ...
}
```
Option provides a composable API with methods like `map`, `flatMap`, and `getOrElse` that make handling optional values more explicit and less error-prone than null checks.
---
## Maintain clean code structure
Keep code clean and well-organized by:
1. Removing unnecessary elements:
- Delete commented-out code that is no longer needed
- Remove unused using directives
- Avoid redundant code blocks
2. Organizing imports properly:
- Group using directives consistently (System namespaces first)
- Use clean imports instead of fully qualified names
- Keep imports ordered alphabetically
Example - Before:
```csharp
using Azure.Core;
using System.Threading;
using System.Linq.Enumerable;
// Old implementation
// public void OldMethod() {
// // ...
// }
using System;
public class MyClass
{
public void ProcessItems()
{
if (System.Linq.Enumerable.Any(items)) // Verbose qualification
{
// ...
}
}
}
```
After:
```csharp
using System;
using System.Linq;
using System.Threading;
using Azure.Core;
public class MyClass
{
public void ProcessItems()
{
if (items.Any()) // Clean syntax with proper imports
{
// ...
}
}
}
```
---
## Guard shared state
Consistently protect shared state with appropriate synchronization mechanisms and ensure proper cleanup to prevent race conditions and deadlocks in concurrent environments.
When working with shared state:
1. **Protect all access to shared variables** with the same mutex, including both reads and writes
2. **Use `defer` statements to guarantee lock releases**, especially in functions with multiple return paths
3. **Consider synchronized accessor methods** instead of direct access to shared data structures
4. **Be consistent about mutex design patterns** - whether embedding or using as a field
```go
// BAD: Data race - accessing 'closed' without mutex protection
func (c *proxyCommandConn) Read(b []byte) (int, error) {
if c.closed { // Race condition here!
return 0, io.EOF
}
return c.stdoutPipe.Read(b)
}
// GOOD: Protected access to shared state
func (c *proxyCommandConn) Read(b []byte) (int, error) {
c.mutex.Lock()
if c.closed {
c.mutex.Unlock()
return 0, io.EOF
}
c.mutex.Unlock()
return c.stdoutPipe.Read(b)
}
// GOOD: Using defer for guaranteed unlock
func (l *Loader) LoadState(configPath string) (*states.State, tfdiags.Diagnostics) {
// ... other code ...
id, err := stateManager.Lock(statemgr.NewLockInfo())
if err != nil {
return state, diags.Append(/* error */)
}
defer stateManager.Unlock(id) // Ensures unlock happens on all return paths
// ... rest of function with potentially multiple return statements ...
}
// GOOD: Using synchronized accessor method
func (ctx *EvalContext) Variables() map[string]cty.Value {
// Returns a new map with synchronized access internally
// instead of directly exposing a shared map
}
```
---
## avoid unnecessary Arc wrapping
Don't wrap atomic types in Arc unless you need to share ownership across multiple owners. Atomic types like AtomicBool, AtomicU64, etc. are already thread-safe and can be used directly in structs that will be wrapped in Arc at a higher level.
Using Arc creates unnecessary indirection and allocation overhead when AtomicBool alone provides the required thread safety. The Arc should be applied at the struct level that contains the atomic field, not around individual atomic fields.
Example of the anti-pattern:
```rust
struct Impl {
sender: mpsc::SyncSender>,
write_shutdown: Arc, // Unnecessary Arc
}
```
Preferred approach:
```rust
struct Impl {
sender: mpsc::SyncSender>,
write_shutdown: std::sync::atomic::AtomicBool, // Direct atomic type
}
// Wrap the entire struct in Arc when sharing is needed
let impl_instance = Arc::new(Impl::new(...));
```
This reduces memory overhead, eliminates unnecessary heap allocation, and simplifies the code while maintaining the same thread safety guarantees.
---
## Use appropriate API methods
When integrating with external APIs or implementing interface methods, ensure you're using the correct API calls for your intended functionality. Consult the official documentation and examples to understand the purpose and proper usage of different methods.
Common issues include:
- Using low-level execution APIs when high-level container management APIs are more appropriate
- Implementing incomplete interface methods without returning required object types
- Not following the documented API patterns and object models
For example, when working with Docker APIs, use `create_container()` and `start_container()` for container lifecycle management rather than `start_exec()` for command execution:
```rust
// Correct approach for container management
let config = ContainerCreateBody {
image: Some(container_name.clone()),
cmd: Some(entrypoint),
env: Some(env),
..Default::default()
};
docker.create_container(Some(options), config).await?;
docker.start_container(&container_name, None::).await?;
```
When implementing RPC interfaces, ensure you return the correct object types as specified in the interface definition:
```rust
// Implement required server interface and return proper object type
fn get_tcp_port(&mut self, params: container::GetTcpPortParams, results: container::GetTcpPortResults) -> Promise<(), capnp::Error> {
// Must implement rpc::Container::Port::Server and return that object
}
```
Always reference the official documentation, API specifications, and existing examples to verify you're using the intended methods for your use case.
---
## Explicit protocol interfaces
Design protocol interfaces with explicit behavior definitions rather than relying on implicit conventions. Clearly specify the purpose and expected handling of each field, especially when adding new parameters or response structures.
When adding fields to protocols:
1. Document whether fields are advisory or required
2. Specify if consumers or providers are responsible for enforcing constraints
3. Use explicit fields rather than inferred behavior from configuration
4. Structure messages for future extensibility
For example, when adding a request parameter like `include_resource_object`, make its purpose and handling explicit in the protocol:
```protobuf
message ListResource {
message Request {
// When include_resource_object is set to true, the provider should
// include the full resource object for each result
bool include_resource_object = 3;
}
}
```
Similarly, consider forward compatibility when designing response structures. Avoid constructs like `oneof` when they might restrict valid combinations:
```protobuf
// Avoid this pattern if both fields might be needed simultaneously
message Event {
oneof response {
Result result = 1;
Diagnostic diagnostic = 2; // Cannot return diagnostics with results
}
}
// Better approach allowing both fields together
message Event {
Result result = 1;
repeated Diagnostic diagnostics = 2;
}
```
For future extensibility, nest related fields in sub-messages that can evolve independently:
```protobuf
message Request {
message Mapping {
map resource_address_map = 1;
map module_address_map = 2;
}
// Can later extend with additional mapping types
oneof mapping {
Mapping simple = 1;
}
}
```
Explicit interfaces lead to more robust integrations, fewer bugs from misunderstood expectations, and easier evolution of your API over time.
---
## Ensure semantic precision
Choose names and identifiers that precisely convey their intended semantic meaning and avoid ambiguity or conflicts. Names should be specific enough to prevent confusion and clearly communicate their purpose within the codebase.
For type definitions, prefer semantically precise types over generic ones when the distinction matters. For example, use `{}` (explicitly empty object) rather than `object` when you specifically need an empty type:
```typescript
export type SwitchChainState = Data.TaggedEnum<{
InProgress: {} // Explicitly empty, not just any object
}>
```
For class and tag names, ensure uniqueness across the application by using descriptive prefixes or suffixes when necessary:
```typescript
// Instead of generic names that might conflict
export class SuiPublicClientSource extends Context.Tag("SuiPublicClientSource")
export class SuiPublicClientDestination extends Context.Tag("SuiPublicClientDestination")
```
This practice prevents naming conflicts, reduces cognitive load when reading code, and makes the codebase more maintainable by ensuring each identifier has a clear, unambiguous meaning.
---
## Craft actionable errors
Create error messages that provide precise context, avoid unnecessary details, and give users clear actions to take. Error messages should include location information when possible, avoid jargon, and maintain a consistent tone without being patronizing.
When reporting errors from the UI:
1. Include relevant context like resource names or locations
2. Use source locations (`Subject` field) when available
3. Exclude technical details that don't help users solve the problem
4. Clearly state what action is needed to fix the issue
**Bad:**
```go
diags = diags.Append(tfdiags.Sourceless(
tfdiags.Warning,
"Output change in sensitivity",
fmt.Sprintf("A previously sensitive output is being changed to insensitive: %q.", outputName),
))
```
**Good:**
```go
diags = diags.Append(&hcl.Diagnostic{
Severity: hcl.DiagWarning,
Summary: "Output change in sensitivity",
Detail: fmt.Sprintf("Sensitivity of the output %q changed. By doing so, the value will not be obfuscated anymore.", oc.Name),
Subject: oc.DeclRange.Ptr(),
})
```
When joining multiple errors, use `errors.Join()` with a clear leading message:
```go
errs = append([]error{fmt.Errorf("decryption failed for all provided methods")}, errs...)
errMessage := errors.Join(errs...).Error()
```
For API/provider references, use a consistent style:
```go
diags = diags.Append(&hcl.Diagnostic{
Severity: hcl.DiagError,
Summary: "Reference to undeclared key provider",
Detail: fmt.Sprintf("There is no key_provider %q %q block declared in the encryption block.", depType, depName),
})
```
---
## Fail gracefully always
Ensure code handles errors robustly by using protective patterns that prevent resource leaks, provide clear diagnostics, and degrade gracefully when possible:
1. **Use resource cleanup patterns** - Prefer block forms for resource management to ensure cleanup happens even during exceptions:
```ruby
# Good: Resources automatically closed after block
TargetIO::File.open(tempname, "w") do |tempfile|
tempfile.write(crontab)
end
# Bad: Manual cleanup may be missed on exception paths
tempfile = TargetIO::File.open(tempname, "w")
tempfile.write(crontab)
tempfile.close # Might never execute if an exception occurs
```
2. **Validate related parameters together** - Check parameter dependencies upfront:
```ruby
# Good: Clear validation of dependent parameters
def define_resource_requirements
requirements.assert(:install, :upgrade) do |a|
a.assertion { new_resource.proxy_user.nil? == new_resource.proxy_password.nil? }
a.failure_message("Both proxy_user and proxy_password must be specified together")
end
end
```
3. **Handle expected failures gracefully** - Catch specific exceptions to provide fallbacks:
```ruby
# Good: Handle missing command gracefully
def loop_mount_points
@loop_mount_points ||= shell_out!("losetup -a").stdout
rescue Errno::ENOENT
"" # Return empty string if command doesn't exist
end
```
4. **Use appropriate exception types** - Choose domain-specific exceptions to accurately represent errors:
```ruby
# Good: Domain-specific exception
raise Chef::Exceptions::Service, "systemctl show not reporting status for #{service_name}!"
# Bad: Using generic or misleading exception type
raise Mixlib::ShellOut::ShellCommandFailed, "Error message" # Implies shell command failed
```
5. **Provide clear, actionable error messages** - Check specific conditions and give targeted feedback:
```ruby
# Good: Check existence before permissions
if !File.directory?(File.dirname(file))
ui.fatal "Directory #{File.dirname(file)} does not exist"
exit 1
elsif !File.writable?(File.dirname(file))
ui.fatal "Directory #{File.dirname(file)} is not writable. Check permissions."
exit 1
end
```
Following these patterns will create more resilient code that fails predictably, provides clear diagnostics, and properly manages resources even during failures.
---
## document workflow capabilities
Workflow methods should include comments that document their orchestration capabilities and data access patterns. This helps developers understand the available temporal execution features and interaction methods.
Key areas to document:
- Data access patterns (bindings via `this.env`, parameters via `event.payload`)
- Orchestration capabilities (waiting for external events, human approval, webhooks)
- External interaction endpoints (HTTP POST patterns for submitting data to workflow instances)
Example:
```javascript
async run(event, step) {
// Can access bindings on `this.env`
// Can access params on `event.payload`
const files = await step.do("my first step", async () => {
// Fetch a list of files from $SOME_SERVICE
return { files: [...] };
});
// You can optionally have a Workflow wait for additional data,
// human approval or an external webhook or HTTP request before progressing.
// You can submit data via HTTP POST to /accounts/{account_id}/workflows/{workflow_name}/instances/{instance_id}/events/{eventName}
}
```
This documentation pattern ensures workflow code is self-explanatory about its durable execution capabilities and helps maintain clarity in complex orchestration scenarios.
---
## workflow documentation clarity
Ensure all workflow-related documentation, help text, and code comments use proper grammar and punctuation. Workflow systems involve complex orchestration, retries, and fault tolerance mechanisms that require clear, professional documentation for maintainability and developer understanding.
Pay special attention to:
- Proper comma usage in lists and clauses
- Clear sentence structure in workflow descriptions
- Professional formatting of code comments explaining workflow behavior
Example of proper formatting:
```typescript
// You can optionally have a Workflow wait for additional data,
// human approval or an external webhook or HTTP request, before progressing.
// Help text should read:
// "For multi-step applications that automatically retry, persist state, and run for minutes, hours, days or weeks"
```
Well-documented workflows reduce onboarding time and prevent misunderstandings about complex temporal execution patterns.
---
## validate input constraints
Always validate user inputs against expected formats, constraints, and business rules before processing them. Implement explicit validation checks that fail fast with clear error messages when inputs don't meet requirements. This prevents security vulnerabilities from malformed or malicious inputs.
Example from Bech32 address validation:
```typescript
Effect.flatMap(decoded => {
if (decoded.prefix !== prefix) {
return Effect.fail(
new Bech32DecodeError({
message: `Given prefix "${decoded.prefix}" does not match requirement "${prefix}"`,
}),
)
}
// Continue processing only after validation passes
})
```
This approach is especially critical for user-facing inputs like addresses, identifiers, and configuration values that could be manipulated to exploit system vulnerabilities.
---
## Specify configuration behaviors
When implementing configuration features (variables, flags, resources), thoroughly document their behavior in all scenarios, especially edge cases and interactions with dependencies. Configuration options should have well-defined and tested behaviors across all contexts where they might be used.
For features like ephemeral resources, variable marks, or command flags like `-exclude`, ensure you clearly specify:
- How marks propagate and interact with other systems
```hcl
# When using ephemeral variables, document if and how the mark propagates
variable "secret" {
type = string
ephemeral = true
}
locals {
# Does this local automatically become ephemeral too?
config = "${var.secret}_suffix"
}
```
- Dependencies and cascading effects
```hcl
# When implementing features like -exclude, document how dependencies are handled
# For example, when excluding resource A that resource B depends on:
resource "null_resource" "a" {}
resource "null_resource" "b" {
triggers = {
a_id = null_resource.a.id
}
}
# Document: Will `tofu plan -exclude=null_resource.a` also exclude resource B?
```
- Behavior during different execution phases (plan vs apply)
- Edge cases like non-existent resources, empty collections, or conflicting settings
When introducing new marks or configuration attributes, thoroughly test their interactions with existing marks to prevent subtle bugs. For example, ensure `sensitive()` doesn't accidentally strip ephemeral marks, and that marked values maintain their properties when transformed or combined.
---
## Externalize sensitive credentials
Never hardcode sensitive values such as client identifiers, API keys, connection strings, or passwords directly in code or configuration files. Instead, use secure mechanisms like environment variables, secret managers, or pipeline variable groups to inject these values at runtime. This practice reduces the risk of credential exposure in version control systems and unauthorized access if the repository is compromised.
Example:
```yaml
# Avoid this:
task: EsrpRelease@9
inputs:
ClientId: '5f81938c-2544-4f1f-9251-dd9de5b8a81b'
# Do this instead:
task: EsrpRelease@9
inputs:
ClientId: $(ClientId)
```
---
## Clear relationship descriptions
When documenting algorithms or data structures with graph-like relationships, use precise terminology to describe connections between elements. This is especially important when explaining how operations traverse or transform structured data.
Distinguish explicitly between direct relationships and hierarchical ones to avoid implementation ambiguity. For example:
Instead of:
```
Remove vertices that are in (or children of items in) t.Excludes
```
Prefer:
```
Remove vertices that are in t.Excludes, or descendants of items in t.Excludes
```
Similarly, when describing behavioral relationships between components, use precise comparative language:
Instead of:
```
Method A should behave similarly with Method B
```
Prefer:
```
Method A should behave similarly to Method B
```
This precision prevents misinterpretation when implementing complex algorithms and makes relationships between components immediately clear to all readers, which is crucial when working with graph transformations, dependency trees, or other hierarchical data structures.
---
## Effect-based API clients
Use Effect-based HTTP clients with specific error types instead of throwing generic exceptions or relying on third-party HTTP libraries like axios. API functions should return Effects with proper error types rather than throwing errors, enabling better error handling and composability.
Instead of extending third-party clients or using axios directly:
```typescript
// ❌ Avoid - throws errors, uses axios
async queryContractSmartAtHeight(contract: string, queryMsg: Record, height: number) {
const resp = await axios.get(url, { headers: { "x-cosmos-block-height": height.toString() } })
if (resp.status < 200 || resp.status >= 300) {
throw new Error(`HTTP ${resp.status}: ${JSON.stringify(resp.data)}`)
}
return resp.data
}
```
Use effectful wrappers with specific error types:
```typescript
// ✅ Preferred - Effect-based with specific errors
export type FetchDecodeGraphqlError = GraphQLError | Persistence.PersistenceError | ParseError
export const fetchDecodeGraphql = (
schema: Schema.Schema,
document: TadaDocumentNode,
variables?: V,
): Effect.Effect =>
Effect.andThen(GraphQL, ({ fetch }) =>
pipe(
fetch(new GraphQLRequest({ document, variables })),
Effect.flatMap(Schema.decodeUnknown(schema))
)
)
```
This approach provides meaningful error information, enables proper error composition, and maintains consistency with the Effect-based architecture throughout the codebase.
---
## Defensive null value handling
Always handle potential null/None values defensively by:
1. Using `.get()` for dictionary access instead of direct key access
2. Checking for None/falsy values before accessing their properties
3. Initializing None defaults explicitly rather than using mutable defaults
Example:
```python
# Bad:
def process_response(response):
items = response['items'] # May raise KeyError
return items['data'] # Nested access compounds risk
# Good:
def process_response(response, extra_params=None):
if extra_params is None:
extra_params = {}
items = response.get('items')
if not items: # Handles None and empty dict
return None
return items.get('data') # Safe nested access
```
This pattern:
- Prevents KeyError exceptions from missing dictionary keys
- Avoids NoneType attribute errors
- Maintains consistent return types
- Makes null cases explicit and intentional
- Improves code robustness and maintainability
---
## Choose semantic algorithms
Select algorithms and data operations that match the semantic intent of your code rather than using convenient but potentially problematic approaches. For operations like version comparisons, string parsing, and collection filtering, choose specialized methods over generic ones.
For version comparisons:
```ruby
# Avoid unreliable approaches like timestamp comparison
# BAD
latest_version_dir = versions.max_by { |v| File.mtime(v) }
# GOOD - Use semantic version comparison
latest_version_dir = versions.max_by { |v| Gem::Version.new(File.basename(v)) }
```
For string parsing, prefer structured operations over complex regex when appropriate:
```ruby
# Overly complex regex
z = t.match(/(^pub:.?:\d*:\d*:\w*:[\d-]*):/)
# More maintainable approach
fields = t.split(':')
z = fields[0..4].join(':') if fields.size >= 5
```
For collection operations, choose methods that properly handle the data structure:
```ruby
# Limited to checking a single action
options[:required].include?(action)
# Properly handles multiple actions
(options[:required] & Array(action)).any?
```
Remember that algorithm selection significantly impacts code reliability, maintainability, and performance. Choose algorithms that reflect the true intent of the operation rather than just what seems convenient.
---
## Document reference standards
Maintain consistent and accurate reference practices throughout project documentation to enhance usability and maintainability. This includes:
1. **Verify link accuracy**: Ensure all document cross-references point to the correct filenames and paths. Double-check file extensions and names before submitting changes.
2. **Follow consistent linking conventions**: When referencing work in changelogs and release notes:
- Link to issues for functional descriptions and design decisions
- Link to PRs for technical implementation details
- For larger features with multiple PRs, prefer linking to tracking issues
3. **Avoid redundancy**: Instead of duplicating information across multiple documentation files, reference a single source of truth:
```markdown
## Compatibility
For detailed compatibility information, see the [Migration Guide](https://example.org/docs/migration/).
```
Rather than:
```markdown
## Compatibility
- Version 1.6.2 is compatible with Tool X version 1.5.x
- Version 1.7.0 is compatible with Tool X version 1.6.x
```
Following these standards reduces maintenance burden and ensures that users can consistently find the most current and accurate information.
---
## use meaningful error types
Replace generic exceptions with context-specific error types that provide meaningful information about what went wrong. When wrapping errors from external libraries, always use the correct error types from those libraries and extract error details to preserve debugging information.
Avoid generic error classes like `NoSuchElementException` or `Error` with string messages. Instead, create domain-specific error types that capture the context and cause of the failure.
When integrating with external libraries, use their specific error types rather than importing error types from unrelated libraries. Always call `extractErrorDetails()` when wrapping external errors to preserve stack traces and debugging information.
Example of what to avoid:
```typescript
// Generic, uninformative error
transferDetails.error = Option.some({ _tag: "NotFound", message: "Transfer not found" })
// Wrong error type from different library
catch: err => new FetchAptosTokenBalanceError({ cause: err as ReadContractErrorType })
// Generic error with string interpolation
catch: e => new Error(`Failed to fetch blockNumber for ${rpc}: ${String(e)}`)
```
Example of proper error handling:
```typescript
// Context-specific error type
transferDetails.error = Option.some(new NoSuchElementException())
// Correct error type with detail extraction
catch: err => new FetchAptosTokenBalanceError({ cause: extractErrorDetails(err) })
// Dedicated function returning TaggedError with extracted details
catch: (error) => new SupabaseError({
operation: "requestRole",
cause: extractErrorDetails(error as Error)
})
```
This approach makes errors more informative for debugging and provides better context for error handling and recovery strategies.
---
## Consistent documentation formatting
Maintain consistent style in documentation files to improve readability and professionalism. Specifically:
1. **Command references**: Use a consistent format when referring to CLI commands. Prefer either:
- The explicit format: "The `terraform fmt` command" (includes both "The" and "command")
- The concise format: "`terraform fmt`:" followed by a description
2. **Punctuation in lists**: Follow consistent punctuation rules in bullet lists:
- Omit periods from incomplete sentences or phrases in bullet lists
- Include periods only for complete sentences
**Example**:
```markdown
# Recommended
- `backend.tf`: Your backend configuration
- `main.tf`: Resource and data source blocks
- `variables.tf`: Variable blocks in alphabetical order
# Instead of
- `backend.tf`: Your backend configuration.
- `main.tf`: Resource and data source blocks.
- `variables.tf`: Variable blocks in alphabetical order.
```
Consistent documentation formatting ensures that users can quickly scan and comprehend content, while maintaining a professional appearance throughout the codebase.
---
## Environment-aware logging configuration
Configure logging behavior dynamically based on the current environment to ensure appropriate log levels and destinations for development, staging, and production contexts. Development environments should use verbose logging (Trace/Debug) for debugging, while production should use minimal logging (Warning/Error) for performance. External logging services should be conditionally initialized to avoid unnecessary overhead in development.
Example implementation:
```typescript
const minimumLogLevel = Logger.minimumLogLevel(
Match.value(ENV()).pipe(
Match.when("DEVELOPMENT", () => LogLevel.Trace),
Match.when("STAGING", () => LogLevel.Debug),
Match.when("PRODUCTION", () => LogLevel.Warning),
Match.exhaustive,
),
)
const init = () => {
if (ENV() === "DEVELOPMENT") {
return // Skip external service initialization
}
// Initialize external logging service for staging/production
externalLogger.init(config)
}
```
This approach ensures optimal logging performance across environments while maintaining debugging capabilities where needed.
---
## Mock external dependencies
Always mock external dependencies in tests to ensure isolation and reliability. Unit tests should not make real network calls, database queries, or interact with external services. Mock implementations must provide the same interface and requirements as their live counterparts to maintain test validity.
When creating mocks, ensure they:
- Return predictable, controlled responses
- Maintain the same interface as the real implementation
- Provide the same requirements/dependencies as the live version
Example:
```typescript
// Mock GraphQL queries to avoid network calls
vi.mock('../../src/graphql/unwrapped-quote-token.js', async (importOriginal) => {
return {
...await importOriginal(),
graphqlQuoteTokenUnwrapQuery: () => Effect.succeed("0x12345")
}
})
// Mock layers for integration testing
const mockLayer = Layer.empty // must provision same requirements as live layer
```
This approach prevents flaky tests, improves test execution speed, and ensures tests focus on the code under test rather than external system behavior.
---
## optimize selection algorithms
When implementing selection algorithms that choose from a pool of candidates, design the algorithm to filter invalid options during the selection process rather than using retry logic after selection. Additionally, always include termination conditions to prevent infinite loops when no valid candidates remain.
The retry approach is inefficient because it may require multiple selection attempts, and each rejected selection wastes computational resources. A filtering approach evaluates constraints once during traversal.
Example of improved selection algorithm:
```go
for {
// Pick handler with closest deadline
handler = heap.Pop(b).(*namedHandler)
b.curDeadline = handler.deadline
handler.deadline += 1 / handler.weight
heap.Push(b, handler)
// Filter during selection instead of retrying
if _, down := b.status[handler.name]; !down {
continue
}
if _, isFenced := b.fenced[handler.name]; isFenced {
continue
}
if handler.passiveHealthChecker != nil && !handler.passiveHealthChecker.AllowRequest() {
continue
}
// Always include termination condition
if allHandlersFenced() {
return nil, errors.New("no available handlers")
}
return handler, nil
}
```
This approach eliminates the need for separate retry methods like `nextServerExcluding` and prevents infinite loops when all candidates are invalid.
---
## Use precise semantic names
Choose names that accurately reflect the purpose and semantics of the entity being named. Avoid overloaded or ambiguous terms that could lead to confusion or misinterpretation.
For example:
- Use specific names like `Result` instead of generic overloaded terms like `Resource` when the context requires precision
- In comments and documentation, ensure terminology is accurate (e.g., "list resource type name" rather than "managed resource type name" when referring to list resources)
- Use the proper established terminology in your domain (e.g., "type constraints" rather than "string" when referring to Terraform types)
- Follow consistent naming conventions by adhering to your team's style guide rather than creating ad-hoc naming rules
When creating a new name or choosing between alternatives, ask: "Will this name clearly communicate the entity's purpose to someone unfamiliar with this code?" If multiple teams or systems interact with your code, ensure your naming aligns with established patterns that all stakeholders understand.
---
## Safe lock patterns
When implementing concurrent operations, ensure locks are acquired and released properly in all execution paths. Always use patterns that guarantee lock release, and document lock acquisition order to prevent deadlocks.
**Key practices:**
1. **Always release locks on all return paths** - Use defer statements for cleanup to guarantee locks are released even on error paths:
```go
func (d *Dir) InstallPackage(ctx context.Context, meta getproviders.PackageMeta) error {
unlock, err := d.Lock(ctx, meta.Provider, meta.Version)
if err != nil {
return err
}
defer unlock() // Ensures lock is released on all return paths
// Implementation...
}
```
2. **Document lock acquisition order** - When acquiring multiple locks, establish and document a consistent order to prevent deadlocks:
```go
// Acquire locks in consistent order: s3 first, then dynamoDB
s3LockId, err := c.s3Lock(info)
if err != nil {
return "", err
}
dynamoLockId, err := c.dynamoDbLock(info)
if err != nil {
return "", err
}
```
3. **Use explicit synchronization patterns** - When coordinating multiple concurrent operations, use clear patterns with channels and wait groups:
```go
lockResults := make(chan lockResult, len(platforms))
go func() {
var wg sync.WaitGroup
for _, platform := range platforms {
wg.Add(1)
go func(platform getproviders.Platform) {
// Process work
lockResults <- result
wg.Done()
}(platform)
}
wg.Wait()
close(lockResults)
}()
for result := range lockResults {
// Process results
}
```
4. **Handle concurrent error cases** - When operating with multiple locks, handle partial failure cases explicitly by cleaning up already acquired resources.
Following these patterns helps prevent race conditions, deadlocks, and resource leaks in concurrent code.
---
## Prevent backing array surprises
When modifying slices in Go, be aware that appending to a slice with available capacity will modify the backing array, potentially affecting other slices that share the same backing storage. This can lead to subtle bugs where one operation unexpectedly affects seemingly unrelated variables.
For example, this code has a potential issue:
```go
encryptCommand := append(cmd, "--encrypt")
decryptCommand := append(cmd, "--decrypt")
```
If `cmd` has spare capacity, both slices will share the same backing array, and the second append will overwrite the last element of the first slice.
To avoid this problem:
1. Use `slices.Clip()` to ensure a fresh backing array before appending:
```go
cmd = slices.Clip(cmd)
encryptCommand := append(cmd, "--encrypt")
decryptCommand := append(cmd, "--decrypt")
```
2. Or explicitly create independent copies:
```go
encryptCommand := make([]string, len(cmd)+1)
copy(encryptCommand, cmd)
encryptCommand[len(cmd)] = "--encrypt"
```
This principle applies to other operations where deterministic behavior is crucial, such as:
- Map iteration (use sorted keys for consistency)
- Merging collections (consider equality semantics)
- Boolean expressions (apply transformations consistently)
By understanding the memory model of your data structures, you'll create more predictable, stable algorithms less prone to subtle side effects.
---
## Explicit versus dynamic configurations
Prefer explicit hardcoded configurations over dynamic ones when the configuration changes infrequently and control is important. While dynamic configurations (like API-driven or external service-based solutions) require less maintenance, explicit configurations provide better control and predictability.
For example, when configuring a CI workflow that needs to run against specific supported versions:
```yaml
strategy:
matrix:
include:
- { branch: main }
- { branch: v1.9 }
- { branch: v1.8 }
- { branch: v1.7 }
```
This approach might require occasional updates, but it provides complete control over which versions are included. To mitigate the maintenance burden, document the update process clearly in contribution guides, including when and how configurations should be updated (e.g., when releasing new versions or deprecating old ones).
---
## Optimize CI/CD workflows
Configure CI/CD workflows to maximize efficiency and improve developer experience. Consider these key optimization practices:
1. **Schedule automated jobs strategically**: Use offset minutes in cron schedules to avoid GitHub Actions high load times.
```yaml
# Schedule during off-peak hours with offset minutes to prevent queuing delays
schedule:
- cron: '42 3 * * SUN' # Using 42 instead of 0 reduces risk of delays
```
2. **Configure path exclusions**: Skip workflow runs for documentation and non-code changes to save CI resources.
```yaml
paths-ignore:
- 'website/**'
- 'docs/**'
```
3. **Progressive code quality enforcement**: Configure linters and code quality tools to only fail on new issues rather than existing ones, preventing contributors from being blocked by legacy problems.
```yaml
- name: golangci-lint
uses: golangci/golangci-lint-action@v3
with:
version: v1.54
only-new-issues: true # Only enforce on changed code
```
These practices help maintain code quality while keeping CI/CD processes efficient and developer-friendly, ensuring the focus remains on new changes rather than fixing preexisting issues all at once.
---
## Reuse existing API utilities
Before implementing custom API utilities, serializers, or type identification methods, check if equivalent functionality already exists in the codebase or standard libraries. This prevents code duplication, ensures consistency across the API surface, and leverages well-tested implementations.
Key practices:
- Search for existing utilities in shared crates before writing custom implementations
- Use trait-provided methods for standard operations like type identification
- Verify API feature compatibility with the target environment before usage
Examples from the codebase:
```rust
// Instead of custom deserializer:
#[serde(default, deserialize_with = "deserialize_opt_u64_from_string")]
// Use existing utility:
// Available in serde_utils crate
// Instead of hardcoded type URLs:
type_url: "/ibc.applications.transfer.v1.MsgTransfer".to_string(),
// Use trait method:
type_url: MsgTransfer::type_url(),
// Avoid incompatible features:
#[sol(rpc, all_derives)] // Don't use 'rpc' in cosmwasm contracts
```
This approach reduces maintenance burden, improves code reliability, and maintains API consistency across the project.
---
## Protect infrastructure secrets
Infrastructure-as-code tools like OpenTofu may store sensitive information in plaintext state files, creating security risks for passwords, API keys, and other secrets. Always implement proper protection measures:
1. Use ephemeral resources or write-only attributes when available to prevent secrets from being persisted
2. Consider state encryption as an additional security layer for all sensitive data
3. For write-only attributes that need updates, implement proper versioning triggers
When implementing secrets management, be aware of the tradeoffs:
- Ephemeral resources don't store secrets at all (reducing risk of leaked credentials)
- State encryption protects all secrets but requires secure key management
Example configuration using write-only attributes:
```hcl
resource "example_resource" "secure_resource" {
name = "my-secure-resource"
# Write-only attribute for sensitive data
password = var.sensitive_password
# Version attribute to trigger updates when password changes
password_version = var.password_version
}
```
Remember that sensitive data can appear in plan files, state files, and logs unless properly managed. Always audit your infrastructure code for potential secret exposure.
---
## organize for readability
Structure code to minimize repetition and improve clarity through appropriate abstraction and import organization. When code contains repetitive patterns, create wrapper functions to eliminate boilerplate. For modules with structured exports (like ADTs), prefer qualified imports over individual named imports to maintain clear namespace organization.
Example of abstracting repetitive patterns:
```typescript
// Instead of repeating tryPromise wrapping:
const amount = yield* Effect.tryPromise({
try: () => client.getBalance(minter, "uxion"),
catch: e => new Error(`Failed to fetch balance: ${String(e)}`)
})
// Create wrapper functions:
const getBalance = (address: string, denom: string) =>
Effect.tryPromise({
try: () => client.getBalance(address, denom),
catch: e => new Error(`Failed to fetch balance: ${String(e)}`)
})
// Then use: yield* getBalance(minter, "uxion")
```
Example of qualified imports for structured modules:
```typescript
// Instead of:
import { Batch, Forward, FungibleAssetOrder, Multiplex } from "../src/ucs03/instruction.js"
// Use qualified import:
import * as Instruction from "../src/ucs03/instruction.js"
```
This approach reduces visual clutter, makes the code's intent clearer, and creates more maintainable examples and implementations.
---
## Minimize API surface
Design APIs with minimal exposed surface by encapsulating implementation details within packages. When designing APIs, expose only what's necessary for consumers while keeping internal details hidden.
For example, instead of exposing complex types that clients must construct:
```go
// Avoid exporting internal types
type DeprecatedOutputDiagnosticExtra struct {
Cause DeprecationCause
wrapped interface{}
}
// Instead, provide wrapper functions that hide implementation details
func DeprecatedOutputDiagnosticOverride(cause DeprecationCause) func() tfdiags.DiagnosticExtraWrapper {
return func() tfdiags.DiagnosticExtraWrapper {
return &DeprecatedOutputDiagnosticExtra{
Cause: cause,
}
}
}
```
When making changes to existing APIs:
1. Consider backward compatibility implications, especially with serialized data structures
2. Be cautious with JSON field tags - changing naming conventions can break compatibility
3. Design consistent parameter patterns for CLI interfaces
4. Handle edge cases in API responses, particularly with pagination and nil values
This approach prevents external code from depending on implementation specifics, makes the codebase more maintainable, and enables future refactoring without breaking compatibility.
---
## Clean documentation links
When writing Rust documentation links, separate the display name from the full path to improve readability of generated docs. Use the short type name as the display text and provide the full path as the link target. This makes the documentation less noisy and easier to read.
**Pattern to follow:**
```rust
// Instead of this (noisy):
/// The returned [`Op`] ***MUST*** resolve to an [`crate::data::OrderedHeaders`] data.
// Use this (clean):
/// The returned [`Op`] ***MUST*** resolve to an [`OrderedHeaders`][crate::data::OrderedHeaders] data.
```
This approach keeps the inline text readable while still providing the full path information needed for proper linking in the generated documentation.
---
## Prefer modern authentication
Always use modern identity-based authentication methods instead of static credentials when accessing external systems. This reduces security risks associated with credential management, rotation, and potential exposure.
For Azure resources, prefer authentication methods in this order:
1. OpenID Connect / Workload identity federation (recommended)
2. Managed Identities
3. Azure Active Directory
4. Access Keys/SAS Tokens (avoid for new workloads)
```hcl
# Example - Using OpenID Connect for Azure authentication
terraform {
backend "azurerm" {
use_oidc = true # Enable OIDC authentication
use_azuread_auth = true # Use Azure AD authentication
tenant_id = "00000000-0000-0000-0000-000000000000" # Can be set via ARM_TENANT_ID
client_id = "00000000-0000-0000-0000-000000000000" # Can be set via ARM_CLIENT_ID
storage_account_name = "abcd1234"
container_name = "tfstate"
key = "prod.terraform.tfstate"
}
}
```
When executing commands or generating credentials:
1. Avoid using Terraform variables directly in command strings to prevent shell injection vulnerabilities
2. Use the `environment` parameter for variable substitution
3. Configure credential generation parameters to ensure both security and compatibility:
```hcl
# Generate a secure password with compatible special characters
ephemeral "random_password" "db_password" {
length = 16
special = true
override_special = "!#$%&*()-_=+[]{}<>:?"
}
```
---
## Proper span lifecycle
Always ensure trace spans are properly closed in all code execution paths to prevent trace leaks that can distort observability data. This is particularly critical when creating spans within loops, conditional blocks, or functions with multiple exit points.
When adding tracing to your code, follow these practices:
1. Use `defer span.End()` immediately after span creation when possible:
```go
ctx, span := tracing.Tracer().Start(ctx, "Operation")
defer span.End()
```
2. For spans in loops, either:
- Extract loop body to a separate function where you can use defer
- Explicitly end spans before continues/breaks/returns
- Consider wrapping the loop body in a function literal with defer
3. Verify spans are ended in all execution paths, especially when error conditions cause early returns.
4. Be particularly careful with spans passed to callback functions to ensure they're properly closed.
Failure to close spans will cause them to remain open until timeout, potentially creating misleading timing data and resource leaks in your tracing backend.
---
## Include descriptive documentation
Provide complete, clear descriptions for all configuration elements in documentation. Every output, variable, argument, and configuration option should include descriptive text explaining its purpose, requirements, and usage from the consumer's perspective.
When documenting outputs, always include a description field:
```hcl
output "website_url" {
value = "https://${module.web_server.instance_ip_addr}"
description = "The website URL, starting with https://"
}
output "db_password" {
value = aws_db_instance.db.password
sensitive = true
description = "The database password."
}
```
For configuration instructions, be explicit rather than implicit. When explaining how to use a feature, provide clear steps and concrete examples showing the correct implementation. Replace vague terms with specific descriptions that help readers understand exactly what actions to take.
Documentation should follow a consistent pattern with proper introduction sentences for each section, and use present tense rather than future tense. Address users directly with clear, actionable language that guides them through proper implementation.
---
## Ensure test isolation
Tests should be completely isolated from each other and clean up after themselves to prevent interference.
1. **Use testing utilities properly**: Leverage the standard library's testing helpers correctly.
```go
// GOOD: Let t.TempDir() handle directory creation and cleanup
td := t.TempDir()
// BAD: Don't call os.MkdirAll() after t.TempDir()
td := t.TempDir()
os.MkdirAll(td, 0755) // Unnecessary - directory already exists with proper permissions
```
2. **Clean up global state**: When tests modify global variables or settings, always restore the original values.
```go
// GOOD: Save and restore global state
p := tfversion.Prerelease
v := tfversion.Version
defer func() {
tfversion.Prerelease = p
tfversion.Version = v
}()
```
3. **Make tests deterministic**: Avoid non-deterministic behavior like unsorted maps to prevent flaky tests.
```go
// GOOD: Sort keys or values before assertion when using maps
// Instead of directly asserting on map values which may be in random order
sortedKeys := make([]string, 0, len(someMap))
for k := range someMap {
sortedKeys = append(sortedKeys, k)
}
sort.Strings(sortedKeys)
```
4. **Validate resource cleanup**: Tests should verify that all resources are properly cleaned up after running.
```go
// Verify no resources remain after test
if provider.ResourceCount() > 0 {
t.Fatalf("should have deleted all resources on completion but left %v",
provider.ResourceString())
}
```
Properly isolated tests lead to more reliable test suites, easier debugging, and prevent issues where test results depend on execution order.
---
## Handle errors completely
Always handle errors comprehensively by checking return values, implementing proper error propagation, and ensuring resources are cleaned up. Errors that are ignored or improperly handled can lead to resource leaks, unexpected behavior, or application crashes.
Follow these principles:
1. **Check all error returns**: Never discard errors with blank identifiers (`_`) unless you have explicitly determined the error can be safely ignored.
```go
// Bad
cfg.BandwidthLimit, _ = NewBandwidthQuantity(pMsg.BandwidthLimit) // Ignores error, creating empty bandwidth limit
// Good
cfg.BandwidthLimit, err = NewBandwidthQuantity(pMsg.BandwidthLimit)
if err != nil {
// Handle appropriately: set default, log warning, or return error
xl.Warnf("Invalid bandwidth limit %q: %v", pMsg.BandwidthLimit, err)
}
```
2. **Add error returns to functions that can fail**: Ensure callers can detect and handle failures.
```go
// Bad
func (c *Controller) RegisterClientRoute(ctx context.Context, name string, routes []net.IPNet, conn io.ReadWriteCloser) {
// No way to signal failure to caller
}
// Good
func (c *Controller) RegisterClientRoute(ctx context.Context, name string, routes []net.IPNet, conn io.ReadWriteCloser) error {
// Implementation
return err // Return any failure
}
```
3. **Close resources after errors**: Always clean up resources when errors occur.
```go
// Bad
if err := svr.RegisterWorkConn(conn, m); err != nil {
// Error logged but connection left open
}
// Good
if err := svr.RegisterWorkConn(conn, m); err != nil {
conn.Close() // Clean up resources
}
```
4. **Protect against panic conditions**: Especially in callbacks or user-provided code.
```go
// Good
if onClose != nil {
func() {
defer func() {
if r := recover(); r != nil {
xl.Warnf("onClose callback panicked: %v", r)
}
}()
onClose()
}()
}
```
Complete error handling is essential for building reliable and maintainable software.
---
## Network information extraction
When extracting network information from connections (such as remote addresses, proxy IPs, or forwarded headers), implement robust extraction methods that don't depend on specific connection wrapper ordering or implementation details. Use iterative unwrapping patterns and ensure all relevant network information is properly preserved and forwarded.
For proxy protocol handling, use a generic unwrapping approach:
```go
getProxyIP := func(c net.Conn) string {
for {
switch conn := c.(type) {
case *tcprouter.Conn:
c = conn.WriteCloser
case *trackedConnection:
c = conn.WriteCloser
case *writeCloserWrapper:
c = conn.writeCloser
case *net.TCPConn:
return c.RemoteAddr().String()
default:
return conn.RemoteAddr().String()
}
}
}
```
When forwarding HTTP requests, preserve all relevant network headers and use context values to pass network information between middleware layers:
```go
// Add back removed Forwarded Headers
req.Out.Header["Forwarded"] = req.In.Header["Forwarded"]
req.Out.Header["X-Forwarded-For"] = req.In.Header["X-Forwarded-For"]
req.Out.Header["X-Forwarded-Host"] = req.In.Header["X-Forwarded-Host"]
req.Out.Header["X-Forwarded-Proto"] = req.In.Header["X-Forwarded-Proto"]
// Use context values for network information
if xForwardedForAddr, ok := req.In.Context().Value(forwardedheaders.XForwardedForAddr).(string); ok {
remoteAddr = xForwardedForAddr
}
```
This approach ensures network information remains accurate across different connection types and middleware layers, which is crucial for proper load balancing, health checking, and security features.
---
## Check context cancellation
Always implement proper cancellation mechanisms in concurrent code to prevent goroutine leaks and enable timely shutdown. Two key practices:
1. Add context checks at the beginning of loops in goroutines:
```go
for {
// Honor caller cancellation to avoid goroutine leaks
select {
case <-ctx.Done():
logger.Debug("operation cancelled")
return
default:
}
// Continue with operation that might block
data, err := ReadMessage(conn)
// ...
}
```
2. Add context parameters to functions that may block for extended periods:
```go
// Before
func (impl *transporterImpl) Send(m msg.Message) error
// After
func (impl *transporterImpl) Send(ctx context.Context, m msg.Message) error
```
This pattern allows callers to cancel operations when a user exits manually or when operations exceed timeouts, preventing resource leaks and ensuring responsive application behavior during shutdown.
---
## avoid hardcoded configuration
Avoid hardcoding configuration values directly in code. Instead, make parameters configurable through CLI arguments, config files, environment variables, or runtime queries, while providing sensible defaults.
Hardcoded values reduce flexibility, make testing difficult, and require code changes for different environments. Configuration should be externalized to support different deployment contexts and operational requirements.
Examples of good practices:
- Make CLI parameters configurable: `faucet --batch-size 6000` instead of `let batch_size = 6000;`
- Fetch values from runtime sources: `voyager_client.client_info()` instead of hardcoded client types
- Use contextual defaults: `DEFAULT_DECIMALS = 6` for cosmos tokens, but allow override when needed
- Implement proper serde defaults with custom functions: `#[serde(default = "default_delay_blocks")]`
This approach improves maintainability, testability, and deployment flexibility while ensuring the system can adapt to different operational requirements without code modifications.
---
## Document with examples
Always include clear, contextual examples when documenting APIs, interfaces, or command-line functionality. Examples significantly improve understanding and reduce ambiguity, particularly for new or complex features. Maintain consistent terminology throughout documentation, avoiding unexplained jargon or abbreviations.
For changelog entries:
```diff
- * Added"force-unlock" support for the HTTP backend: ([#2381](https://github.com/opentofu/opentofu/pull/2381))
+ * "force-unlock" option is now supported by the HTTP backend. ([#2381](https://github.com/opentofu/opentofu/pull/2381))
- * Provider defined functions are now available. They may be referenced via `provider::alias::funcname(args)`.
+ * Provider defined functions are now available. They may be referenced via `provider::provider_alias::funcname(args)`. Example: `aws::default::vpc_id(region)`.
```
For API/protocol documentation:
1. Provide examples for common use cases
2. Show exact request/response formats
3. Explain each parameter's purpose and constraints
4. Include links to related concepts for additional context
5. Use consistent terminology when referring to similar concepts (e.g., clarify differences between "plugin" vs "provider")
---
## Provider instance management
Ensure proper configuration of provider instances when using environment-specific settings. When using `for_each` with providers, carefully manage the lifecycle of provider instances to avoid warnings or errors during resource operations.
Key considerations:
1. Provider instances created with `for_each` must remain available for the entire lifecycle of any resources using them, including during destruction
2. When resources also use `for_each`, ensure their instance keys don't exactly match the provider's to allow proper resource removal
3. Use selective filtering when creating resource instances to maintain needed provider instances
```hcl
# Good practice: Filter resources but maintain provider instances
variable "aws_regions" {
type = map(object({
vpc_cidr_block = string
}))
}
provider "aws" {
alias = "by_region"
for_each = var.aws_regions
region = each.key
}
resource "aws_vpc" "private" {
# Filter var.aws_regions to include only non-null elements
# allowing provider instances to remain while removing resources
for_each = {
for region, config in var.aws_regions : region => config
if config != null
}
provider = aws.by_region[each.key]
cidr_block = each.value.vpc_cidr_block
}
```
This pattern allows you to "disable" resources in specific regions by setting their config to null while maintaining the provider instance needed for cleanup operations. Without this approach, OpenTofu would generate warnings when trying to destroy resources whose provider instances have been removed.
---
## dependency version constraints
Ensure consistent and appropriate dependency version constraints across all package.json files. Use flexible version ranges for peer dependencies to avoid forcing unnecessary upgrades, maintain minimum supported versions that align with project requirements, and keep template dependencies up-to-date for consistency.
Key practices:
- Use caret (^) syntax for regular dependencies: `"wrangler": "^3.101.0"`
- Use hyphenated ranges for peer dependencies when supporting multiple versions: `"vitest": "1.3.x - 1.5.x"`
- Specify minimum supported versions that match actual requirements, not outdated versions
- Classify dependencies correctly (dependencies vs devDependencies vs peerDependencies)
- Keep template package.json files updated to latest supported versions for consistency
- Consider using workspace references (`workspace:*`) for internal packages to maintain version alignment
Example of proper version constraints:
```json
{
"dependencies": {
"wrangler": "^3.101.0"
},
"peerDependencies": {
"vitest": "1.3.x - 1.5.x"
},
"devDependencies": {
"@cloudflare/workers-types": "^4.20241230.0"
}
}
```
This prevents compatibility issues, reduces maintenance burden, and ensures users can adopt newer versions without being blocked by overly restrictive constraints.
---
## Names preserve cognitive context
Choose variable, function, and type names that preserve cognitive context by clearly indicating their purpose and relationship to surrounding code. Names should help readers understand the code's intent without having to deeply analyze implementation details.
Examples:
```go
// Poor naming - loses context
ctx := someFunc(refs)
psuedo := value.Decode()
targetedNodes := getExcludedItems()
// Good naming - preserves context
hclCtxFunc := someFunc(refs) // Indicates it returns HCL context
decodedExpectedVar := value.Decode() // Shows relationship to expected value
excludedNodes := getExcludedItems() // Matches exclusion logic
```
This practice reduces cognitive load when reading code by:
1. Making the purpose of variables immediately clear
2. Maintaining consistency with surrounding context
3. Avoiding misleading names that could cause confusion
4. Helping readers predict behavior without checking implementation
When choosing names, consider:
- What does this value represent in the current context?
- How will it be used by surrounding code?
- What assumptions might readers make based on the name?
---
## Configuration validation consistency
Ensure configuration fields use consistent validation patterns, appropriate data types, and proper bounds checking. This includes using correct regex patterns for duration fields, consistent type usage across similar fields, and implementing cross-field validation where relationships exist.
Key practices:
1. **Duration validation patterns**: Use the simplified regex pattern `^[0-9]+(\\.[0-9]+)?(ns|us|µs|ms|s|m|h)?$` instead of the complex `^([0-9]+(\\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$` for duration fields
2. **Type consistency**: Use `ptypes.Duration` consistently for timeout/duration configurations rather than mixing with `time.Duration`
3. **Validation bounds**: Add appropriate kubebuilder validation constraints like `+kubebuilder:validation:Minimum=0` and maximum bounds where applicable
4. **Cross-field validation**: Implement validation checks for related fields (e.g., ensuring ResponseHeaderTimeout ≤ Timeout) in the Init() method
Example of proper duration field validation:
```go
// DialTimeout is the amount of time to wait until a connection can be established.
// +kubebuilder:validation:Pattern="^[0-9]+(\\.[0-9]+)?(ns|us|µs|ms|s|m|h)?$"
// +kubebuilder:validation:XIntOrString
DialTimeout *intstr.IntOrString `json:"dialTimeout,omitempty"`
```
This ensures configuration fields are validated consistently, preventing runtime errors and improving user experience with clear validation messages.
---
## Document intent and limitations
Clearly document the intended purpose, scope limitations, and design decisions in your code. For all exported types, functions, and variables, provide comprehensive comments explaining their purpose, usage patterns, expected behavior, and any deliberate limitations.
When documenting code:
- Explain what the code does and doesn't do
- Specify when and how it should be used
- Document any assumptions or edge cases not handled
- Include links to external specifications when referenced
- Explain platform-specific behaviors and why they exist
Always update documentation when modifying code behavior, and ensure comments accurately reflect current usage patterns. This helps prevent misunderstandings and improves maintainability.
Example:
```go
// ociImageManifestSizeLimit is the maximum size of artifact manifest (aka "image
// manifest") we'll accept. This 4MiB value matches the recommended limit for
// repositories to accept on push from the OCI Distribution v1.1 spec:
// https://github.com/opencontainers/distribution-spec/blob/v1.1.0/spec.md#pushing-manifests
const ociImageManifestSizeLimitMiB = 4
// providerIterationIdentical performs a limited comparison of HCL expressions
// to determine if they are syntactically identical. This function is intentionally
// limited to simple references and function calls with simple reference arguments.
// All other expression types will return false by default, as this function is not
// expected to handle every possible HCL expression type.
func providerIterationIdentical(a, b hcl.Expression) bool {
// implementation...
}
// EvalContextWithParent creates an evaluation context derived from the given parent
// context. This allows the new context to inherit values from its parent while
// adding or overriding specific values. This is particularly useful for nested
// evaluations like module calls where child contexts need access to parent variables
// but also define their own local values.
func (s *Scope) EvalContextWithParent(...) {...}
// On Windows, we use 0777 permissions instead of 0755 because Windows
// doesn't have the same permission model and these bits get ignored
if runtime.GOOS == "windows" {
// Windows-specific behavior
}
```
---
## Use structured logging fields
Prefer structured logging fields over string formatting in tracing logs to improve searchability, parsing, and consistency. Use field syntax like `field = %value` or `%field` instead of embedding values directly in log messages. Keep log messages single-line, lowercase, and include relevant context as separate fields.
**Examples:**
Instead of:
```rust
tracing::info!("SendPacket event recorded for sequence {}. key: {}", sequence, key);
tracing::info!("ETH Token balance: {}. Sending amount: {}", balance, amount);
debug!("abi build log: \n-----------\n{}\n-----------", log);
```
Use:
```rust
tracing::info!(sequence = %sequence, key = %key, "sendpacket event recorded");
tracing::info!(balance = %balance, amount = %amount, "eth token balance check");
debug!(stdout = %output.stdout, stderr = %output.stderr, "abi build log");
```
This approach makes logs more structured, easier to query, and maintains consistency across the codebase. Always include relevant contextual information like chain IDs, block numbers, addresses, and amounts as separate fields rather than formatting them into the message string.
---
## Structure tests thoroughly
Create well-structured tests with thorough coverage of both expected success and error conditions. Name test cases descriptively to clearly identify their purpose, and separate test logic from test data when using table-driven tests.
**Key practices:**
1. **Use descriptive test case names** to clearly indicate what's being tested:
```go
testCases := map[string]struct {
name: "should set proxy using http_proxy environment variable",
rawUrl: "http://example.com",
httpProxy: "http://foo.bar:3128",
expectedProxyURL: "http://foo.bar:3128",
}
```
Instead of using unnamed array elements.
2. **Test both success and failure paths** explicitly:
```go
// Ensuring error checks are performed
if tc.wantErr != "" && len(diags) == 0 {
t.Fatalf("expected error but got none")
}
```
3. **Use proper test resource management** to ensure test isolation:
```go
// Use t.TempDir() instead of manual temp file management
dir := t.TempDir()
// Use t.Helper() in test helpers
t.Helper()
// Use t.Setenv for environment variables
t.Setenv("HTTP_PROXY", tc.httpProxy)
```
4. **Verify both positive and negative expectations** to catch regressions:
```go
// Check for presence of expected value
if !strings.Contains(output, "ami = \"ValueFROMmain/tfvars\"") {
t.Errorf("expected output to include value from main tfvars")
}
// Check that unwanted value is absent
if strings.Contains(output, "ValueFROMtests/tfvars") {
t.Errorf("output should not include value from tests tfvars")
}
```
Well-structured tests improve maintainability, make test failures more informative, and provide better protection against regressions.
---
## validate input sanitization
Always maintain input sanitization and validation mechanisms to prevent security vulnerabilities. Disabling built-in security features like path sanitization can expose applications to path traversal attacks and routing manipulation.
When working with path sanitization options, avoid disabling security features unless absolutely necessary. If legacy client compatibility requires disabling sanitization, ensure all incoming requests are properly URL-encoded at the application boundary instead.
Example of secure configuration:
```yaml
# Secure - keep sanitization enabled (default)
entryPoints:
web:
address: ":80"
http:
sanitizePath: true # Default, recommended
# Insecure - avoid this configuration
entryPoints:
web:
address: ":80"
http:
sanitizePath: false # Creates security vulnerabilities
```
Setting `sanitizePath` to `false` is not safe as it can lead to path interpretation differences between routing rules and backend servers. This can result in unsafe routing when paths contain characters like `/` that aren't properly URL-encoded. Always ensure requests are properly URL-encoded rather than disabling security mechanisms.
---
## Nil-Safe Input Normalization
When handling optional/null values, normalize and guard them at the boundary so downstream code never has to guess.
Apply these rules:
1) Keep safe fallbacks for optional config fields (don’t delete “default” logic unless the field is strictly required).
2) Normalize values to the expected type immediately:
- If a header can be duplicated, `request.get_headers()[name]` may be a table; convert to the first string.
- If an upstream value is sometimes nil/empty, treat empty as missing consistently.
3) Ensure string operations and serialization never receive `nil` (use nil checks/early returns, or set deterministic defaults).
4) Avoid producing arrays/lists with `nil` elements in the middle; either use deterministic defaults or filter out nils before iterating/serializing.
5) Add regression tests for shape differences (e.g., duplicate headers, missing route fields, nil-able config).
Example (normalize header values + nil-safe decode):
```lua
local function normalize_header(v)
if type(v) == "table" then
return v[1]
end
return v
end
local function get_first_valid_header(request_headers, name)
return normalize_header(request_headers[name])
end
-- usage
local request_headers = request.get_headers()
local token_header = get_first_valid_header(request_headers, "authorization")
if type(token_header) ~= "string" or token_header == "" then
return nil
end
```
Example (deterministic metric/tag element):
```lua
local route_name = message.route and message.route.name or ""
route_name = (route_name:gsub("%.", "_"))
-- always pass a string (or explicitly omit the element before building the array)
```
---
## Document Split Contracts
When implementing algorithmic transformations that clients depend on (especially split/partition functions and any logic that rebuilds/serializes structured strings), treat semantics as a stable API: explicitly define and document the contract (edge cases, limits, nil/empty handling, delimiter rules), and guarantee deterministic output by not relying on non-deterministic table iteration.
Practical rules:
- Splitters/partitioners: write the expected behavior for `value=nil`, `value==""`, `pattern==nil`, `pattern==""`, and how `n`/max is honored (never more than `n`, what the last element contains, etc.).
- Plain vs pattern: document whether the delimiter is treated as a literal string or a pattern, and how empty delimiters behave.
- Deterministic serialization: if you rebuild a query/string from a map, iterate keys in a deterministic order (e.g., sorted keys) and preserve repeated-parameter semantics (don’t silently collapse multiple values).
- Add targeted tests for the trickiest semantic boundaries (limit=0/1, empty delimiter, delimiter longer than input, boundary windows, etc.).
Example (deterministic query rebuild while avoiding `pairs` ordering issues):
```lua
local function rebuild_query_in_order(kv)
local keys = {}
for k in pairs(kv) do
keys[#keys+1] = k
end
table.sort(keys)
local parts = {}
for i = 1, #keys do
local k = keys[i]
local v = kv[k]
-- If kv[k] can have repeated values, encode accordingly; otherwise keep single.
parts[#parts+1] = k .. "=" .. v
end
return table.concat(parts, "&")
end
```
---
## Semantic Naming Rules
Adopt a naming standard where identifiers encode meaning, don’t clash with framework semantics, and don’t obscure behavior.
Guidelines:
- Avoid reserved/special filenames and namespace collisions. If a module filename has framework semantics (e.g., `api.lua` in plugin contexts), don’t reuse it for unrelated code—rename or place code where it can’t be mistaken.
- Prefer semantic names over comments for basic intent. If a comment explains what a function does, the name likely should include that intent.
- Example:
- Bad: `local function set_headers(conf, claims)` with “set header keys from claims” comment.
- Better: `local function set_headers_from_claims(conf, claims)` (remove the now-redundant comment).
- Make return types match the “has/is” naming contract.
- Example: `has_capture(...)` should return `true/false` consistently (e.g., `return false`), not `nil`.
- Don’t shadow/repurpose function parameters when their meaning or type changes; this breaks reader expectations.
- Example: avoid reassigning `value` from `string` to `table` inside the same function.
- Avoid overly-generic identifiers for critical context (e.g., `saved` / `get_saved`). Use names that describe what’s actually being retrieved (request context, saved request headers, etc.), or pass the context explicitly to the handler.
- Use clear boolean helper naming for roles/flags.
- Example: prefer `is_control_plane(kong.configuration.role)` over raw string comparisons scattered through code.
Impact: improves readability, reduces accidental coupling/namespace bugs, and makes behavior self-evident from names alone.
---
## Preserve sensitive data marks
Carefully handle data marked as sensitive throughout the codebase to maintain security properties. Ensure that sensitive marks are only removed when necessary, and be aware that operations on marked data (such as reordering from nested to top level) could have security implications.
When modifying code that processes sensitive data:
1. Only remove sensitive marks when explicitly required
2. Validate that transformations maintain appropriate security properties
3. Consider interactions with other marking systems in your codebase
Example:
```go
// Good: Only remove marks when necessary (check if they exist first)
if n.Addr.Module.IsRoot() && marks.Contains(val, marks.Sensitive) {
// Handle sensitive data appropriately
}
// Avoid: Unconditional operations on sensitive data that might not exist
if n.Addr.Module.IsRoot() {
// Potentially unnecessary operations on sensitive marks
}
```
---
## Use environment variables
When working with configurations that require sensitive data (credentials, tokens, passwords), always use environment variables instead of hardcoding values directly in configuration files. This prevents sensitive information from being stored in version control systems, state files, or plan outputs.
For backend configurations:
```hcl
terraform {
backend "azurerm" {
storage_account_name = "abcd1234"
container_name = "tfstate"
key = "prod.terraform.tfstate"
# BAD: client_secret = "highly-sensitive-value"
# GOOD: Use environment variable ARM_CLIENT_SECRET instead
}
}
```
For write-only arguments and ephemeral resources, the same principle applies:
```hcl
resource "aws_db_instance" "example" {
instance_class = "db.t3.micro"
allocated_storage = "5"
engine = "postgres"
username = "example"
skip_final_snapshot = true
# Instead of hardcoding: password_wo = "secret-password"
# Use an ephemeral resource with environment variables
password_wo = ephemeral.random_password.db_password.result
password_wo_version = 1
}
```
This approach improves security by:
1. Keeping sensitive data out of version control repositories
2. Preventing exposure in Terraform's state and plan files
3. Allowing for different credentials in different environments
4. Enabling safer CI/CD pipelines with environment-specific secrets
Most providers support environment variable alternatives for sensitive configuration values - consult the provider documentation for the specific environment variable names available.
---
## Resource cleanup on errors
Always ensure proper resource cleanup in error paths to prevent leaks. Use defer functions with explicit error checking for closing operations, and log any close errors that occur during cleanup.
When working with resources like file handles, network connections, or API responses, make sure to:
1. Use defer statements to guarantee cleanup even when errors occur
2. Check for and log errors that happen during the cleanup process itself
3. Use context-aware cancellation when appropriate
For example, instead of:
```go
getOutput, err := c.s3Client.GetObject(ctx, getInput)
if err != nil {
return fmt.Errorf("unable to retrieve file: %w", err)
}
defer getOutput.Body.Close()
```
Prefer:
```go
getOutput, err := c.s3Client.GetObject(ctx, getInput)
if err != nil {
return fmt.Errorf("unable to retrieve file: %w", err)
}
defer func() {
if cerr := getOutput.Body.Close(); cerr != nil {
log.Warn(fmt.Sprintf("failed to close S3 object body: %v", cerr))
}
}()
```
For processes that might need cancellation, consider using context:
```go
ctx, cancel := context.WithCancel(context.Background())
defer cancel() // Ensure cancellation happens even on error paths
// Create command with context for lifecycle management
cmd := exec.CommandContext(ctx, cmdParts[0], cmdParts[1:]...)
```
This ensures all resources are properly cleaned up, error conditions during cleanup are logged, and long-running operations can be gracefully terminated.
---
## descriptive contextual logging
Log messages should be descriptive, contextual, and provide actionable information. Include relevant context such as service names, configuration details, or affected components. When logging errors or warnings, explain what happened, why it matters, and what action is being taken or should be taken.
Examples of improvements:
- Instead of: `logger.Error().Msg("Health check interval smaller than zero")`
- Use: `logger.Error().Msg("Health check interval smaller than zero, default value will be used instead.")`
- Add contextual loggers that include service-specific information rather than generic loggers
- Include warning logs when important features or configurations are used that users should be aware of
This approach helps with debugging, monitoring, and provides users with clear understanding of system behavior and any corrective actions being taken.
---
## Contextualize security findings
When reporting security vulnerabilities, include sufficient context beyond just vulnerability IDs or codes. Always preserve standard identifiers (like GO-YYYY-NNNN) in titles while adding descriptive information about affected components, versions, and modules. This makes vulnerabilities easier to prioritize, track, and remediate.
For example:
```
// Instead of just:
Issue: "GO-2024-1234 reported"
// Prefer:
Issue: "GO-2024-1234 reported - affects authentication module in v1.7-v1.9"
Description:
"This vulnerability is affecting the following versions: v1.7 v1.8 v1.9
*Vulnerability info:* https://pkg.go.dev/vuln/GO-2024-1234
*Pipeline run:* https://github.com/org/repo/actions/runs/12345
*Affected component:* authentication/oauth2"
```
Properly labeled and contextualized vulnerability reports allow teams to quickly understand the severity and impact without opening multiple tabs or digging through comments. Consider adding clear documentation on how to handle these vulnerabilities and restricting sensitive security discussions to appropriate team members when necessary.
---
## Reduce code nesting
Minimize nesting levels and complexity in your code to improve readability and maintainability. Use early returns instead of deeply nested conditions, and restructure switch statements to reduce complexity.
Here are practical approaches to reduce nesting:
1. **Use early returns for error conditions or special cases:**
```go
// Instead of this:
if condition {
// Long code block here
if anotherCondition {
// More code here
}
}
// Do this:
if !condition {
return // or handle the error case
}
// Long code block here
if !anotherCondition {
return // or handle the error case
}
// More code here
```
2. **Simplify switch statements:**
```go
// Instead of nested switch-case:
switch {
case !forEachVal.IsKnown():
if !allowUnknown {
var detailMsg string
switch {
case ty.IsSetType():
detailMsg = errInvalidUnknownDetailSet
default:
detailMsg = errInvalidUnknownDetailMap
}
// Handle error...
}
// Use simpler pattern with clear, separated checks:
if !forEachVal.IsKnown() && !allowUnknown {
var detailMsg string
if ty.IsSetType() {
detailMsg = errInvalidUnknownDetailSet
} else {
detailMsg = errInvalidUnknownDetailMap
}
// Handle error...
return // early return after error handling
}
```
3. **Extract complex logic into helper functions** with clear names to reduce the depth of your primary functions.
4. **For conditional logic, use clear variable names** instead of nested expressions to improve readability:
```go
// Instead of:
if ext := tfFileExt(p); ext != "" {
parallelTofuExt := strings.ReplaceAll(ext, ".tf", ".tofu")
pathWithoutExt, _ := strings.CutSuffix(p, ext)
parallelTofuPath := pathWithoutExt + parallelTofuExt
// Nested logic here...
} else {
relevantPaths = append(relevantPaths, p)
}
// Do this:
ext := tfFileExt(p)
if ext == "" {
relevantPaths = append(relevantPaths, p)
continue
}
parallelTofuExt := strings.ReplaceAll(ext, ".tf", ".tofu")
pathWithoutExt, _ := strings.CutSuffix(p, ext)
parallelTofuPath := pathWithoutExt + parallelTofuExt
// Logic continues with less nesting...
```
These changes make code easier to follow, test, and maintain.
---
## Design repeatable CI workflows
{% raw %}
CI workflows should be idempotent and handle cleanup automatically to avoid manual intervention and ensure reliable execution. When designing workflows that create resources, branches, or temporary artifacts, always include cleanup steps that can run safely multiple times.
Key practices:
- Check for and clean up existing resources before creating new ones
- Use force operations or deletion commands that don't fail if the target doesn't exist
- Design workflows to be safely re-runnable without conflicts
Example from workflow design:
```yaml
- name: "Create Draft PR"
run: |
# Clean up existing branch if it exists
git branch -D run-ci-on-behalf-of-${{ inputs.pr-number }} 2>/dev/null || true
git checkout -b run-ci-on-behalf-of-${{ inputs.pr-number }}
```
This prevents scenarios where workflows fail on subsequent runs due to existing branches, resources, or conflicts, eliminating the need for manual cleanup and ensuring consistent behavior across executions.
{% endraw %}
---
## Configuration override precedence
When designing systems with configurations that can be specified at multiple levels (global vs local, environment vs file, default vs override), establish and document a clear precedence model. Always prioritize more specific configurations over general ones.
For example, with test configurations:
```go
// Apply local run block settings over global test block settings
if runBlock.SkipCleanup != nil {
// Local setting takes precedence when explicitly set
useSkipCleanup = *runBlock.SkipCleanup
} else if testBlock.SkipCleanup != nil {
// Fall back to global setting when local isn't specified
useSkipCleanup = *testBlock.SkipCleanup
}
```
Use pointers for optional configuration values to distinguish between unset values (nil) and explicit zero values. This pattern enables clear differentiation between "not specified" and "explicitly set to default value", allowing proper inheritance from parent configurations.
When designing hierarchical configurations, document the precedence rules to help users understand which settings will take effect when specified at multiple levels. This is especially important for complex systems like backends, providers, and test frameworks.
---
## Clarify test documentation
Ensure all testing-related documentation is clear, accurate, and user-focused. Use precise terminology when describing test components, fully explain configuration attributes with their effects, and provide complete examples that demonstrate proper usage.
When documenting test blocks and attributes:
- Use exact parameter names and describe their full behavior
- Explain default values and all possible options
- Reference related sections for context
For example:
```hcl
test "configuration_example" {
# Document that this enables parallel execution of all run blocks
# within this test unless specifically overridden
parallel = true
}
run "validate_resource_properties" {
# Document that this block contains validation logic
# with clear explanation of the condition and error message
condition = local.resource_name != ""
error_message = "Resource name cannot be empty"
}
```
Well-documented tests serve as both validation tools and self-explanatory examples, making your codebase more maintainable and helping new team members understand testing requirements quickly.
---
## Technical precision matters
When documenting algorithms, data structures, and computational processes, use precise and objective language rather than subjective assessments. Replace phrases like "better approach" with specific technical comparisons that highlight concrete differences, such as:
```
// Instead of this:
// This sorting algorithm is better than bubble sort.
// Write this:
// This merge sort implementation has O(n log n) time complexity compared
// to bubble sort's O(n²), making it more efficient for large datasets.
```
When providing examples of operations or syntax, maintain consistent formatting and avoid abbreviations for clarity. This precision enables team members to make informed decisions about algorithmic trade-offs and performance characteristics without ambiguity.
---
## Verify Downloaded Artifacts
Any CI/install workflow that downloads a binary or other external artifact must verify its integrity before use.
Apply this standard:
- Prefer immutable references (commit SHA/immutable artifact IDs) when your tooling supports it.
- Otherwise, download deterministically (e.g., by version/tag) and verify a pre-published cryptographic hash (sha256) at install time.
- Fail closed: if the computed hash doesn’t match the expected hash, abort the install.
Example pattern (shell):
```sh
EXPECTED_SHA256="46847521abf3745686d89460809b84e6a9f10e33" # trusted/pre-published
URL="https://example.com/tool/releases/download/vX.Y.Z/tool-linux-x64"
curl -fsSL "$URL" -o tool
ACTUAL_SHA256=$(sha256sum tool | awk '{print $1}')
if [ "$ACTUAL_SHA256" != "$EXPECTED_SHA256" ]; then
echo "sha256 mismatch: expected $EXPECTED_SHA256 got $ACTUAL_SHA256" >&2
exit 1
fi
# proceed to use tool only after verification
```
---
## Sanitize command inputs
When constructing commands that will be executed, always sanitize input values to prevent command injection vulnerabilities. Never directly substitute user-supplied or externally-sourced data into command strings without proper validation and sanitization.
Unsafe pattern (vulnerable to injection):
```go
command := strings.Replace(proxyCommand, "%h", host, -1)
// Executing this command could be dangerous if 'host' contains malicious characters
```
Safer alternatives:
1. Validate inputs against strict patterns before use
```go
if !validHostnamePattern.MatchString(host) {
return nil, fmt.Errorf("Invalid hostname format: %s", host)
}
```
2. Use dedicated libraries/APIs that handle command arguments safely
```go
cmd := exec.Command(proxyCommand, host, port)
// Arguments are properly escaped by the exec package
```
3. If string interpolation is necessary, consider using a dedicated escaping function
```go
escapedHost := shellEscape(host)
command := strings.Replace(proxyCommand, "%h", escapedHost, -1)
```
This practice helps protect against attackers who might craft malicious input to execute unauthorized commands on your system.
---
## Explicit dependency graph
When implementing algorithms involving dependencies between components or operations, model the dependency graph explicitly rather than relying on implicit ordering. Explicit graph modeling facilitates cycle detection, enables parallel execution of independent operations, and provides clear visualization of relationships between components.
Key practices:
1. Create distinct nodes for each component or operation
2. Connect nodes with directional edges based on dependencies
3. Implement specific logic for handling parallel vs. sequential execution
4. Include cycle detection in traversal operations
Example:
```go
// Create nodes for each operation
for _, operation := range operations {
node := &OperationNode{operation: operation}
graph.Add(node)
nodes = append(nodes, node)
}
// Connect nodes based on dependencies
for _, node := range nodes {
// Connect based on explicit dependencies
for _, dep := range node.operation.Dependencies() {
dependencyNode := findNodeByID(nodes, dep)
if dependencyNode != nil {
graph.Connect(dag.BasicEdge(node, dependencyNode))
}
}
// Connect parallel/sequential operations appropriately
if !node.operation.IsParallel() {
// Non-parallel operations should depend on all previous parallel operations
for _, prev := range previousParallelNodes {
graph.Connect(dag.BasicEdge(node, prev))
}
}
}
// Check for cycles during validation
if cycles := graph.Cycles(); len(cycles) > 0 {
return fmt.Errorf("dependency cycles detected: %v", cycles)
}
```
By explicitly modeling dependencies, you create a more maintainable and robust system that can handle complex execution patterns while preventing circular dependencies.
---
## Configuration file consistency
Ensure consistent patterns for configuration files, proper exclusion of development artifacts, and clear environment-specific handling across projects.
**Key practices:**
1. **Use proper .gitignore patterns** - Include wildcards for development files:
```gitignore
.wrangler
.dev.vars*
```
2. **Maintain configuration format consistency** - When migrating between formats (e.g., wrangler.toml to wrangler.json), ensure all templates and documentation are updated consistently to avoid breaking changes.
3. **Handle environment-specific configurations clearly** - Use environment variables like `CLOUDFLARE_ENV` to select configurations at build/dev time:
```toml
# wrangler.toml
name = "my-worker"
vars = { MY_VAR = "Top-level var" }
[env.production]
vars = { MY_VAR = "Production var" }
```
4. **Ensure all project types include necessary exclusions** - Both worker templates and full-stack framework templates should include wrangler-related files in .gitignore to prevent committing temporary build artifacts and sensitive development files.
This prevents configuration drift, avoids committing sensitive development files, and ensures consistent behavior across different environments and project types.
---
## Separate configuration lifecycles
Maintain clear separation between different stages of configuration processing by creating dedicated structures for each phase of the configuration lifecycle. Divide configuration handling into distinct phases:
1. **Raw configuration loading** - Parse directly from HCL/JSON without evaluation
2. **Static evaluation** - Process expressions and validate structure
3. **Runtime configuration** - Final evaluated config ready for graph processing
This separation prevents confusion, simplifies testing, and improves maintainability.
**Bad example**:
```go
// Provider represents a provider block in a module or file.
// BUT it's sometimes also used for provider instances after evaluation!
type Provider struct {
Name string
NameRange hcl.Range
Alias string
AliasExpr hcl.Expression // nil if no alias set
AliasRange *hcl.Range // nil if no alias set
ForEach hcl.Expression
EachValue *cty.Value // Only populated after evaluation
Count hcl.Expression
CountIndex *cty.Value // Only populated after evaluation
// ...
}
```
**Good example**:
```go
// ProviderBlock represents the raw provider configuration from a file
type ProviderBlock struct {
Name string
NameRange hcl.Range
Alias string
AliasExpr hcl.Expression
AliasRange *hcl.Range
ForEach hcl.Expression
Count hcl.Expression
// ...
}
// Provider represents a fully evaluated provider instance
type Provider struct {
Name string
Alias string
InstanceKey addrs.InstanceKey // From for_each/count evaluation
// ...
}
```
This approach also helps with tracking deprecated configuration fields, ensuring they're properly documented and validated at the appropriate phase, and prevents confusion around whether omitted fields should be represented in serialized output.
---
## API interface design
Design APIs with clean abstractions, logical data organization, and proper layer separation. Structure interfaces to group related data hierarchically and provide convenient helper functions instead of requiring manual object construction.
Key principles:
- Organize data logically (e.g., group assets under chains rather than as flat lists)
- Separate concerns between API layers (handle filtering in GraphQL queries, not in rendering)
- Provide constructor helpers for complex objects instead of manual assembly
- Use clear, typed interfaces with descriptive field names
Example of good API design:
```typescript
// Instead of manual object construction:
let currentTransactionParams = {
account: account.address,
abi: ucs03ZkgmAbi,
chain: sepolia,
// ... many more fields
}
// Provide helper constructors:
const params = createTransactionParams({
sourceChain: Chain,
ucs03address: Address,
value: BigInt,
baseToken: Address,
receiver: Hex
});
```
For GraphQL APIs, structure queries to reflect logical relationships and handle data processing at the appropriate layer rather than pushing complexity to consumers.
---
## avoid unnecessary memory operations
Be mindful of memory usage when working with large data structures. Avoid unnecessary clones of large objects, remove unused large fields from data structures, and prefer references when possible. Large data structures can significantly impact both memory usage and execution speed.
For example, when dealing with large arrays or collections, avoid cloning:
```rust
// Avoid - unnecessary clone of large data
let block_tx_event_count = block
.txs_results
.clone() // txs_results is quite big
// Prefer - use reference instead
let block_tx_event_count = &block.txs_results
```
Similarly, remove large unused fields from stored state:
```rust
// Remove large fields that aren't needed after initialization
// e.g., initial_sync_committee: 1024 * 384 bytes of BLS pubkeys
pub client_state: Option, // Set to None to remove large unused data
```
Always consider the memory footprint of your data structures and operations, especially in resource-constrained environments.
---
## ensure test isolation
Tests must be isolated and not leak state between runs. This includes properly cleaning up mocks, spies, and any global state modifications to ensure reliable and maintainable test suites.
Key practices:
- Configure automatic mock restoration in test setup (e.g., `restoreMocks: true` in Vitest config)
- Reset any modified global state in `afterEach` hooks
- Use explicit test setup rather than relying on shared defaults that might affect other tests
- Collect assertion data in test scope variables rather than using `expect()` inside mocks to improve debuggability
Example of proper cleanup:
```ts
describe("dialog helpers", () => {
let originalStdoutColumns: number;
beforeAll(() => {
originalStdoutColumns = process.stdout.columns;
});
afterEach(() => {
process.stdout.columns = originalStdoutColumns;
});
test("with lines truncated", async () => {
process.stdout.columns = 40;
// test logic here
});
});
```
This prevents test pollution where one test's modifications affect subsequent tests, leading to flaky or unreliable test results.
---
## Provide specific examples
Documentation should include concrete, actionable examples and use clear, unambiguous terminology to eliminate confusion for developers. Avoid vague instructions that leave developers guessing about implementation details.
When documenting commands or procedures, provide specific examples rather than generic descriptions. For instance, instead of writing "run uninstall", specify the exact command: `npm uninstall @cloudflare/workers-types`.
Choose terminology that is precise and contextually clear. Consider how terms might be interpreted differently in various contexts - for example, "Worker environments" could be confusing when discussing both Cloudflare Workers and Vite environments, so "Cloudflare environments" would be more specific and less ambiguous.
This approach helps developers understand exactly what actions to take and reduces the cognitive load of interpreting documentation.
---
## prefer standard crypto functions
Use Node.js built-in crypto module functions instead of third-party cryptographic libraries when possible. The built-in crypto module is well-maintained, follows established standards, and provides better security guarantees than external alternatives.
Standard crypto functions are more likely to receive security updates, have been thoroughly vetted, and reduce dependency risks. They also provide consistent behavior across different environments.
Example:
```javascript
// Prefer this
const crypto = require('crypto');
const hash = crypto.createHash('sha256').update(data).digest('hex');
// Instead of
const hash = blake3hash(data).toString('hex');
```
This applies to hash functions, encryption, and other cryptographic operations where Node.js provides built-in alternatives.
---
## Structure for readability
Prioritize code readability by structuring code in a way that makes it easy to understand at a glance. This includes:
1. Break complex conditions into clearer if-else blocks for better comprehension:
```python
# Instead of this:
if account_id and access_key is None and secret_key is None:
return True
# Prefer this:
if account_id is None:
return False
elif access_key is None or secret_key is None:
return True
return False
```
2. Use higher-level APIs when they express intent more clearly:
```python
# Instead of this:
path = os.sep.join([self.EXAMPLE_PATH, self._service_name + '.rst'])
# Prefer this:
path = os.path.join(self.EXAMPLE_PATH, self._service_name + '.rst')
```
3. Always use explicit `is not None` when comparing against None:
```python
# Instead of this:
if identifiers or identifiers == None:
# Prefer this:
if identifiers is not None:
```
4. Use named parameters for complex function calls to improve readability:
```python
# Instead of this with nested dictionaries:
resource = self.load('test', 'Message', model, defs, None)
# Prefer this:
resource = self.load(
service_name='test',
resource_name='Message',
model=model,
resource_defs=defs,
service_model=None
)
```
These practices help other developers understand your code faster and reduce the cognitive load when navigating the codebase.
---
## Explicit configuration definitions
{% raw %}
Ensure all configuration dependencies and environment variables are explicitly defined rather than relying on implicit behavior or assumptions. This prevents issues from version drift, missing definitions, or unclear dependencies.
For dependency management, use package manager overrides or explicit version pinning when implicit version ranges could cause compatibility issues:
```yaml
# pnpm override example
overrides:
vite: "5.4.14" # Pin to specific version when needed
```
For environment variables, explicitly define all required variables even if they're referenced elsewhere in configuration files:
```yaml
# GitHub Actions example
env:
CI_OS: ${{ runner.os }} # Explicitly define, don't just reference
TEST_PM: ${{ inputs.packageManager }}
```
This approach prevents scenarios where dependencies unexpectedly update ("vitest doesn't pin to vite 5.0 so it can easily get updated to 6 when you're not looking") or where required environment variables are referenced but not properly defined ("we also need to make sure it's defined").
{% endraw %}
---
## Descriptive migration functions
Name migration-related functions descriptively to convey their exact purpose and context of use. Include detailed documentation explaining when and how each function should be executed in the migration workflow. For example, instead of ambiguous names like `maintenancerelease`, use more specific terms like `setupBackportBranch` or `prepareMaintenanceBranch` that clearly indicate the function's purpose.
```bash
# BETTER:
# This function sets up a new maintenance branch for accepting backports
# Run this immediately after creating a branch for the previous minor version
function setupBackportBranch {
# Function implementation
# ...
}
# AVOID:
# function maintenancerelease {
# # Unclear purpose without reading implementation
# # ...
# }
```
Always include brief comments that explain why certain cleanup or setup steps are necessary, making it easier for others to understand and maintain the migration process.
---
## Deterministic isolated testing
Make integration/unit tests deterministic, isolated, and robust against async timing and ordering.
Checklist
- **No ordering dependence:** Each test must be runnable alone; avoid modifying a shared plugin/config mid-suite. For configuration permutations, create separate routes/services (or fully separate instances) per permutation.
- **Explicit state transitions:** If testing readiness/convergence, assert the initial “not ready” state first (e.g., 503) and then assert the “ready” state.
- **Single timeout strategy:** If you use a helper like `pwait_until/assert.eventually`, don’t add extra per-assert timeouts unless you truly need nested waits.
- **Synchronize to server-side truth:** Don’t rely on client-side sleeps or random timing for timing-sensitive behavior. Prefer waiting on server time/state/metrics/log lines until the expected condition is satisfied.
- **Right bounds to reduce flakiness:** Keep iteration counts/time windows just large enough; higher counts increase the chance of crossing period boundaries.
- **Guaranteed cleanup:** Ensure `teardown()`/cleanup stops every started component and closes clients even if earlier assertions fail.
Example pattern (Lua)
```lua
describe("readiness", function()
lazy_setup(function()
assert(start_kong_dp())
end)
lazy_teardown(function()
-- always stop what we started
assert(helpers.stop_kong("serve_dp"))
end)
it("transitions to ready", function()
local res = helpers.http_client("127.0.0.1", tcp_status_port):get("/status/ready")
assert.res_status(503, res) -- assert initial state
assert.with_timeout(30).eventually(function()
local r = helpers.http_client("127.0.0.1", tcp_status_port):get("/status/ready")
assert.res_status(200, r)
end)
end)
end)
```
Apply this standard whenever tests touch CP/DP sync, rate limiting/period counters, metrics/log convergence, or any configuration that can be mutated across tests.
---
## Validate Inputs Securely
Treat runtime-derived values (env vars, request data, rendered attributes) as untrusted unless they’re validated by the framework’s schema/typedefs or hardened with allowlists.
Checklist:
- Prefer typedefs/schema validation over raw `string`/ad-hoc parsing for security-sensitive fields (URLs, crypto material, etc.).
- For crypto keys, use `typedefs.key` (and restrict/validate key type/algorithm, e.g., RSA vs EC).
- Don’t let environment variables directly control production-sensitive paths/behavior; gate with explicit allowlisted logic (dev vs prod) or generate the needed config at build time.
Examples:
- Redirect URL validation:
```lua
location = typedefs.url
```
- Public key schema:
```lua
type = "record",
-- ...
public_key = typedefs.key {
description = "The RSA public key used to validate signature.",
encrypted = true,
referenceable = true,
}
```
- Avoid unsafe env-driven paths by gating:
```lua
local prefix = "/usr/local/kong"
if kong_config.development then
prefix = os.getenv("KONG_LIBRARY_PREFIX") or prefix -- allowlisted dev override only
end
prepare_prefixed_interface_dir(prefix, "gui", kong_config)
```
Apply this consistently to prevent path traversal/config injection, incorrect header handling, and weak or missing validation for URLs and cryptographic inputs.
---
## Document phased migration paths
When replacing an existing system feature with a new implementation, provide a clear and well-documented phased migration path. Design your system to support both old and new approaches simultaneously during a transition period, allowing users to migrate gradually without disruption.
For example, when implementing the S3 locking feature that replaces DynamoDB:
```terraform
# Migration path documentation for users:
# Step 1: Enable both locking mechanisms
terraform {
backend "s3" {
bucket = "state-backend"
key = "statefile"
region = "us-east-1"
dynamodb_table = "locking_table" # Old mechanism still present
use_lockfile = true # New mechanism enabled
}
}
# Step 2: After successful testing, remove old mechanism
terraform {
backend "s3" {
bucket = "state-backend"
key = "statefile"
region = "us-east-1"
use_lockfile = true
}
}
```
Implementation should handle the transition scenario with special care, such as migrating necessary data between systems, maintaining data integrity, and providing fallback mechanisms. Always include explicit instructions for the recommended migration workflow, including required commands (e.g., `init -reconfigure`) and any behavior changes users should expect during and after migration.
---
## Review consistency assumptions
Periodically reassess your database operations based on updated consistency guarantees offered by storage technologies. As database services evolve over time, operations initially designed to work around consistency limitations may become unnecessary overhead that impacts performance.
For example, in Discussion 2, there was a realization that certain digest verification steps were implemented to work around S3's eventual consistency model before 2020. After S3 became strongly consistent, these checks became redundant:
```go
// This check might have been necessary when S3 was eventually consistent
// but is no longer required with strong consistency guarantees
checkDigest := &s3.GetObjectInput{
Bucket: aws.String(bucket),
Key: aws.String(key + "-md5"),
}
_, err := s3Client.GetObject(checkDigest)
```
When migrating between database technologies (like from DynamoDB to S3), review not just the functional aspects but also consistency guarantees. Remove operations that were added as workarounds for previous limitations. Document the rationale behind these decisions for future maintainers, noting which database features you depend on and potential compatibility concerns with alternative implementations. This practice improves performance while maintaining system integrity.
---
## complete API documentation
Ensure all API configuration options are fully documented with accurate default values, required field indicators, and complete parameter tables. Missing configuration options, incorrect defaults, or incomplete documentation tables create confusion and implementation errors for developers.
When documenting API interfaces, configuration providers, or middleware options:
1. **Include all available options** - Don't omit configuration parameters that users can set
2. **Specify accurate defaults** - Use correct default values (e.g., `[]` for arrays, `""` for strings, specific values where applicable)
3. **Mark required fields correctly** - Clearly indicate which parameters are mandatory vs optional
4. **Provide complete examples** - Include required parameters in code examples, especially when they have no defaults
Example of complete API documentation:
```yaml
# Configuration Options Table
| Field | Description | Default | Required |
|:-----------|:-----------------------------------------------------|:--------|:---------|
| `endpoint` | HTTP(S) endpoint URL for the provider | "" | Yes |
| `status` | Status codes that trigger error pages | [] | No |
| `preserveRequestMethod` | Preserve original request method during forwarding | false | No |
```
This prevents developers from encountering undocumented options, incorrect assumptions about defaults, or missing required configuration that leads to runtime errors.
---
## complete observability router options
When documenting router configuration options for any provider (Docker, Consul Catalog, ECS, KV stores, Nomad, etc.), ensure that all observability-related router options are included and properly documented. This is critical for enabling comprehensive monitoring, tracing, and logging capabilities.
The following observability router options must be documented for each provider:
```yaml
# Access logs control
traefik.http.routers..observability.accesslogs=true
# Distributed tracing control
traefik.http.routers..observability.tracing=true
# Metrics collection control
traefik.http.routers..observability.metrics=true
```
These options allow developers to enable or disable specific observability features at the router level, providing fine-grained control over monitoring and debugging capabilities. Without proper documentation of these options, developers cannot effectively configure observability for their services.
Additionally, when documenting router-level observability, clarify the relationship with global settings: "To enable router-level observability, you must first enable access-logs, tracing, and metrics globally. When metrics layers are not enabled with the `addEntryPointsLabels`, `addRoutersLabels` and/or `addServicesLabels` options, enabling metrics for a router will not enable them."
This ensures developers understand both the configuration options available and the prerequisites for their effective use.
---
## Secure checkout configurations
{% raw %}
When configuring GitHub Actions workflows, pay special attention to the checkout action's configuration to ensure both correctness and security:
1. In `pull_request_target` workflows, always specify the reference explicitly to ensure you're working with the intended branch:
```yaml
- name: Checkout code
uses: actions/checkout@v4
with:
ref: ${{ github.head_ref }}
```
2. When your workflow only needs specific files or directories, use sparse-checkout to minimize unnecessary file access and improve security:
```yaml
- name: Checkout specific files
uses: actions/checkout@v4
with:
sparse-checkout: |
.changes/
.changie.yaml
```
This practice helps protect against security risks when workflows might have elevated permissions, particularly when running on code from external contributors. Sparse checkouts also improve performance by reducing the amount of data transferred.
{% endraw %}
---
## Hot-Path Performance Rules
Default to performance-aware coding for hot paths (proxy routing, request parsing, metrics/serialization, and request body handling):
- **Avoid unnecessary periodic work**: only schedule timers or run refresh logic when the correctness mode requires it.
- **Do not add extra O(n) work in hot paths**: avoid length/count scans like `tb_nkeys()` on request-critical structures; prefer constant-time checks (e.g., `next()`-based) or use existing router-provided capture counts.
- **Reuse per-module/per-conf objects**: never allocate metatables/functions/large helper tables inside request-handling functions when the structure is reusable.
- **Minimize nginx/Kong accessor overhead**: prefer the cheaper single-value accessors (`ngx.ctx`, `ngx.var.http_content_type`, `ngx.header[name]`) over higher-level helpers when the value is already available.
- **Eliminate redundant per-request work**: ensure request body reads happen only once per request lifecycle.
- **Guard expensive debug logging**: don’t build JSON/strings for debug logs unless debug logging is enabled.
- **Measure before simplifying**: if you propose a code simplification in a performance-sensitive utility, require a microbenchmark/profile result—simpler code can be slower.
Example (constant-time capture check + localizing `next`):
```lua
local next_ = next
-- captures = { [0]=full_path, [1]=cap1, ... }
local function has_uri_captured(captures)
if not captures then return nil end
-- constant-time check for any key other than [0]
if captures[1] then
return captures
end
return next_(captures, 0) and captures or nil
end
```
Example (reuse metatable outside the hot function):
```lua
local payload_mt = {
__newindex = function(t, k, v)
-- set dot-path values
end,
}
local function build_payload(template_payload)
return setmetatable(template_payload, payload_mt)
end
```
If you’re unsure whether a change is beneficial, treat it as a performance work item: profile/flamegraph or microbenchmark it under realistic inputs before merging.
---
## Document with examples
Always include comprehensive documentation with clear examples for properties, methods, and code patterns. Documentation should include:
1. **Property descriptions**: Use the `description:` attribute to explain what each property does
```ruby
property :source_location, introduced: "17.6", String,
description: "The location where the package source resides."
```
2. **Version information**: Add `@since` tags and `introduced:` attributes to track when features were introduced
```ruby
# @since 17.9
property :only_record_changes, [TrueClass, FalseClass], default: false,
description: "Only record changes to the registry key."
```
3. **Usage examples**: Provide concrete examples, especially for complex features
```ruby
# For command options:
option :connection_protocol,
short: "-o PROTOCOL",
long: "--connection-protocol PROTOCOL",
description: "The protocol to use to connect to the target node (such as 'ssh' or 'winrm')."
```
4. **Pattern matching examples**: When documenting pattern matching or regular expressions, include example lines that would match the pattern
```ruby
# This matches mount points like "/mnt/volume"
when /\A#{Regexp.escape(real_mount_point)}\s+#{device_mount_regex}\s/
```
5. **Accessible language**: Use plain language descriptions over technical jargon when possible, and spell out "regular expression" instead of "regex" in user-facing documentation
Comprehensive documentation reduces the learning curve for new developers and makes the codebase more maintainable.
---
## Network semantics consistency
When implementing HTTP/TCP/WebSocket/networking logic, treat protocol semantics as “correctness-critical”: don’t rely on accidental behavior, and don’t assume inputs are single-valued.
Apply these rules:
1) Be consistent about connection lifecycle
- If you use a higher-level HTTP client (e.g., lua-resty-http), assume it manages keepalive/SSL as documented; don’t partially override by mixing raw socket operations unless you fully own SSL/keepalive/close behavior.
- For correctness tests/connection reuse issues, prefer fully closing the underlying socket over half-close patterns.
2) Defensively handle multi-value headers
- In OpenResty, the same header name can yield a string or a table when the client sends duplicates. Pick a deterministic rule (e.g., “take first” or “ignore if duplicated”) and enforce it.
3) Normalize outbound URLs
- Ensure URL paths are absolute (e.g., prepend “/” when missing) before passing to request/builders.
4) Avoid fragile query parsing/merging
- Naive string parsing can drop duplicate keys and mishandle encoding/edge cases. If correct merging semantics are unclear, avoid merging or use a proper query parser that preserves duplicates.
5) Parse WebSocket subprotocol lists correctly
- For `Sec-WebSocket-Protocol`, treat it as a list of tokens and compare exact compatible values—don’t use substring matching.
Example (multi-value header handling):
```lua
local function first_header_value(v)
if type(v) == "table" then
return v[1]
end
return v
end
local instana_t = first_header_value(headers["x-instana-t"])
local instana_s = first_header_value(headers["x-instana-s"])
```
---
## Standardize installation directory paths
Maintain consistent and separate installation paths for different build types to prevent conflicts and improve system organization. Use `/hab` directory for Habitat builds and `/opt/chef` for Omnibus installations.
Key guidelines:
- Place Habitat-built components under `/hab/` directory
- Keep Omnibus installations under `/opt/chef/`
- Use distinct directories for migration tools (e.g., `/hab/migration/`)
- Avoid mixing paths between build types
Example directory structure:
```
# Habitat builds
/hab/
├── chef/
│ └── bin/
└── migration/
├── bin/
└── bundle/
# Omnibus installations
/opt/chef/
├── bin/
└── bundle/
```
This separation enables:
- Clear distinction between installation types
- Easier cookbook checks and compatibility verification
- Simplified upgrade paths
- Prevention of file conflicts between different versions
---
## Cache Consistency Rules
When implementing caching, make coherence and invalidation explicit and configuration-driven:
- If a setting promises immediate consistency (e.g., “strict”), do not perform lazy reloads; rely on the update pipeline to keep cached data correct.
- For multi-worker systems, prefer shared caches (e.g., ngx.shared or equivalent) so workers don’t recompute independently; unnecessary recomputation increases both CPU cost and inconsistency risk.
- Tie TTLs to the real invalidation mechanism. Don’t add TTL “just because” when cascade delete or another definitive mechanism already removes stale data. When a TTL is required, use the intended constant so behavior is predictable.
Example pattern (versioned + conditional reload):
```lua
-- cache state
local upstream_version = 0
local all_upstreams
local function reset_all_upstreams()
-- recompute and repopulate shared/local state
-- ...
upstream_version = new_upstream_version
all_upstreams = upstreams_dict
return true
end
reload_all_upstreams = function()
-- in strict consistency mode, skip reloads entirely
if kong.configuration.upstream_consistency == "strict" then
return true
end
-- otherwise reload only when upstreams changed
if upstream_version == new_upstream_version then
return true
end
return reset_all_upstreams()
end
```
Checklist to apply during review:
1) Does any config imply strict correctness? If yes, is lazy reload/invalidation disabled accordingly?
2) Is the cache shared across workers (or otherwise proven consistent)?
3) Is TTL aligned with how entries actually become invalid (TTL vs cascade delete vs explicit version updates)?
---
## Consistent, Actionable Logging
When adding/modifying logs, follow these rules:
1) Use the Kong logging API
- Prefer `kong.log.` (e.g., `kong.log.err(...)`) over `ngx.log(...)` to keep logging consistent with Kong conventions.
2) Pick the right level (avoid noise)
- Don’t leave payload/verbose debugging at `warn`/`err` (e.g., log payloads at `debug` only).
- Be extra cautious with logs in background workers, timers, and automated paths—debug logs can flood and be hard to disable. Log on failure, and use debug sparingly.
3) Make error messages actionable
- If the behavior is governed by a config knob, mention the knob value (e.g., “giving up after max_retry_time exceeded: X”).
4) Log enough context to diagnose failures, but in the right layer
- Include identifiers for the failing operation (entity/op/node) so support can trace what broke.
- Prefer instrumenting the function that actually performs the work (e.g., the sender/handler) rather than sprinkling one-off logs.
Example pattern:
```lua
-- Prefer kong.log over ngx.log
local ok, err = send_entries(conf, { entry })
if not ok then
kong.log.err(string.format(
"could not send http-log entries; giving up after max_retry_time=%d exceeded",
conf.max_retry_time
))
-- keep any success traces at debug, and avoid spamming timers
end
```
Apply this checklist across plugins, clustering/rpc, queue/timer processing, and any new debug instrumentation.
---
## Concurrency primitive semantics
When introducing async work, retries, or batching:
1) Use each concurrency primitive for its intended role
- Don’t repurpose a queue as a parallel executor. If you need the same per-entry logic from both the queue and direct callers, extract it into a shared function/module and have both paths call it.
2) Make concurrency-limit meanings unambiguous
- Define clearly what values mean “disabled” vs “unlimited” (and keep it consistent across the codebase). If you choose a sentinel (e.g. `-1`), document it where the option is read and ensure callers won’t assume `0` means unlimited.
3) Prefer mutex helpers over ad-hoc lock code
- Use shared lock helpers (e.g., `concurrency.with_worker_mutex`) to avoid race bugs and to centralize lock/timeout/exptime behavior.
4) Be careful with timers under locks
- Avoid unnecessary timers for already-asynchronous “notification” steps when the cost is negligible.
- When retrying, decide whether to release the mutex or retry while holding it, and treat lock-timeout separately from real failures.
- Don’t rely on tail-recursive timer creation; if a timer callback may be scheduled via tail recursion, schedule with a small delay instead of `0` to avoid timer stack/callsite issues.
5) Avoid timer fan-out in batch code
- If batch items would each spawn timers, consider doing the batch synchronously (or waiting for all spawned work) to prevent runaway scheduling.
Example pattern (mutex helper + safe reschedule):
```lua
local function retrying_sync(premature, retry_count)
if premature then return end
local res, err = concurrency.with_worker_mutex({
name = "get_delta",
timeout = 0,
exptime = 5,
}, function()
return do_sync() -- shared logic; retry decision handled outside if needed
end)
if not res and err ~= "timeout" then
ngx_log(ngx_ERR, "sync failed: ", err)
return
end
-- avoid tail-recursion/timerng crash cases
kong.timer:at(0.1, retrying_sync, (retry_count or 0) + 1)
end
```
Apply this standard during review by checking: (a) are primitives used for their intended semantics, (b) are unlimited/concurrency-limit semantics consistent, (c) are mutex/timer interactions safe under contention, and (d) does batch logic avoid uncontrolled timer spawning.
---
## maintain clean project structure
Keep your codebase organized and clutter-free by removing unnecessary files, directories, and artifacts that serve no functional purpose. When tools have compatibility issues with certain file types, configure appropriate ignore patterns rather than leaving problematic files to cause confusion or errors.
Examples of maintaining clean structure:
- Remove empty directories with .gitkeep files when they're no longer needed
- Add problematic file types to tool ignore files (e.g., .prettierignore for .d.ts files that cause parsing errors)
- Question whether directories and files are actually necessary before adding them to the project
This practice reduces cognitive load for developers, prevents confusion about project structure, and ensures that development tools work reliably without encountering parsing or processing errors.
---
## Document configuration decisions
Add clear comments explaining the rationale behind configuration decisions, especially for workarounds, compatibility fixes, or environment-specific settings. This helps future maintainers understand why certain configurations exist and prevents accidental removal of necessary settings during refactoring.
Good examples:
```yaml
# back compat for pre-unified-/usr distros, do not add new OSes
- remote: sudo ln -s /usr/bin/install /bin/install
```
```yaml
# We have to use 20.04 host for these operations otherwise
# the dokken images throw timedatectl error
linux-2004-host:
```
Prefer specific version identifiers over relative terms (like "latest") to ensure reproducibility and prevent unexpected behavior when defaults change:
```yaml
# Instead of: name: macos-latest # arm64
- name: macos-14 # arm64
```
---
## API surface compatibility
Treat any change to a public interface (PDK function signatures, plugin config/schema fields, or other externally-consumed API contracts) as a compatibility commitment.
**Do**
- **Avoid expanding public API surface** unless the benefit is clear and the tradeoffs are acceptable.
- If a function signature must change, **append new parameters at the end** (never insert in the middle) to preserve positional-arg compatibility.
- For **schema/config additions**: require a compatibility plan—discussion/approval, **changelog entry**, and any related compatibility/removed-fields plumbing (and tests that validate the schema).
**Don’t**
- Don’t add new public parameters that “paint you into a corner” without a strong necessity.
- Don’t change schema semantics/config options without coordinating compatibility artifacts.
**Example (signature change rule)**
```lua
-- Before
function compose_tags(service_name, status, consumer_id, tags, conf) end
-- After (append new param at the end)
function compose_tags(service_name, status, consumer_id, tags, conf, route_name) end
```
Apply this checklist whenever a change touches externally-defined contracts: if users (or other plugins) might call it, update it with backward compatibility as the default and a documented migration/compat story.
---
## Consistent Early-Exit Style
When updating/adding code, prioritize readability and predictable control-flow:
- Use early exits (return/goto/continue) for error/invalid states to avoid deep nesting/extra indentation.
- Keep error-handling visually tight (no distracting blank lines between the call and the error check).
- For error logs, follow formatting rules:
- Avoid Lua string concatenation inside ngx_log/ngx.log; pass multiple arguments instead.
- Use the required capitalization for error messages (e.g., don’t capitalize the message text).
- Prefer clearer positive conditions over negated/complex expressions, and simplify large if/else chains where possible.
Example pattern (body parsing + early exit + logging):
```lua
local body, err = kong.request.get_body()
if err then
ngx_log(ngx.ERR, "cannot process request body: ", tostring(err))
return
end
local identifier = body -- proceed normally
```
Example logging without concatenation:
```lua
ngx_log(ngx.ERR, "request failed (", req_url, "): ", err)
```
---
## Externalize configuration values
Avoid hardcoding configuration values directly in scripts, especially for values that might change between environments or contain sensitive information. Instead, use environment variables, build parameters, or secrets management systems.
Key practices:
1. Move endpoint URLs, license keys, and service addresses to environment variables
2. Maintain consistent naming conventions for environment variables across different scripts
3. Configure CI/CD systems to inject these values during build and deployment
4. Use default values only for development environments, never for production configurations
Example - Instead of:
```bash
export CHEF_LICENSE_SERVER="http://hosted-license-service-lb-8000-606952349.us-west-2.elb.amazonaws.com:8000"
```
Use:
```bash
export CHEF_LICENSE_SERVER="${CHEF_LICENSE_SERVER:-fallback_value_for_dev_only}"
```
Or configure the value in your CI/CD system's environment variables or secrets store.
For version information, prefer environment variables provided by your CI/CD system over reading from files:
```bash
# Preferred
VERSION="${EXPEDITOR_VERSION}"
# Avoid
VERSION=$(cat VERSION)
```
---
## Prefer guard clauses
Use guard clauses with early returns for null checking instead of wrapping code in conditional blocks. This improves readability by reducing nesting and making the code's "happy path" more evident.
```ruby
# Instead of this:
unless current_record.nil?
current_record.status = :skipped
current_record.conditional = conditional
end
# Do this:
return if current_record.nil?
current_record.status = :skipped
current_record.conditional = conditional
```
For method chains with potential null values, use the safe navigation operator (`&.`) instead of explicit conditional blocks:
```ruby
# Instead of:
if license_keys.nil?
nil
else
license_keys.empty?
end
# Do this:
license_keys&.empty?
```
When checking for truthiness, use Ruby's idiomatic style which treats only `nil` and `false` as falsey:
```ruby
# Instead of:
unless new_resource.download_url.nil?
# code
end
# Do this:
if new_resource.download_url
# code
end
```
Remember to use `.compact` to remove nil values from arrays when needed:
```ruby
array_with_nils.compact # Returns a new array with all nil elements removed
```
Only use safe navigation when the object might actually be nil. Don't use it on objects that will never be nil, such as class constants:
```ruby
# Unnecessary:
::File&.dirname(path)
# Better:
::File.dirname(path) # Since ::File will never be nil
```
---
## Use appropriate comment syntax
Choose the correct comment syntax based on the file type and processing system to ensure documentation serves its intended purpose. For template files (like Jinja), use template-specific comments rather than HTML comments to prevent documentation from appearing in rendered output. Always include explanatory comments for files that might seem unnecessary but serve a specific purpose.
For example, in a Jinja template file:
```html
{#
DO NOT REMOVE THIS FILE
This file is normally inherited from the version defined by our docs theme.
However, that file includes in-line styling which isn't allowed by our website's
Content Security Policy (CSP). This empty file overwrites the template inherited
from the theme.
#}
```
Instead of:
```html
```
This ensures maintenance documentation remains visible to developers but doesn't leak into generated artifacts seen by end users.
---
## eliminate redundant null checks
Remove unnecessary null/undefined checks when you already have sufficient validation in place, and use proper type guards instead of type assertions for better null safety.
When you've already validated that a value is truthy or non-null, avoid redundant checks that add noise without providing additional safety. Similarly, prefer type guard functions over type assertions to maintain proper null safety.
Examples of improvements:
- If you have `if (match)` then `const [, year, month, date] = match` is sufficient - no need for `match ?? []`
- Instead of checking both `response instanceof UndiciResponse && !(response instanceof Response)`, determine which single check provides the necessary validation
- Replace type assertions like `(newModule as Record)` with proper type guard functions that can handle null/undefined cases safely
This approach reduces code complexity while maintaining robust null handling, making your code both cleaner and safer.
---
## Explicit configuration over implicit
Always define explicit configuration defaults rather than relying on implicit behavior or autovivification. Configuration values should:
1. Use explicit nil defaults instead of undefined values
2. Document default values clearly in property descriptions
3. Use Chef::Config for global settings rather than environment variables
4. Consider platform-specific variations when defining defaults
Example:
```ruby
# Bad - Implicit default
property :store_location, String
# Good - Explicit default with clear documentation
property :store_location, String,
default: nil,
description: "Use the `CurrentUser` store instead of the default `LocalMachine` store."
# Bad - Environment variable configuration
default :use_s3_cache, ENV['USE_S3_CACHE'] == 'true'
# Good - Chef::Config configuration
config_context :caching do
default :use_s3, false
end
```
This approach improves code clarity, makes behavior more predictable, and ensures proper documentation of configuration options. It also facilitates better testing and maintenance by making all possible states explicit.
---
## Function-focused code organization
Files should contain only code related to their named purpose, with proper organization and formatting. When adding functionality:
1. Place code in files that match their purpose (e.g., theme-related code belongs in general utilities, not in specialized modules)
2. Create dedicated, well-named functions for specific tasks
3. Follow established patterns for code organization in the project
4. Run all JavaScript changes through a formatter for readability and maintainability
Example of good organization:
```js
// In custom.js (not in specialized files like loadShortbread.js)
function loadThemeFromLocalStorage(){
document.body.dataset.theme = localStorage.getItem("theme") || "auto";
}
function runAfterDOMLoads() {
expandSubMenu();
makeCodeBlocksScrollable();
setupKeyboardFriendlyNavigation();
// Organized functions called in appropriate place
loadThemeFromLocalStorage();
loadShortbread();
}
```
---
## Maintain naming consistency
Ensure consistent terminology and naming conventions across the entire codebase. Use the same identifier names for the same concepts throughout all modules, files, and APIs. Avoid defining the same logical entity with different names in different places.
Key principles:
- Use consistent terminology across all components (e.g., consistently use "receiver" instead of mixing "receiver" and "recipient")
- Follow established protocol or framework naming standards (e.g., use "ucs01-relay-1" format for version identifiers)
- Maintain single source of truth for variable definitions - avoid defining the same concept in multiple places with different names
- When renaming for consistency, update all related code simultaneously
Example of inconsistent naming to avoid:
```typescript
// Bad: Same concept with different names
const recipient = $page.url.searchParams.get("receiver")
const transferHash = await unionClient.transferAsset({
recipient: $recipient // Should be "receiver" to match URL param
})
// Good: Consistent naming
const receiver = $page.url.searchParams.get("receiver")
const transferHash = await unionClient.transferAsset({
receiver: $receiver
})
```
This prevents confusion, reduces cognitive load, and makes the codebase more maintainable by ensuring developers can rely on consistent naming patterns.
---
## avoid suppressing TypeScript errors
Do not use `@ts-expect-error` comments to suppress TypeScript errors, especially those related to null, undefined, or type safety. These errors are designed to catch potential runtime issues and should be properly resolved instead of silenced.
TypeScript's type system helps prevent null reference errors and other type-related bugs. When you encounter type errors, investigate and fix the root cause rather than suppressing them.
Instead of:
```typescript
// @ts-expect-error
someFunction(potentiallyNullValue)
```
Fix the underlying issue:
```typescript
if (potentiallyNullValue !== null) {
someFunction(potentiallyNullValue)
}
```
Similarly, prefer type-safe patterns like `derived()` stores for read-only computed values instead of `writable()` stores that allow unsafe mutations:
```typescript
// Prefer this - read-only derived state
let destinationChain = derived(chains, $chains =>
$chains.find(chain => chain.chain_id === destination)
)
// Over this - writable store for derived data
let destinationChain = writable(chains.find(chain => chain.chain_id === destination))
```
If you must temporarily suppress an error during development, add a detailed comment explaining why and create a task to fix it properly.
---
## telemetry documentation consistency
Maintain consistent formatting and style when documenting telemetry and observability systems. This includes using parallel structure in lists, consistent terminology, and clear explanations of what data is collected and why.
When documenting telemetry collection, ensure:
- List items follow parallel grammatical structure
- Consistent phrasing across similar concepts (e.g., "Package manager" vs "Package manager being used")
- Clear, professional language that explains the purpose and scope of data collection
- Proper punctuation and formatting throughout
Example of inconsistent vs consistent formatting:
```markdown
// Inconsistent
- What command is used as the entrypoint?
- Package manager being used (e.g. npm, yarn)
- Number of first time downloads
// Consistent
- Command used as entrypoint
- Package manager (e.g. npm, yarn)
- Whether instance is a first-time download
```
This ensures that observability documentation is professional, clear, and maintains user trust by transparently communicating monitoring practices.
---
## Privacy documentation clarity
When documenting data collection practices, telemetry, or analytics features, explicitly enumerate what sensitive information is NOT collected to ensure transparency and build user trust. Privacy statements should be clear, comprehensive, and easily understandable.
The documentation should specifically list categories of sensitive data that are excluded from collection, such as usernames, raw error logs, stack traces, file paths, file contents, and environment variables. This transparency is crucial for security compliance and user confidence.
Example from telemetry documentation:
```markdown
## What happens with sensitive data?
Cloudflare takes your privacy seriously and does not collect any sensitive information including: usernames, raw error logs, stack traces, file names/paths, content of files, and environment variables. Data is never shared with third parties.
```
This approach helps users understand exactly what privacy protections are in place and demonstrates a commitment to responsible data handling practices.
---
## Promise error handling patterns
When handling promise errors, use the second callback parameter of `.then()` instead of `.catch()` when you want to handle only the specific promise rejection and avoid accidentally catching programmer errors from the success handler. Use `.catch()` only when you intend to handle all errors in the promise chain.
Additionally, use appropriate error types and provide meaningful context in error messages. Use `ServerlessError` for user configuration issues and regular `Error` for API/programming issues. Always include error codes for better monitoring and add relevant context like resource names to error messages.
Example of proper promise error handling:
```javascript
// Good - only catches errors from the specific promise
return this.provider.request('ApiGatewayV2', 'getApi', { ApiId: id })
.then(result => {
stackData.externalHttpApiEndpoint = result.ApiEndpoint;
}, error => {
throw new this.serverless.classes.Error(
`Could not resolve provider.httpApi.id parameter. ${error.message}`,
'HTTPAPI_ID_RESOLUTION_ERROR'
);
});
// Avoid - catches both promise rejection AND any errors in success handler
return this.provider.request('ApiGatewayV2', 'getApi', { ApiId: id })
.then(result => {
stackData.externalHttpApiEndpoint = result.ApiEndpoint;
})
.catch(error => {
throw new this.serverless.classes.Error(
`Could not resolve provider.httpApi.id parameter. ${error.message}`
);
});
```
This pattern prevents masking programmer errors while ensuring proper error context and appropriate error types for better debugging and monitoring.
---
## Isolate config state
Configurable behavior must be isolated per plugin/consumer instance, and derived/internal values must not be injected into the schema-defined `conf` object. This prevents cross-request/config leakage and keeps schema validation predictable—especially during deprecations.
Apply:
- Don’t store per-config options in module-level locals (shared by all instances/requests in the same worker). Store them on an instance/table created per consumer/plugin.
- Treat `conf` as schema input: if you need computed/compiled data, create a separate table and pass it alongside `conf`.
- When introducing deprecated/new config fields, ensure both sides resolve/validate consistently for reference/vault values; don’t rely on `replaced_with` to “magically” reconcile dereferencing.
Example (instance-scoped state instead of module locals):
```lua
-- BAD: module-level mutable config shared across instances
-- local use_proto_names = false
-- function protojson:configure(options) use_proto_names = options.use_proto_names end
-- GOOD: store config on the instance
local protojson = {}
protojson.__index = protojson
function protojson.new(options)
return setmetatable({
use_proto_names = options.use_proto_names or false,
enum_as_name = options.enum_as_name or false,
emit_defaults = options.emit_defaults or false,
json_names = options.json_names or {},
}, protojson)
end
function protojson:decode_to_json(msg_type, msg)
-- use self.use_proto_names etc.
end
```
Example (don’t mutate `conf` with non-schema fields):
```lua
function OpenTelemetryHandler:log(conf)
local options = {}
if conf.resource_attributes then
options.compiled_resource_attributes = otel_utils.read_resource_attributes(conf.resource_attributes)
end
otel_traces.log(conf, options) -- pass alongside conf
end
```
---
## Write clear examples
Create comprehensive code examples in documentation that demonstrate common operations and use proper formatting. Use double backticks (``) for inline code references in reStructuredText, and wrap code blocks in proper directives:
```
.. code-block:: python
import boto3
# Create an S3 client
s3 = boto3.client('s3')
# Upload a file to S3 - this demonstrates the simple method for small files
s3.upload_file('local/path/to/file', 'my-bucket', 'key/name.txt')
```
Always include explanatory comments that describe what each section accomplishes. For service-specific guides, include examples of frequently used operations like upload/download for S3. When documenting parameters or return values, use accurate descriptions that match the underlying implementation. Always generate and preview documentation before submission to ensure correct rendering.
---
## Consistent region configuration
Always maintain consistency in region configurations throughout your application. Instead of hardcoding endpoints, use proper region configuration which allows for better maintainability and fewer errors. When working with region-dependent services like S3, ensure your client configuration region matches the service requirements.
For example, when creating S3 buckets:
```python
# Good practice: Configure region once and use it consistently
region_name = 'us-west-2'
s3_client = boto3.client('s3', region_name=region_name)
# When creating a bucket, use the same region in LocationConstraint
s3_client.create_bucket(
Bucket=bucket_name,
CreateBucketConfiguration={'LocationConstraint': region_name}
)
```
Remember that configuration sources have precedence - programmatic configurations (like client parameters) will override environment variables and config files. When multiple configuration sources exist, be explicit about which one takes precedence to avoid unexpected behavior.
---
## Demonstrate canonical API patterns
Always provide examples that demonstrate the recommended and most current API usage patterns. This includes:
1. Using the most up-to-date API operations (e.g., prefer ListObjectsV2 over ListObjects)
2. Showing proper parameter passing conventions (positional vs. keyword arguments)
3. Including handling for special cases like region-specific logic
4. Testing all examples to verify they work as documented
Examples should be concise but complete enough to show proper usage:
```python
# CORRECT: Proper parameter passing for upload_file (positional arguments)
s3.upload_file(filename, bucket_name, key_name)
# INCORRECT: Attempting to use keyword arguments for positional parameters
s3.upload_file(Bucket=bucket_name, Filename=filename) # This will fail!
# CORRECT: Handling region-specific bucket creation
bucket_config = {}
if region != "us-east-1":
bucket_config["CreateBucketConfiguration"] = {"LocationConstraint": region}
s3.create_bucket(Bucket=bucket_name, **bucket_config)
# CORRECT: Using the recommended V2 API version
event_system.register('before-parameter-build.s3.ListObjectsV2', add_my_bucket)
```
Validating examples against the actual implementation helps catch discrepancies between documentation and behavior, ensuring developers can trust your API examples as authoritative references.
---
## Secure credential management
When handling passwords, certificates, or keys in your code, implement secure encryption and storage mechanisms to prevent exposure of sensitive data.
Key practices:
1. Use strong encryption with unique salts when hashing sensitive data to prevent rainbow table attacks:
```ruby
# Poor implementation - vulnerable to rainbow tables
def obscure(cleartext)
return nil if cleartext.nil? || cleartext.empty?
Digest::SHA2.new(256).hexdigest(cleartext)
end
# Better implementation - with salt
def obscure(cleartext)
return nil if cleartext.nil? || cleartext.empty?
salt = SecureRandom.hex(16) # Generate a random 16-byte salt
hash = Digest::SHA2.new(256).hexdigest(salt + cleartext)
{ hash: hash, salt: salt } # Store both hash and salt
end
```
2. Use platform-appropriate secure storage mechanisms (registry on Windows, keychain on macOS) rather than storing credentials in plaintext files.
3. When migrating between encryption methods, ensure backward compatibility while maintaining or improving security. Plan for safe key rotation without disrupting existing implementations.
4. Use dedicated encryption libraries when available rather than implementing your own cryptography:
```ruby
# Prefer built-in encryption libraries over custom implementations
Chef::ReservedNames::Win32::Crypto.encrypt(password)
```
5. Validate that credential operations succeed and provide meaningful error handling when they fail, without exposing sensitive details in logs or error messages.
---
## preserve original error codes
When handling errors, preserve the original error information rather than replacing it with generic error constants. This maintains better debugging information and error traceability throughout the system.
Instead of using generic error constants that lose the specific failure context:
```move
assert!(err == 0, E_INVALID_PROOF);
```
Preserve the original error code to maintain debugging information:
```move
assert!(err == 0, err);
```
This practice ensures that:
- Specific error details are not lost during error propagation
- Debugging becomes easier as the root cause error code is preserved
- Error handling maintains the original context of what actually failed
- Developers can trace back to the exact source of errors
Apply this principle consistently across error handling scenarios where you have access to the original error information. The goal is to maintain error fidelity rather than abstracting away potentially useful diagnostic information.
---
## Defensive null handling
Always initialize data structures before use, particularly before accessing them in loops or conditional blocks. Check for null values before accessing their properties, and provide clear, contextual error messages when null values are not allowed.
Three key practices to follow:
1. **Initialize maps and slices before they're used in loops**
```go
// Bad: May cause null pointer exception
for k, v := range instanceVariableMap {
m.Aliases[k] = v // m.Aliases might be nil
}
// Good: Initialize first
m.Aliases = make(map[addrs.InstanceKey]string)
for k, v := range instanceVariableMap {
m.Aliases[k] = v
}
```
2. **Validate nullability with specific error messages**
```go
// Bad: Generic or missing null validation
if val.IsNull() {
return errors.New("invalid value")
}
// Good: Clear context about why null isn't allowed
if val.IsNull() {
return &hcl.Diagnostic{
Severity: hcl.DiagError,
Summary: "Import block 'to' address contains an invalid key",
Detail: "Import block contained a resource address using an index which is null. Please make sure the expression for the index is not null",
Subject: expr.Range().Ptr(),
}
}
```
3. **Ensure map initialization happens even in error paths**
```go
// Bad: Variables only initialized in happy path
if len(refs) == 0 {
ctx.Variables = make(map[string]cty.Value)
return ctx, diags
}
// Good: Initialize early to handle all code paths
ctx := parent.NewChild()
ctx.Functions = make(map[string]function.Function)
ctx.Variables = make(map[string]cty.Value)
```
When appropriate, create helper methods (like `IsValid()` or `IsSet()`) for commonly repeated null checks to improve code readability.
---
## Choose appropriate async primitives
Select async/concurrency primitives based on your specific usage patterns and requirements rather than defaulting to generic solutions. Different async contexts benefit from different tools:
**Cancellation patterns**: Use dedicated utilities like `CancellationToken::run_until_cancelled()` instead of manual `tokio::select!` loops when you need simple cancellation logic.
```rust
// Instead of manual select loops:
loop {
tokio::select! {
Ok((stream, _)) = listener.accept() => { /* handle */ }
_ = token.cancelled() => { break; }
}
}
// Use the dedicated utility:
token.run_until_cancelled(async {
// your async logic here
}).await;
```
**Data flow patterns**: Prefer Streams over channels when you need concurrent message processing and better debugging capabilities. Streams allow for easier composition with `.inspect()`, `.for_each_concurrent()`, and other combinators.
```rust
// Instead of channels:
let (tx, mut rx) = mpsc::channel(chunk_size);
fetch_range(tx, slice).await?;
while let Some(message) = rx.recv().await { /* handle */ }
// Use streams:
let stream = fetch_range(slice).instrument(info_span!("fetch"));
stream.for_each_concurrent(None, |message| handle_message(message)).await;
```
**Synchronization**: Use async-aware locks (like `tokio::sync::RwLock`) only when you need to hold the lock across await points. For short, synchronous critical sections, prefer `std::sync` or `parking_lot` locks for better performance.
```rust
// Use async locks only when holding across awaits:
let guard = async_lock.lock().await;
some_async_operation().await; // Lock held across await
drop(guard);
// Use sync locks for quick operations:
{
let guard = sync_lock.lock().unwrap();
quick_synchronous_work();
} // Lock automatically released
```
This approach reduces complexity, improves performance, and makes code more maintainable by matching the tool to the specific concurrency requirements.
---
## Complete CI/CD documentation
Ensure all CI/CD documentation is comprehensive and technically accurate, covering complete workflows and tooling capabilities. Incomplete or incorrect documentation leads to deployment failures, misconfigurations, and developer confusion.
Documentation should include:
- All deployment scenarios (initial deployment, rollbacks, parameter retrieval)
- Accurate build tool configurations and supported formats
- Complete feature coverage without assumptions
For example, when documenting deployment buckets, include all use cases:
```markdown
# Deployment Bucket
Storage for Lambda code, CloudFormation templates, and other resources
required for service deployment, service rollback, and efficient parameter retrieval.
```
When documenting build configurations, verify technical accuracy:
```markdown
**Note:** Build output format can be configured for both CommonJS and ESM.
See esbuild documentation for format options.
```
This prevents developers from making incorrect assumptions that could cause deployment issues or require workarounds.
---
## Validate network addresses
Always validate network addresses according to their specific protocol requirements and maintain consistent encoding throughout the application. Different blockchain networks have distinct address formats and validation rules that must be enforced to prevent communication failures.
For each destination network, implement proper validation:
- EVM chains: Validate checksum and format (0x prefixed, 40 hex characters)
- Cosmos-based chains: Validate bech32 encoding with correct prefix
- Other protocols: Apply their specific validation rules
Ensure address encoding consistency across all network operations. Inconsistent encoding (like using checksummed vs non-checksummed addresses) can cause lookup failures and break packet transmission.
Example validation approach:
```javascript
// Validate based on destination chain
if (isEvmChain(destinationChain)) {
if (!isValidEvmAddress(address) || !hasValidChecksum(address)) {
throw new Error('Invalid EVM address or checksum');
}
} else if (isCosmosChain(destinationChain)) {
if (!isValidBech32Address(address, expectedPrefix)) {
throw new Error('Invalid bech32 address or prefix');
}
}
```
This prevents network communication failures and ensures reliable cross-chain operations.
---
## Consistent descriptive naming patterns
Use clear, descriptive names that follow consistent patterns across the codebase. For methods and properties:
1. Use intention-revealing names that clearly indicate purpose
2. For boolean methods, use question-mark suffixes and appropriate prefixes
3. Maintain consistent naming patterns across similar properties
4. Use lowercase for variables unless they are true constants
Examples:
```ruby
# Poor naming
def compare_users # unclear if returns boolean
def detect_certificate_key # verb is ambiguous
property :certpassword # inconsistent with other properties
# Good naming
def users_changed? # clear boolean return
def certificate_key_exist? # clear boolean check
property :cert_password # consistent with other properties
# Property naming consistency
property :user # preferred over user_name
property :password # preferred over pass
```
This pattern improves code readability, maintains consistency, and reduces cognitive load when working across different parts of the codebase.
---
## Provide contextual explanations
Documentation should explain the reasoning, context, and practical implications behind code examples, not just show syntax or commands. Include explanations of why developers would use specific approaches, how different options work together, and what to expect from running commands.
For example, instead of just showing configuration syntax:
```yaml
custom:
esbuild:
sourcemap: true
```
Provide context about when and why:
```yaml
# Enable source maps for better error debugging in transpiled code
custom:
esbuild:
sourcemap: true
```
When documenting commands, explain their purpose and expected outcomes rather than using vague phrases like "follow the prompts." Replace complex, deployment-specific examples with simpler, more universally applicable ones that developers can easily understand and adapt to their needs.
---
## Release note formatting
When updating documentation that is consumed by automated release tooling (such as changelog YAML), verify both the semantic classification and the generated markdown rendering.
Apply a checklist before merge:
- Set the correct change `type` for the user impact (e.g., if behavior changes and can break workflows, prefer `breaking_change` over `bugfix`).
- Write `message` in a release-friendly structure. If the release generator turns `message` into markdown list items, keep the first line as a short sentence and add clear sub-bullets rather than long, unstructured paragraphs.
Example:
```yml
type: breaking_change
message: |
Changed the default value of `nginx_http_client_max_body_size` from `0` (unbounded) to `10m`.
- Requests larger than the new limit may be rejected.
- Update Kong/Nginx settings if you rely on larger request bodies.
```
---
## audit third-party dependencies
{% raw %}
Before using third-party actions, libraries, or dependencies that require access to sensitive data (tokens, secrets, credentials), conduct a thorough security audit. Third-party code, especially when source is obfuscated or built/compiled, poses significant security risks when granted access to sensitive resources.
Key evaluation steps:
1. **Review source code transparency** - Prefer dependencies with clear, readable source code over those with built/compiled distributions
2. **Apply principle of least privilege** - Use tokens with minimal required permissions (e.g., read:org only tokens instead of broader access)
3. **Consider alternatives** - Evaluate copying source code into your own codebase or forking the dependency into your organization's control
4. **Assess maintenance and reputation** - Review the dependency's maintenance status, contributor history, and community trust
Example from GitHub Actions:
```yaml
# Instead of using third-party action with broad token
- uses: third-party/action@v1
with:
GITHUB_TOKEN: ${{ secrets.GH_ACCESS_TOKEN }}
# Consider forking to your org or copying source code
- uses: your-org/forked-action@v1
with:
GITHUB_TOKEN: ${{ secrets.LIMITED_READ_TOKEN }}
```
When in doubt, prioritize security over convenience by maintaining direct control over code that accesses sensitive resources.
{% endraw %}
---
## Eliminate redundant operations
Identify and eliminate repeated expensive operations to improve performance. Look for opportunities to cache results, avoid duplicate computations, and minimize unnecessary work.
Key strategies:
- **Memoize expensive operations**: Cache results of file reads, hash computations, and API responses that are called multiple times
- **Avoid redundant parsing**: Don't parse the same data multiple times; use simple checks like `item.startsWith('[')` before expensive operations like `JSON.parse()`
- **Skip unnecessary operations**: Check if work is actually needed before performing it (e.g., check if ECR repository exists before attempting removal)
- **Use efficient file operations**: Prefer moving files over copying when working with temporary directories
Example of memoization:
```javascript
// Before: Reading package.json multiple times
const packageJson = JSON.parse(fs.readFileSync('package.json'));
// After: Memoize the operation
this._readPackageJson = _.memoize(this._readPackageJson.bind(this));
```
Example of avoiding redundant parsing:
```javascript
// Before: JSON.parse in both filter and map
.filter((item) => item !== '' && Array.isArray(JSON.parse(item)))
.map((item) => JSON.parse(item))
// After: Simple check first, parse once
.filter((item) => item.startsWith('['))
.map((item) => JSON.parse(item))
```
This approach reduces CPU usage, memory allocation, and I/O operations, leading to faster execution times and better resource utilization.
---
## Design intuitive API interfaces
APIs should be designed with user experience in mind, accepting inputs in formats users naturally encounter and providing clear customization options with well-documented defaults.
When designing command-line interfaces or API endpoints:
- Accept natural input formats that users commonly work with (e.g., allowing GitHub URLs to be copied directly from the browser address bar)
- Provide customization options through clear parameter names (e.g., `--env-interface` to specify interface names)
- Always document default behaviors when parameters are omitted
- Use descriptive parameter names that clearly indicate their purpose
Example from CLI design:
```bash
# Good: Accepts natural GitHub URLs and provides clear customization
wrangler create my-app https://github.com/user/repo/tree/main/templates/worker
wrangler types --env-interface MyCustomEnv # defaults to 'Env' if not specified
```
This approach reduces friction for users by eliminating the need to transform inputs into specific formats and provides flexibility while maintaining predictable default behavior.
---
## SQL query best practices
Always include ORDER BY clauses in paginated queries to ensure consistent results across multiple requests. Without explicit ordering, databases may return results in different orders each time, making pagination unreliable and potentially causing data to be skipped or duplicated.
Additionally, use compile-time query verification macros like `query!` instead of `query` to catch SQL errors at build time rather than runtime.
Example of problematic pagination:
```rust
// BAD: No ORDER BY clause
let mut stmt = conn.prepare("SELECT id, address, time, tx_hash FROM requests WHERE tx_hash IS NULL LIMIT ?1 OFFSET ?2")?;
```
Example of proper pagination:
```rust
// GOOD: Explicit ordering ensures consistent pagination
let mut stmt = conn.prepare("SELECT id, address, time, tx_hash FROM requests WHERE tx_hash IS NULL ORDER BY id LIMIT ?1 OFFSET ?2")?;
// BETTER: Use compile-time verification
let requests = sqlx::query!(
"SELECT id, address, time, tx_hash FROM requests WHERE tx_hash IS NULL ORDER BY id LIMIT $1 OFFSET $2",
limit,
offset
).fetch_all(pool).await?;
```
For time-based pagination, consider using cursor-based pagination with timestamps instead of OFFSET to handle concurrent insertions more gracefully.
---
## Optimize database queries
When writing database queries, prioritize both performance and correctness. Avoid unnecessary joins that can significantly impact query performance - fetch only essential data and use separate services or caches for additional lookups. Also ensure your filtering logic doesn't inadvertently exclude valid records, particularly with boundary conditions.
For performance optimization, prefer fetching minimal data:
```typescript
// Instead of expensive joins for display names
newer: v0_transfers(
where: { source_timestamp: { _gt: $timestamp } }
) {
source_chain { chain_id display_name } // Adds expensive joins
}
// Fetch IDs only and use separate service
newer: v0_transfers(
where: { source_timestamp: { _gt: $timestamp } }
) {
source_chain { chain_id } // Minimal data
}
// Then use chainsgate service for display names
```
For correctness, ensure filters cover boundary cases:
```typescript
// Problematic - misses exact timestamp matches
where: { source_timestamp: { _gt: $timestamp } }
where: { source_timestamp: { _lt: $timestamp } }
// Better - includes boundary values
where: { source_timestamp: { _gte: $timestamp } }
where: { source_timestamp: { _lte: $timestamp } }
```
---
## Validate input before submission
Always validate user input before enabling form submission to prevent processing of invalid or malicious data. This includes checking for empty required fields, format validation, and business logic constraints. Implement validation checks in the form's disabled state or submission handler to ensure only valid data can be processed.
Example implementation:
```javascript
// Disable submit button when validation fails
disabled={$faucetState.kind !== "IDLE" || isValidCosmosAddress(address, ['union']) === false}
```
This pattern prevents users from submitting forms with empty addresses, invalid formats, or when the application is in an inappropriate state. Client-side validation improves user experience while server-side validation provides security protection against malicious requests.
---
## explicit observability configuration
Ensure observability features are configured explicitly with clear documentation about their scope and impact. Avoid relying on implicit defaults or ambiguous configuration that could mislead users about what monitoring capabilities are being enabled or disabled.
When documenting observability features, provide explicit YAML configuration examples that clearly show:
- What specific features are being controlled (monitoring, tracing, metrics)
- The scope of impact (service-level vs dashboard-level features)
- Clear examples for different environments/stages
Example of good explicit configuration:
```yaml
stages:
prod:
observability: true # turn on observability in the "prod" Stage.
dev:
observability: true # turn on observability in the "dev" Stage.
default:
observability: false # turn off observability for all other Stages.
```
Avoid suggesting broad configuration changes (like removing `app` property) when the intent is to disable only specific observability features, as this can unintentionally disable other dashboard functionality.
---
## Remove unused code elements
Eliminate unnecessary code elements including unused parameters, struct tags, methods, and dead code to improve code cleanliness and maintainability. Unused code creates confusion for maintainers and adds unnecessary complexity to the codebase.
Key areas to review:
- Remove unused function parameters that serve no purpose
- Delete unnecessary struct tags that aren't used in the current context
- Remove unused methods and functions that have no callers
- Clean up dead code that serves no functional purpose
Example of unused parameter removal:
```go
// Before: req parameter is unused
func (b *BasicLimiter) Allow(ctx context.Context, source string, amount int64, req *http.Request, rw http.ResponseWriter) {
// req is never used, only ctx is needed
}
// After: remove unused parameter
func (b *BasicLimiter) Allow(ctx context.Context, source string, amount int64, rw http.ResponseWriter) {
// cleaner function signature
}
```
Example of unnecessary struct tag removal:
```go
// Before: description tag not needed in dynamic config
type Redis struct {
Endpoints []string `description:"KV store endpoints." json:"endpoints,omitempty"`
}
// After: remove unused description tag
type Redis struct {
Endpoints []string `json:"endpoints,omitempty"`
}
```
Regularly audit code for unused elements during code reviews to maintain a clean, maintainable codebase.
---
## Comprehensive API documentation
Always provide comprehensive API documentation that includes accurate examples, complete parameter descriptions, and clarifications about parameter usage. This helps users understand how to properly use your API and reduces support questions.
1. **Include multiple usage examples** showing different common scenarios:
```python
# Example showing file path operations with proper mode
with open('/tmp/myfile.txt', 'rb') as file:
s3.upload_fileobj(file, 'mybucket', 'mykey')
# Example showing in-memory operations
import io
data = io.BytesIO(b'file content')
s3.upload_fileobj(data, 'mybucket', 'mykey')
```
2. **Document all parameters** with:
- Type information
- Clear description of purpose
- Default values or required status
- Which operation the parameter applies to (for complex methods)
```python
def upload_fileobj(self, Fileobj, Bucket, Key, ExtraArgs=None, Callback=None, Config=None):
"""Upload a file-like object to S3.
:type Fileobj: file-like object
:param Fileobj: A file-like object that implements read()
:type Bucket: str
:param Bucket: The name of the bucket to upload to
:type ExtraArgs: dict
:param ExtraArgs: Extra arguments that will be passed to the underlying
PutObject operation (e.g., {'ACL': 'public-read'})
"""
```
3. **Use correct documentation syntax** for your chosen documentation system:
- In restructuredText, use double backticks (``code``) for inline code
- Use relative links instead of absolute URLs
- Ensure API examples use accurate methods (e.g., distinguish between `boto3.client('s3')` and `boto3.resource('s3')`)
Always test your documentation examples to verify they work as described.
---
## Use relative documentation links
When documenting error handling mechanisms, always use relative path references (`../path/to/file.mdx`) instead of absolute paths (`/docs/path/to/file`) when creating documentation links. This ensures documentation about error handling, assertions, validations, and error recovery patterns remains navigable even when documentation structures change.
For example, change:
```markdown
[custom conditions](/docs/language/expressions/custom-conditions)
```
To use relative paths:
```markdown
[custom conditions](../expressions/custom-conditions.mdx)
```
Properly linked documentation is essential for developers to find and implement appropriate error handling strategies. When documentation links break, developers struggle to locate crucial information about error handling techniques, potentially leading to improper implementation of validation checks, error messaging, and recovery mechanisms.
---
## Secure encryption key backups
Always implement proper encryption key management procedures, including secure backups of encryption keys before enabling encryption features. Without proper key backups, encrypted data can become permanently inaccessible, creating security and operational risks.
When implementing encryption:
- Create and test a disaster recovery plan
- Make temporary backups of unencrypted data before encryption
- Establish secure storage for encryption keys with redundant backups
- Document key rotation schedules and procedures
- Consider using key management systems for sensitive environments
```hcl
# Before enabling encryption in configuration
# 1. Back up your unencrypted state
$ cp terraform.tfstate terraform.tfstate.backup
# 2. Ensure encryption keys are securely backed up
# 3. Then enable encryption in your configuration
terraform {
# Configuration with encryption enabled
state_encryption {
# Your encryption configuration
# ...
}
}
# Remember: Once encryption is enabled, access to data requires the correct key
```
Failure to maintain access to encryption keys can result in permanent data loss, as encrypted data cannot be recovered without the correct key.
---
## Use configuration placeholders
Configuration files should use placeholder values like `` instead of hardcoded values for fields that need to be dynamically replaced by tooling or build processes. This ensures that automated systems can properly substitute the correct values during project setup or deployment.
Hardcoded values prevent tooling from functioning correctly and can lead to inconsistencies between user selections and final configuration. For example, if a user selects the project name "crimson-sky-1234" but the configuration contains a hardcoded name, the final result won't match their choice.
Example of correct placeholder usage:
```toml
name = ""
compatibility_date = ""
```
Instead of:
```toml
name = "hello-python-worker"
compatibility_date = "2024-03-20"
```
This practice allows build tools to automatically look up the latest compatibility dates and apply user-specified names, ensuring configurations remain current and personalized.
---
## Prevent algorithmic pitfalls
Avoid common algorithmic errors that lead to incorrect results or inefficient code by following these practices:
1. **Never modify a collection while iterating over it**
Store results in a separate variable rather than overwriting the collection you're iterating through:
```python
# Incorrect:
response = self.meta.client.list_access_keys(UserName=self.user_name)
for access_key in response['AccessKeyMetadata']:
if access_key['AccessKeyId'] == self.id:
response = access_key # Overwriting the response being iterated!
# Correct:
response = self.meta.client.list_access_keys(UserName=self.user_name)
result = None
for access_key in response['AccessKeyMetadata']:
if access_key['AccessKeyId'] == self.id:
result = access_key
```
2. **Use appropriate data types for calculations**
Cast to float when division requires decimal precision:
```python
# Incorrect (integer division truncates to 0):
percentage = (self._seen_so_far / self._size) * 100 # 123/1024*100 = 0
# Correct:
percentage = (float(self._seen_so_far) / self._size) * 100 # 12.01171875
```
3. **Choose specialized tools over general approaches**
Use dedicated parsers rather than regex for complex parsing tasks:
```python
# Avoid brittle regex approaches with edge cases:
TARGET_COMPONENT_RE = re.compile(r'[^.\[\]]+(?![^\[]*\])')
# Better: Use existing parsers for complex expressions
result = jmespath.compile('foo[].bar[].baz.*.qux')
current = result.parsed
while current['children']:
current = current['children'][0]
field_name = current['value'] # 'foo'
```
4. **Use efficient built-in functions**
Prefer Python's built-in functions like `any()` over creating temporary lists:
```python
# Inefficient (creates a temporary list):
needs_data = [i for i in reference.resource.identifiers if i.source == 'data']
if needs_data:
# do something
# Efficient:
needs_data = any(i.source == 'data' for i in reference.resource.identifiers)
```
5. **Implement robust comparisons**
Compare actual types rather than names, and handle edge cases in comparison algorithms:
```python
# Fragile comparison that could have false positives:
if other.__class__.__name__ != self.__class__.__name__:
# More robust comparison:
if other.__class__ != self.__class__:
```
When implementing comparison algorithms (like version checking), parameterize tests to cover edge cases such as non-standard formats.
---
## Extract and organize methods
Break down large, complex methods into smaller, focused methods with clear names that describe their purpose. This improves code readability, maintainability, and testability.
When methods grow too long or handle multiple concerns:
- Extract separate behaviors into dedicated methods
- Use descriptive method names that explain their purpose
- Avoid duplicating logic across methods
For example, instead of:
```ruby
def wrapper_script
# 50+ lines of complex code with slight variations
if new_resource.use_inline_powershell
# inline powershell version
else
# regular shell out version
end
end
```
Refactor to:
```ruby
def wrapper_script
if new_resource.use_inline_powershell
inline_powershell_wrapper_script
else
shell_out_wrapper_script
end
end
def inline_powershell_wrapper_script
# inline powershell implementation
end
def shell_out_wrapper_script
# regular shell out implementation
end
```
Or when logic is repeated:
```ruby
def resolved_package(pkg)
new_resource.anchor_package_regex ? "^#{pkg}$" : pkg
end
```
This approach reduces cognitive load, improves reusability, and makes code easier to understand and modify.
---
## Organize code logically
Maintain a clean and logical code structure by properly organizing code according to its functionality and purpose:
1. Group related functionality into dedicated packages based on domain logic (e.g., `pkg/ssh` for SSH-related code)
2. Keep static/asset files in separate directories rather than embedding them alongside application code
3. Follow Go's import convention with a single, organized import section that separates standard library and third-party imports
4. Structure complex patterns like multiple callbacks into interfaces and structs for better readability
Example of proper import organization:
```go
// Good: Organized import section
import (
"context"
"crypto/tls"
"fmt"
"github.com/fatedier/frp/models/transport"
)
```
Example of improving complex parameter patterns with structured types:
```go
// Before
func NewVhostMuxer(listener net.Listener, vhostFunc muxFunc, authFunc httpAuthFunc,
successFunc successFunc, rewriteFunc hostRewriteFunc, timeout time.Duration) {
// ...
}
// After
type MuxerOptions struct {
VhostFunc muxFunc
AuthFunc httpAuthFunc
SuccessFunc successFunc
RewriteFunc hostRewriteFunc
Timeout time.Duration
}
func NewVhostMuxer(listener net.Listener, options MuxerOptions) {
// ...
}
```
This organization improves code maintainability, makes navigation easier for developers, and establishes a consistent project structure that scales with codebase growth.
---
## Non-root container users
Always run containers with a non-root user to reduce the security attack surface. Modern Docker allows non-root users to bind to privileged ports (80, 443), eliminating a common reason for using root. Create a dedicated user and group in your Dockerfile and ensure your application runs with that user's privileges.
Example:
```Dockerfile
FROM alpine:3.18 AS runtime
ARG APP
# Create a non-root user and group
RUN addgroup -g 1000 -S ${APP} && \
adduser -u 1000 -S ${APP} -G ${APP} --home /app
# Set the working directory owned by the non-root user
WORKDIR /app
COPY --from=builder /building/bin/${APP} /app/
# Switch to non-root user
USER ${APP}
# Run the application
CMD ["/app/your-application"]
```
---
## Memoize expensive operations
Cache results of expensive operations, especially shell commands and external queries, to avoid redundant executions. Use Ruby's idiomatic memoization pattern with blocks for clarity and efficiency. Only fetch data when needed, and structure code to optimize for the most common execution paths.
For shell commands:
```ruby
def choco_version
@choco_version ||= begin
powershell_exec!("choco --version").result
end
end
```
For conditional resource initialization:
```ruby
def loop_mount_points
# Only fetch when actually needed
@loop_mount_points ||= shell_out!("losetup -a").stdout
end
```
When executing shell commands, use splat arguments instead of string concatenation:
```ruby
# Prefer this (avoids shell parsing overhead):
shell_out!(systemctl_path, args, "show", "-p", "UnitFileState", new_resource.service_name, options)
# Instead of:
shell_out!("#{systemctl_path} #{args} show -p UnitFileState #{new_resource.service_name}", options)
```
For frequently accessed data, consider optimizing for the most common case:
```ruby
# Optimization for the 90% single-package case
target_dirs = []
target_dirs << targets.first.downcase if targets.length == 1
```
Always benchmark critical code paths before and after optimization to verify improvements.
---
## Secure network operations
When performing network operations, prioritize security and configurability to ensure robustness across different environments. This includes:
1. **Use explicit command patterns**: When executing shell commands that involve network operations, avoid string interpolation and use argument arrays instead to prevent command injection vulnerabilities.
```ruby
# Avoid - potential command injection risk
shell_out!("semodule --install '#{selinux_module_filepath('pp')}'")
# Prefer - safer argument passing without shell interpretation
shell_out!("semodule", "--install", selinux_module_filepath('pp'))
```
2. **Make network operations transparent**: When downloading and executing content from the network, clearly document what's happening to avoid confusion and potential security issues.
```ruby
# Unclear - abbreviation hides the operation being performed
powershell_exec("iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))").error!
# Clear - explicitly states what's happening with a clarifying comment
# note that Invoke-Expression is being called on the downloaded script (outer parens)
powershell_exec("Invoke-Expression ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))").error!
```
3. **Use configurable HTTP options**: When making HTTP requests, provide configurable options through a hash instead of individual properties to allow for flexible and extensible client configuration.
```ruby
# Add to your resource
property :http_options, Hash,
description: "Configuration options for the HTTP client"
# Then in your provider
def http_client_opts
defaults = { retries: 5, retry_delay: 2 }
defaults.merge(new_resource.http_options || {})
end
```
These practices ensure network operations are secure against injection attacks, clearly documented for maintainers, and configurable for different network environments.
---
## Keep actions versions current
Always use the latest stable versions of GitHub Actions components in CI/CD workflows to avoid deprecated features, security vulnerabilities, and compatibility issues. This includes:
1. Use the latest version of common actions:
```yaml
# Use this
- uses: actions/checkout@v4
# Instead of these older versions
- uses: actions/checkout@v3
- uses: actions/checkout@v2
```
2. Reference the canonical branch name in external actions:
```yaml
# Use this
- uses: actionshub/chef-install@main
# Instead of
- uses: actionshub/chef-install@master
```
3. Keep runner images updated to currently supported versions:
```yaml
# Use these
runs-on: macos-11 # or newer
runs-on: windows-2022 # instead of windows-2016
# Replace deprecated runners like
# runs-on: macos-10.15
# runs-on: windows-2016
```
Regular updates reduce security risks, ensure compatibility with GitHub's evolving infrastructure, and prevent build failures when older components are deprecated or removed. Create a recurring task to audit and update actions versions across your workflows.
---
## Document configuration completely
Always provide complete documentation for configuration options, including defaults, override methods, and security implications. When documenting configuration:
1. Be explicit about default values and their rationale
2. Provide clear examples showing the correct syntax
3. Specify whether configurations apply locally or globally
4. Document any security considerations
For dependency-related configurations, include the exact commands and their outputs in PR descriptions:
```ruby
# Example for gem installations
gem install [gem_name] --conservative
# Example for configuration attributes
node['audit']['reporter'] = %w{json-file cli}
# Example for local-scoped bundle configurations
bundle config set --local without development
```
When configuration defaults change, especially those with security implications, provide clear migration paths for users who need previous functionality.
---
## No Blanket Vulnerability Ignores
Security scanner ignore files must not use broad “blanket” suppression that can hide future real issues.
**Standard**
- Avoid rules that ignore by coarse attributes (e.g., `fix-state: unknown`) for wide sets of findings.
- Prefer explicit, reviewable exceptions: list the **specific vulnerability IDs** you intend to ignore.
- Add a **short, human explanation per ignored CVE** stating why the finding is not applicable/acceptable for your product and images.
**Example**
```yaml
ignore:
# CVE-2008-4318 is ignored because it affects Python,
# and Kong images do not ship Python at runtime.
- vulnerability: CVE-2008-4318
# CVE-XXXX-YYYY is ignored because ... (document the reason)
- vulnerability: CVE-XXXX-YYYY
```
**If you think you must ignore a “fix-state”**
- Scope it tightly and still anchor it to specific CVEs, and ensure there’s an update plan when the scanner state changes.
**Review checklist**
- Does the ignore rule target specific `vulnerability` IDs?
- Is there a clear comment explaining the exception?
- Could this rule accidentally ignore a new, relevant vulnerability in the future?
---
## maintain IAM role isolation
Each resource should use the IAM role assigned to its associated function rather than sharing roles across different functional boundaries. Sharing roles between different functions or resources can create security vulnerabilities and potential privilege escalation paths.
When configuring resources like scheduled events, always ensure they use the same role as their associated function:
```javascript
// Preferred: Use the function's specific role
const functionLogicalId = this.provider.naming.getLambdaLogicalId(functionName);
const functionResource = resources[functionLogicalId];
roleArn = functionResource.Properties.Role;
// Avoid: Using a shared default role across different functions
roleArn = { 'Fn::GetAtt': ['IamRoleLambdaExecution', 'Arn'] };
```
This approach maintains proper security isolation, prevents unintended cross-function access, and aligns with the principle of least privilege. Many users prefer to have IAM permissions isolated and configured per function to avoid security breaches where one function's resources inadvertently rely on roles dedicated to other functions.
---
## maintain configuration standards
Ensure configuration files maintain both consistency and currency across all services. Configuration values should follow established patterns within the codebase and use up-to-date versions for runtimes and dependencies.
Key practices:
- Apply consistent validation modes across all service configurations (e.g., `configValidationMode: error`)
- Keep runtime versions current and avoid outdated versions
- Review configuration files for both standardization and version currency
Example from serverless.yml:
```yaml
service: my-service
configValidationMode: error # Consistent validation across services
provider:
name: aws
runtime: nodejs16.x # Use current runtime versions, not nodejs12.x
```
This ensures reliable deployments and reduces configuration drift between services while maintaining security and compatibility with current platform features.
---
## Use runServerless utility
All new tests must be written using the `runServerless` utility instead of legacy testing approaches. This utility provides a more reliable way to test functionality by replicating full command runs, ensuring that cross-dependent machinery works as expected in production.
The `runServerless` approach offers several advantages:
- Tests the complete integration rather than isolated components
- Reduces maintenance burden during refactors
- Provides consistent testing patterns across the codebase
- Eliminates the need for complex mocking setups
When writing new tests, use `runServerless` with appropriate fixtures and configuration:
```javascript
it('should handle function configuration correctly', async () => {
const { cfTemplate, awsNaming } = await runServerless({
fixture: 'function',
command: 'package',
configExt: {
functions: {
basic: {
handler: 'index.handler',
memorySize: 512,
},
},
},
});
const functionResource = cfTemplate.Resources[awsNaming.getLambdaLogicalId('basic')];
expect(functionResource.Properties.MemorySize).to.equal(512);
});
```
Do not expand or modify existing legacy tests - they should remain intact or be completely replaced. For test efficiency, consider consolidating multiple test scenarios into a single `runServerless` call when testing related functionality, as these runs are expensive and can prolong test execution time.
---
## Use descriptive semantic names
Variable and function names should clearly communicate their purpose, type, and scope without requiring additional context. Avoid confusing naming patterns and follow established conventions to improve code readability and maintainability.
**Key Guidelines:**
- Avoid underscore prefixes/suffixes (`statement_`, `_areMergeablePolicyStatements`) - they suggest private members or temporary variables
- Don't capitalize variables that aren't constructors (`Effect`, `Action`) - capitalization implies class constructors
- Use descriptive names over abbreviations (`serviceDir` instead of `sDir`, `shouldMinify` instead of `minify`)
- Name booleans as questions (`isConsoleDevMode`, `shouldMinify`, `isInteractiveTerminal`)
- Choose semantically accurate names that reflect data type (`kmsKeyArn` for ARN values, `resolvedPath` vs `entryFileRealPath`)
- Maintain consistency across related concepts (`websocket` not `websockets` to match event names)
**Example:**
```javascript
// Avoid
const statement_ = statements.find(el => ...);
const Effect = statement.Effect; // Looks like constructor
const sDir = fixture.servicePath;
const minify = this.options['minify-template'];
// Prefer
const matchingStatement = statements.find(el => ...);
const effect = statement.Effect; // Clear it's a value
const serviceDir = fixture.servicePath;
const shouldMinify = this.options['minify-template'];
```
Well-chosen names serve as inline documentation, reducing cognitive load and making code self-explanatory to future maintainers.
---
## consistent async/await usage
When refactoring code to use async/await, ensure complete and consistent adoption throughout the function or module. Avoid mixing async/await syntax with .then() chains, as this creates confusing and hard-to-maintain code.
The pattern to avoid:
```javascript
// Bad: mixing async/await with .then()
async function example() {
const result = await someAsyncOperation();
return result.then(data => processData(data));
}
// Bad: using .then() after await
await expect(awsPlugin.monitorStack('update', cfData, { frequency: 10 }))
.to.eventually.be.rejectedWith(ServerlessError, 'An error occurred')
.then(() => {
// additional logic
});
```
The preferred approach:
```javascript
// Good: consistent async/await
async function example() {
const result = await someAsyncOperation();
const processedData = await processData(result);
return processedData;
}
// Good: clean async/await in tests
await expect(awsPlugin.monitorStack('update', cfData, { frequency: 10 }))
.to.eventually.be.rejectedWith(ServerlessError, 'An error occurred');
// additional logic follows naturally
```
When refactoring legacy promise-based code, complete the migration in dedicated commits or PRs before adding new functionality. This prevents the codebase from having inconsistent async patterns that are difficult to understand and debug.
---
## Explicit verified configurations
Always specify configuration values explicitly and verify their accuracy against official documentation or tests. This applies to region configurations, API settings, and credential management. Avoid mutations of global configuration objects, and instead set values explicitly when defined by service APIs.
Example:
```json
// GOOD: Explicitly verified region configuration
"us-iso-*/iam": {
"endpoint": "{service}.us-iso-east-1.c2s.ic.gov",
"globalEndpoint": true,
"signingRegion": "us-iso-east-1" // Verified against Endpoints 2.0 tests
}
// BAD: Incorrect or unverified configuration
"us-iso-*/iam": {
"endpoint": "{service}.us-iso-east-1.c2s.ic.gov",
"globalEndpoint": true,
"signingRegion": "us-east-1" // Incorrect region
}
```
For credential configurations, always use resolved credentials when available rather than relying on automatic refresh mechanisms that may cause performance issues.
---
## Least privilege for tokens
{% raw %}
Always apply the principle of least privilege when configuring access tokens for CI/CD workflows and other automated processes. Use fine-grained tokens or permissions that grant only the minimum necessary access required for the specific operations.
For example, if a GitHub workflow only needs to trigger actions in a specific repository, limit the token's scope to just that repository and only the "Actions (Read and write)" permission:
```yaml
# Example GitHub workflow using fine-grained token
- name: Setup workflow
uses: hashicorp/action-setup-bob@v1
with:
github-token: ${{ secrets.LIMITED_SCOPE_TOKEN }}
# Token configured with:
# - Access to only this specific repository
# - Only Actions (Read and write) permission
# - No other permissions granted
```
This reduces the security risk if tokens are ever compromised by limiting the potential impact of a security breach. When using service accounts or tokens in any context, document the exact permissions granted and regularly audit them to ensure they remain appropriate.
{% endraw %}
---
## Structure configs for clarity
Organize configuration objects to maximize clarity and maintainability while ensuring robust validation. Follow these principles:
1. Use single object definitions instead of multiple configurations to enable specific error messages
2. Include sensible defaults and clear fallback behavior
3. Validate at schema level when possible, but move complex validations to code level
4. Ensure error messages clearly indicate the misconfigured property
Example of good configuration structure:
```javascript
// Instead of multiple object configurations:
{
oneOf: [
{ type: 'string' },
{ type: 'object',
properties: { ... }
}
]
}
// Use single object with clear validation:
{
type: 'object',
properties: {
type: { type: 'string' },
arn: { type: 'string' }
}
}
// Then validate complex rules in code:
if (config.arn && !isValidArn(config.arn)) {
throw new Error('Invalid ARN format provided');
}
```
This approach ensures configurations are easy to understand, maintain, and debug while providing clear feedback when issues arise.
---
## prefer simple readable patterns
Choose simple, readable code patterns over complex alternatives. Avoid unnecessary complexity that doesn't add functional value but makes code harder to understand and maintain.
Key principles:
- Use async/await instead of Promise chains for better readability
- Choose appropriate array methods (use `some()` for boolean checks, not `find()`)
- Avoid overusing `reduce()` when simple iteration is clearer
- Remove commented code and eslint-disable comments
- Return directly instead of wrapping in `Promise.resolve()`
- Avoid stylistic changes that don't improve functionality
Examples:
```javascript
// Prefer this (simple async/await)
try {
await fs.promises.access(join(workingDir, input));
return `Path ${input} is already taken`;
} catch {
return true;
}
// Over this (Promise chains)
fs.promises.access(join(workingDir, input))
.then(() => `Path ${input} is already taken`)
.catch(() => true)
// Prefer this (appropriate method choice)
if (!Object.keys(resources).some(key =>
resources[key].Type === 'AWS::Lambda::LayerVersion'
)) {
// handle case
}
// Over this (wrong method for boolean check)
if (!Object.keys(resources).find(key =>
resources[key].Type === 'AWS::Lambda::LayerVersion'
)) {
// handle case
}
// Prefer this (simple iteration)
const result = [];
for (const param of params) result.push(...param);
return { value: result };
// Over this (unnecessary reduce complexity)
return params.reduce((acc, item) => {
acc.push(...item);
return acc;
}, []);
```
This approach improves code maintainability, reduces cognitive load, and makes the codebase more accessible to all team members.
---
## API clarity and consistency
Ensure API configurations, documentation, and terminology are clear, consistent, and properly organized. Group related API properties together logically, use precise terminology that matches the underlying service (e.g., distinguish "HTTP API" from "REST API"), and maintain consistent naming conventions throughout.
When organizing API configurations, group related properties under logical sections and order them by usage frequency to improve discoverability. Use naming conventions that align with the underlying service's terminology.
Example of good API configuration organization:
```yml
provider:
apiGateway:
# More commonly used, placed first
restApiId: existing-api-id
websockets:
# Grouped together logically
apiName: custom-websockets-api-name
apiRouteSelectionExpression: $request.body.route
description: Custom Serverless Websockets
```
In documentation, use precise API terminology and provide clear context for examples. Avoid generic terms when specific ones exist, and ensure examples include sufficient context to understand their purpose and application.
---
## configuration examples accuracy
Ensure configuration examples and documentation use current, supported syntax and accurately reflect the actual behavior of the system. Avoid promoting deprecated features, outdated versions, or configuration options that have no effect.
Key practices:
- Use current runtime versions in examples (e.g., `nodejs18.x`, `python3.9`) instead of outdated ones (`nodejs6.x`, `python2.7`)
- Promote current syntax over deprecated alternatives (e.g., `iam.role.statements` instead of `iamRoleStatements`)
- Remove configuration examples that have no actual effect on the system
- Verify that statements about required vs optional configuration are accurate
- Use proper semantic version constraints that don't inadvertently allow incompatible future versions
Example of good practice:
```yaml
# Good: Uses current syntax and supported versions
provider:
name: aws
runtime: nodejs18.x
iam:
role:
statements:
- Effect: Allow
Action: 's3:GetObject'
Resource: '*'
# Bad: Uses deprecated syntax and outdated versions
provider:
name: aws
runtime: nodejs6.x
iamRoleStatements:
- Effect: Allow
Action: 's3:GetObject'
Resource: '*'
```
This prevents developers from copying ineffective or outdated configuration patterns that may cause deployment issues or use deprecated features.
---
## Remove commented code
Avoid leaving commented-out code in the codebase. Version control systems already track the history of changes, making commented-out code unnecessary. Removing unused commented code improves readability, reduces confusion, and keeps the codebase clean.
Example of code to avoid:
```yaml
builder-to-testers-map:
ubuntu-20.04-x86_64:
- ubuntu-16.04-x86_64
- ubuntu-18.04-x86_64
- ubuntu-20.04-x86_64
# windows-2012r2-i386:
# - windows-2012r2-i386
```
Instead, simply remove the commented lines completely. If the code needs to be referenced later, it can be found in the commit history.
---
## Defensive null checking
Always perform explicit null/undefined checks before accessing properties or using values that could be null or undefined. Use strict equality checks rather than relying on JavaScript's truthy/falsy evaluation which can lead to subtle bugs.
Common patterns to adopt:
1. Check objects before accessing their properties:
```javascript
// Bad:
if (error.code === 'AuthorizationHeaderMalformed') { /* ... */ }
// Good:
if (error && error.code === 'AuthorizationHeaderMalformed') { /* ... */ }
```
2. Be careful with array index checks:
```javascript
// Bad - indexOf returns 0 for first item which is falsy:
if (list.indexOf(member)) { return true; }
// Good:
if (list.indexOf(member) >= 0) { return true; }
```
3. Use typeof checks before accessing browser/environment-specific objects:
```javascript
// Bad:
return window.localStorage !== null;
// Good:
return AWS.util.isBrowser() && window.localStorage !== null && typeof window.localStorage === 'object';
```
4. Provide defaults for parameters that could be undefined:
```javascript
// Bad:
function handleParams(params) {
params.property = 'value'; // Fails if params is null/undefined
}
// Good:
function handleParams(params) {
params = params || {};
params.property = 'value';
}
```
5. Use type checks for numeric values instead of truthy checks:
```javascript
// Bad - fails for zero values:
if (params.$waiter.delay) {
this.config.delay = params.$waiter.delay;
}
// Good:
if (typeof params.$waiter.delay === 'number') {
this.config.delay = params.$waiter.delay;
}
```
Consistent null checking prevents the most common class of runtime errors and produces more predictable code.
---
## use loose equality checks
Use loose equality (`== null`) instead of strict equality (`=== null` or `=== undefined`) when checking for both null and undefined values. In most JavaScript contexts, null and undefined should be treated equivalently, and loose equality provides a more concise and readable way to handle both cases.
This pattern is particularly useful for:
- Environment variable checks
- Optional configuration properties
- Function parameters with default values
- Property existence validation
Example:
```javascript
// Instead of this:
if (typeof process.env[address] === 'undefined') missingEnvVariables.add(address);
if (startingPosition === 'AT_TIMESTAMP' && !(startingPositionTimestamp !== undefined && startingPositionTimestamp !== null)) {
// Use this:
if (process.env[address] == null) missingEnvVariables.add(address);
if (startingPosition === 'AT_TIMESTAMP' && startingPositionTimestamp == null) {
```
The loose equality check (`== null`) catches both `null` and `undefined` values in a single, readable condition, making code more maintainable and following JavaScript's conventional approach to null safety.
---
## Follow naming conventions
Use consistent and appropriate naming conventions based on the context in Python code:
1. **Classes**: Use `CamelCase` for class names
```python
class ResourceMeta(object):
# Class implementation
```
2. **Variables and methods**: Use `snake_case` for variables, functions, and methods
```python
self._resource_sub_path = self._resource_name.lower()
```
3. **Constants**: Use `UPPER_CASE` for constants
```python
STRING = 'S'
NUMBER = 'N'
```
4. **Private members**: Use leading underscore for internal/private attributes and methods, but avoid redundant underscores when scope already provides privacy
```python
# Good - private method
def _method_returns_resource_list(resource):
# Implementation
# Avoid unnecessary underscores for local variables
def setUp(self):
patch_global_session = mock.patch('boto3.DEFAULT_SESSION') # No leading underscore needed
```
5. **File naming**: Follow established patterns for file naming
```python
# For test files, use test_.py
test_table.py # Not test_batch_write.py if testing the table module
```
6. **Acronyms**: Properly capitalize acronyms in names
```python
class TestIAMAccessKey(unittest.TestCase): # Not TestiamAccessKey
```
7. **References and paths**: Use snake_case for references and lowercase-hyphenated for URL paths
```python
# For references
ref.name = 'frob' # Not 'Frob'
# For URL paths
self._resource_sub_path = 'service-resource' # Not 'ServiceResource'
```
8. **Type mappings**: Use appropriate Python type names
```python
# Map external types to Python types
'double': 'float',
'character': 'string',
'long': 'integer'
```
Consistent naming makes code more readable, maintainable, and reduces cognitive load for developers working with the codebase.
---
## Validate with sensible defaults
Implement a comprehensive configuration validation strategy that combines centralized validation functions with appropriate default values and user-friendly messaging. Instead of failing with errors on non-critical configuration issues, provide warnings and continue with sensible defaults.
**Key practices:**
1. Move configuration validation to dedicated check functions (like `CheckForCli` and `CheckForSvr`)
2. Provide sensible defaults for optional configuration values rather than requiring them all
3. Use warnings instead of errors for non-critical configuration issues
4. Centralize validation logic to support multiple configuration formats
**Example:**
```go
// Bad practice - returning error for non-critical configuration issue
if cfg.TLSEnable == false && cfg.TLSCertFile != "" {
return fmt.Errorf("Parse conf error: forbidden tls_cert_file, it only works when tls_enabled is true")
}
// Good practice - providing warning for non-critical configuration issue
if cfg.TLSEnable == false {
if cfg.TLSCertFile != "" {
fmt.Println("WARNING! tls_cert_file is invalid when tls_enable is false")
}
}
// Bad practice - requiring all configuration values
proxyClient.LocalIp, ok = section["local_ip"]
if !ok {
return fmt.Errorf("Parse ini file error: proxy [%s] no local_ip found", proxyClient.Name)
}
// Good practice - providing sensible default
if localIP, ok := section["local_ip"]; ok {
proxyClient.LocalIp = localIP
} else {
proxyClient.LocalIp = "127.0.0.1" // Sensible default
}
```
This approach improves user experience by allowing applications to start with reasonable defaults while clearly communicating configuration issues. It also facilitates future changes by centralizing validation logic rather than scattering it throughout the codebase.
---
## Fail fast principle
Design CI/CD pipelines to fail quickly and visibly rather than masking errors through excessive retries or complex conditions. When a build step fails, it should fail immediately with clear error reporting to reduce debugging time and enable faster remediation.
Instead of implementing multiple retry attempts that delay the inevitable failure, prefer a minimal retry strategy or a single attempt with good error logging. This approach reduces build time and exposes problems sooner, allowing developers to address issues more efficiently.
For example, replace code like this:
```
$install_attempt = 0
do {
Start-Sleep -Seconds 5
$install_attempt++
Write-BuildLine "Install attempt $install_attempt"
bundle exec rake install:local --trace=stdout
} while ((-not $?) -and ($install_attempt -lt 5))
```
With a simpler approach:
```
bundle exec rake install --trace=stdout
```
Similarly, when configuring pipeline conditions, use concise regex patterns that are easy to understand and maintain rather than complex, hard-to-read conditions that might hide logic errors.
---
## Structure CI/CD scripts
Improve CI/CD shell scripts' readability and maintainability by using appropriate shell script patterns. Use heredocs for multiline output generation (especially for YAML configurations) and extract repetitive operations into functions. This approach reduces duplication, makes scripts easier to understand, and simplifies future updates.
Example 1 - Using heredocs for multiline output:
```bash
# Instead of multiple echo statements:
echo "- label: \":hammer_and_wrench::docker: $platform\""
echo " retry:"
echo " automatic:"
# ...many more echo statements...
# Use heredoc syntax:
cat <<- YAML_CONFIG
- label: ":hammer_and_wrench::docker: $platform"
retry:
automatic:
limit: 1
key: build-$platform
# ...rest of configuration...
YAML_CONFIG
```
Example 2 - Extracting repetitive operations into functions:
```bash
# Instead of repeating similar commands:
docker manifest create "chef/chef:${CHANNEL}" \
--amend "chef/chef:${VERSION}-amd64" \
--amend "chef/chef:${VERSION}-arm64"
docker manifest push "chef/chef:${CHANNEL}"
# Extract into a reusable function:
function create_and_push_manifest() {
echo "--- Creating manifest for $2"
docker manifest create "$1:$2" \
--amend "$1:${EXPEDITOR_VERSION}-amd64" \
--amend "$1:${EXPEDITOR_VERSION}-arm64"
echo "--- Pushing manifest for $2"
docker manifest push "$1:$2"
}
# Then call it multiple times:
create_and_push_manifest "chef/chef" "${EXPEDITOR_TARGET_CHANNEL}"
```
---
## Verify automated documentation
When using automated tools to generate documentation, always verify the output for accuracy and document any additional manual steps required for completion. Automated documentation can inherit incorrect properties or miss crucial steps in the process.
For example:
- When running tools like `rake docs_site:resources` that generate resource documentation automatically, review the output to ensure resources that inherit from parent resources don't contain properties or actions that don't apply to them.
- When using scripts like `publish-release-notes.sh` that push content to repositories, document the complete process including any subsequent manual steps (like triggering Netlify rebuilds) required for the documentation to become visible to users.
Document both the automation commands and their limitations to ensure team members understand the complete documentation workflow. This prevents confusion and ensures accurate, complete documentation reaches the end users.
---
## Semantic naming conventions
Use descriptive, semantic names for all code elements that clearly indicate their purpose and behavior. Follow consistent casing patterns throughout the codebase:
- camelCase for variables, properties, and method names (e.g., 'useDualstack', 'bucketExists')
- PascalCase for class names and type definitions
- When naming functions, prefer names that describe what the function does rather than implementation details (e.g., 'buildMessage' is clearer than 'formatMessage')
- Avoid abbreviations that aren't widely understood (e.g., use 'optionalDiscoveryEndpoint' instead of 'optionalDisverEndpoint')
- When type names conflict with JavaScript primitives, use a prefix (e.g., '_Date') rather than skipping the type definition entirely to prevent runtime errors
```javascript
// Poor naming
function getServiceClock() {
return new Date(Date.now() + this.config.systemClockOffset);
}
// Better naming
function getSkewCorrectedDate() {
return new Date(Date.now() + this.config.systemClockOffset);
}
// Poor type handling - skipping shapes that match JavaScript primitives
if (['string', 'boolean', 'number', 'Date', 'Blob'].indexOf(shapeKey) >= 0) {
return '';
}
// Better type handling - using prefix to preserve shape names
if (['string', 'boolean', 'number', 'Date', 'Blob'].indexOf(shapeKey) >= 0) {
code += 'export type _' + shapeKey + ' = ' + getTypeMapping(shape.type) + ';\n';
return code;
}
```
---
## Clear abstraction boundaries
Design APIs with clear and consistent abstraction boundaries to maintain code quality and prevent interface leakage between different system layers.
Key principles:
1. **Separate CLI and API interfaces**: CLI tools should not return API-style responses, and API endpoints should not handle CLI-specific concerns.
```ruby
# Incorrect - CLI tool returning HTTP-like response
{ "status" => 200, "message" => "Success" } if @calling_request != "CLI"
# Better approach - wrap the functionality with appropriate interfaces
def perform_upload
# Upload functionality here
return true # Simple boolean for CLI
end
def api_upload
perform_upload
{ "status" => 200, "message" => "Success" } # HTTP-style response for API
end
```
2. **Use proper method signatures**: Prefer explicit keyword arguments over option hashes for better readability, documentation, and forward compatibility.
```ruby
# Avoid this pattern - hard to document, using a generic options hash
def powershell_exec(script, options = {})
timeout = options.fetch(:timeout, nil)
# ...
end
# Better pattern - explicit keyword arguments with defaults
def powershell_exec(script, interpreter: :powershell, timeout: nil)
# Implementation...
end
```
3. **Place functionality at the appropriate abstraction level**: Methods and properties should exist at the level where they are most logically connected.
```ruby
# Avoid adding HTTP-specific error handling in generic resources
class Resource
# This doesn't belong here - too specific
private
def http_request_errors
source.map do |msg|
uri = URI.parse(msg)
"Error connecting to #{msg} - Failed to open TCP connection to #{uri.host}:#{uri.port}"
end
end
end
# Better: Place in the specific resource that needs it
class RemoteFileResource < Resource
private
def http_request_errors
# Implementation...
end
end
```
Following these principles creates more maintainable, testable, and adaptable code by ensuring that each component has a clear, focused responsibility.
---
## maintain proper formatting
Ensure code and configuration files follow proper formatting standards that maintain both syntactic validity and visual readability. This includes correct indentation for nested structures and appropriate line length management to prevent horizontal scrolling.
For nested structures like YAML, maintain consistent indentation for all properties at the same level:
```yaml
# Correct - all properties properly indented
events:
- serviceBus:
name: item
queueName: myqueue
connection: myconnection
# Incorrect - inconsistent indentation
events:
- serviceBus:
name: item # Wrong indentation level
queueName: myqueue
```
For long commands or statements, use line continuation to improve readability:
```sh
# Good - broken into readable lines
$ serverless create \
-u https://github.com/serverless/examples/tree/master/folder-name \
-n my-project
# Avoid - causes horizontal scrolling
$ serverless create -u https://github.com/serverless/examples/tree/master/folder-name -n my-project
```
Always validate formatting using appropriate tools (YAML validators, linters) to ensure syntactic correctness alongside visual clarity.
---
## maintain naming consistency
Ensure consistent naming patterns across related components and configurations. When naming properties, methods, or identifiers that relate to the same concept, use the same form (singular/plural, casing, terminology) throughout the codebase.
This prevents confusion and maintains predictability for developers working with related features. Inconsistent naming can lead to errors and makes the API harder to learn and use.
Example of inconsistent naming to avoid:
```yaml
# Inconsistent - mixing singular and plural forms
provider:
websockets: # plural form
useProviderTags: true
functions:
handler:
events:
- websocket: # singular form (event name)
```
Correct approach:
```yaml
# Consistent - using singular form throughout
provider:
websocket: # matches the event name
useProviderTags: true
functions:
handler:
events:
- websocket: # singular form (event name)
```
Always check that related components use consistent naming conventions, especially when they reference the same underlying concept or feature.
---
## standardize log output methods
Use `process.stdout.write` instead of `console.log` for controlled logging output to avoid linter issues and ensure consistent behavior. When using `process.stdout.write`, manually add newlines since they are not automatically appended like with `console.log`. Maintain consistent log message formatting with proper prefixes and structured layout.
Example:
```javascript
// Instead of:
function consoleLog(...args) {
console.log(...args); // eslint-disable-line no-console
}
// Use:
function writeDeprecation(code, message) {
process.stdout.write(
[
`Serverless: ${chalk.red(`Deprecation Warning: ${message}`)}`,
` ${chalk.dim(
`More Info: https://www.serverless.com/framework/docs/deprecations/#${code}`
)}`,
].join('\n') + '\n' // Note the explicit newline at the end
);
}
```
This approach provides better control over output formatting, avoids linter warnings about console usage, and ensures consistent message structure across the application. Always handle edge cases like undefined values in log formatting and maintain proper spacing and alignment in multi-line log messages.
---
## Connection lifecycle management
Implement comprehensive lifecycle management for network connections. Ensure proper initialization, authentication, monitoring, and termination of connections to maintain system reliability and performance.
1. Configure appropriate timeout values based on network conditions and application requirements
```go
// Document timeout values with comments explaining their purpose
conn.SetReadDeadline(time.Now().Add(60 * time.Second)) // Add explanation for timeout to aid maintainability
```
2. Implement graceful connection termination, especially for protocols with specific shutdown requirements
```go
// Add dedicated methods for graceful termination when needed
func (ctl *Control) GracefulClose(gracefulTime time.Duration) {
// Protocol-specific graceful shutdown logic
}
```
3. Properly authenticate network connections and handle authentication failures with appropriate responses
```go
// Verify authentication and respond with clear error messages
if err := svr.authVerifier.VerifyNewWorkConn(newMsg); err != nil {
// Send authentication failure response before closing
errResp := &msg.NewWorkConnResp{Error: err.Error()}
msg.WriteMsg(workConn, errResp)
workConn.Close()
return
}
```
4. Optimize connection-related data transfers for bandwidth-sensitive environments by removing unnecessary metadata
```go
// Only include required data in frequent messages like heartbeats
pingMsg := &msg.Ping{}
if authenticateHeartbeats {
pingMsg.Timestamp = time.Now().Unix()
}
```
---
## Manage test environments
When writing tests that interact with environment variables or configuration settings, always (1) preserve the original state and (2) explicitly specify required configurations.
For environment variables, use setUp/tearDown methods to save and restore their state after test execution:
```python
def restore_dict(self, dictionary: dict, original_data: dict):
dictionary.clear()
dictionary.update(original_data)
def setUp(self):
# Save original environment to restore after test
original_env = os.environ.copy()
self.addCleanup(lambda: self.restore_dict(os.environ, original_env))
```
For service configurations, always explicitly specify required parameters like region rather than relying on the machine's environment:
```python
self.session = boto3.session.Session(region_name='us-west-2')
```
This practice ensures tests are isolated, repeatable, and portable across different development environments, preventing unexpected test failures and interference between test cases.
---
## Follow flake8 style guidelines
Adhere to the project's established flake8 style guidelines as defined in setup.cfg. This includes:
1. Maintain line length limits of 80 characters for consistency and readability across all files.
2. Use proper vertical spacing in Python code, with two blank lines between top-level elements (classes and functions) to satisfy E302 requirements.
```python
# Incorrect - exceeds 80 character line limit
def some_function(parameter1, parameter2, parameter3, parameter4, parameter5, parameter6, very_long_parameter):
return True
# Incorrect - missing blank lines between top-level elements
import boto3
def example_function():
pass
class ExampleClass:
pass
# Correct formatting
import boto3
def example_function():
pass
class ExampleClass:
pass
```
Remember that these style checks are enforced both in local development and by the CI "Lint" workflow. Following these conventions consistently improves code readability and prevents CI failures.
---
## API schema validation accuracy
Ensure that JSON schema validation for API configurations precisely matches the actual service requirements and constraints. Schema validation should use correct JSON schema properties and accurately reflect documented API limits.
Common issues to avoid:
- Using wrong validation properties (e.g., `minLength`/`maxLength` for integers instead of `minimum`/`maximum`)
- Overly restrictive patterns that don't match service capabilities (e.g., JSON pattern allowing only objects when arrays/strings are valid)
- Incorrect constraint values that don't match service documentation (e.g., wrong maximum batch sizes)
- Schema that allows invalid configurations (e.g., array validation that permits partial matches)
Example of correct validation:
```javascript
// Correct: Use proper integer constraints
maximumRetryAttempts: {
type: 'integer',
minimum: 0,
maximum: 185,
}
// Correct: Use enum for exact array matches
AllowedMethods: {
enum: [['GET', 'HEAD'], ['GET', 'HEAD', 'OPTIONS'], ['GET', 'HEAD', 'OPTIONS', 'PUT', 'PATCH', 'POST', 'DELETE']]
}
// Correct: JSON pattern that matches service capabilities
const jsonPattern = '^\\{.*\\}$'; // Only if service truly requires objects
```
Always verify schema constraints against official service documentation and test edge cases to ensure validation accuracy matches real API behavior.
---
## Log message quality
Ensure all log messages are consistent in formatting and clear in purpose. Complete sentences in logs should end with proper punctuation (especially periods), and messages should precisely describe what is happening in the system. When logging phase transitions or significant events, explicitly state where one phase ends and another begins rather than using vague descriptions.
Example:
```ruby
# Poor logging
logger.info("Processing data")
logger.info("Infra Phase and Compliance Phase improved")
# Better logging
logger.info("Processing data.")
logger.info("Transitioning from Infra Phase to Compliance Phase.")
```
This standard improves log readability during troubleshooting and ensures documentation accurately reflects system behavior.
---
## Update security-critical dependencies
Regularly audit and update third-party libraries and dependencies to address known security vulnerabilities. Pay special attention to components that handle sensitive operations such as file system access, encryption, or network communication. Implement a systematic process to monitor CVEs and security bulletins relevant to your dependencies, and document all security-related updates in release notes with specific vulnerability references.
Example:
```ruby
# In your dependency management file (e.g., Gemfile, package.json, requirements.txt)
# GOOD: Specify minimum secure versions with comments explaining security implications
gem 'libarchive', '>= 3.5.2' # Addresses symbolic link handling vulnerabilities
gem 'openssl', '>= 1.1.1l' # Resolves CVE-2021-3711 and CVE-2021-3712
# BETTER: Include automated security scanning in your CI pipeline
# Example GitHub Actions workflow snippet:
- name: Security scan dependencies
uses: some-security-scanner-action@v1
with:
scan-type: 'dependency'
fail-on: 'high'
```
When updating dependencies for security reasons, always include clear documentation in your release notes that specifies:
1. Which dependency was updated
2. The version change (from/to)
3. What security vulnerability was addressed
4. Any potential impact on existing functionality
---
## Use strict test doubles
Always use strict test doubles (instance_double, class_double) instead of basic doubles or OpenStruct in tests. Strict doubles provide compile-time checks that prevent tests from passing when the mocked interface changes, improving test maintainability and catching integration issues early.
Example - Instead of:
```ruby
auth_stub = double("vault auth", aws_iam: nil)
dummy = OpenStruct.new(stdout: output, exitstatus: 0)
```
Use:
```ruby
auth_stub = instance_double("VaultAuth", aws_iam: nil)
shell_out = instance_double(Mixlib::ShellOut,
stdout: output,
exitstatus: 0,
error?: false
)
```
This approach:
- Ensures mocks accurately reflect the real interfaces
- Catches interface changes during test execution
- Makes dependencies explicit in test code
- Prevents tests from silently passing with invalid assumptions
---
## Isolate concurrent resources
Create separate instances of non-thread-safe resources for each thread or process in concurrent applications rather than sharing a single instance. Many objects that maintain state or shared metadata (like sessions, connections, or context-dependent resources) are not thread-safe and can cause race conditions or unpredictable behavior when accessed concurrently.
For example, when using a library with both thread-safe and non-thread-safe components:
```python
import threading
import boto3.session
class MyTask(threading.Thread):
def run(self):
# Create a new session per thread
session = boto3.session.Session()
# Create resource using thread's session
s3 = session.resource('s3')
# Put your thread-safe code here
# ...
# Create and start multiple threads
threads = [MyTask() for _ in range(5)]
for thread in threads:
thread.start()
```
For thread-safe components (like certain clients), you may create them once and share across threads, but be aware of limitations:
1. Check documentation to confirm thread safety guarantees
2. Be cautious with any metadata attributes which may not be thread-safe to modify
3. Avoid sharing any objects across processes even if they're thread-safe
4. Consider potential performance impacts of excessive object creation
---
## Configure proxies with schemes
When configuring proxies in AWS SDK clients, always include the complete URL scheme in proxy definitions. Match the scheme to the protocol: use 'http://' for HTTP connections and 'https://' for HTTPS connections. Missing or incorrect schemes can lead to connection failures or security issues.
For example, when setting up proxies with the Config object:
```python
import boto3
from botocore.config import Config
# Correct way to define proxies with proper schemes
proxy_definitions = {
'http': 'http://proxy.company.com:6502', # HTTP scheme for HTTP proxy
'https': 'https://proxy.company.com:2010' # HTTPS scheme for HTTPS proxy
}
my_config = Config(
region_name='us-east-2',
proxies=proxy_definitions
)
client = boto3.client('s3', config=my_config)
```
Remember that TLS negotiation only occurs with HTTPS connections, so when configuring proxy_ca_bundle or proxy_client_cert in proxies_config, ensure you're using HTTPS proxies. Otherwise, your certificate configuration will have no effect.
---
## Consistent naming standards
Follow standard Python naming conventions consistently throughout code and documentation. Use underscores instead of hyphens in variable and parameter names (e.g., `proxies_config` not `proxies-config`). Maintain consistent capitalization of technical terms across all documentation. When working with file paths in code examples, use platform-agnostic formats that work across all operating systems:
```python
# Good
filename = 'file.txt'
# Avoid (Windows-specific)
filename = 'C:\file.txt'
```
This consistency improves code readability, ensures cross-platform compatibility, and helps maintain a professional, unified appearance across the codebase and documentation.
---
## Document APIs completely
Always provide complete, clear, and contextually rich documentation for all public APIs. Documentation should:
1. Use proper grammar and clear wording
2. Specify environment requirements and version constraints where applicable
3. Be present for all publicly exposed functions, methods, and properties
**Example:**
```typescript
/**
* Custom DNS lookup function.
* Defaults to dns.lookup.
* Used in Node.js (>= v12.x) environment only.
*/
lookupFunction?: LookupFunction;
/**
* Whether to enable endpoint discovery for operations that allow
* optionally using an endpoint returned by the service.
*/
endpointDiscovery?: boolean;
```
Thorough documentation helps other developers understand how to use your code correctly and identify potential limitations or requirements.
---
## Document code decisions
Always include clear documentation for important code decisions and metadata. This includes preserving copyright notices and explaining the reasoning behind specific values and constants.
For copyright notices:
- Maintain all original copyright information
- Add new copyright notices on separate lines, never replacing existing ones
For code constants and values:
- Replace hard-coded "magic numbers" with named constants
- Add comments explaining the reasoning behind specific values, especially for timeouts, limits, and other non-obvious choices
Example:
```go
// Original hard-coded value
svr.rc.VhostTcpMuxer, err = vhost.NewTcpHttpTunnelMuxer(l, 30*time.Second)
// Improved version with named constant and explanation
// DefaultTunnelTimeout defines how long to wait before closing inactive connections
// 30 seconds was chosen based on average connection usage patterns
const DefaultTunnelTimeout = 30 * time.Second
svr.rc.VhostTcpMuxer, err = vhost.NewTcpHttpTunnelMuxer(l, DefaultTunnelTimeout)
```
---
## Follow Go naming conventions
Adhere to Go's standard naming conventions for identifiers:
1. **Control visibility with capitalization**:
- Use uppercase first letter for exported (public) identifiers
- Use lowercase first letter for unexported (package-private) identifiers
- Only export what needs to be used outside the package
2. **Capitalize acronyms properly**:
- Write acronyms in all caps (e.g., `HTTP`, `TCP`, `TLS`, not `Http`, `Tcp`, `Tls`)
- Apply this to all identifiers (variables, functions, types, etc.)
Example of improper naming:
```go
type TcpHttpTunnelProxy struct {
// ...
}
var ResponseHeaderTimeout int64
var TlsVerify bool
type BaseAuth struct {
// Not needed outside package
}
```
Example of proper naming:
```go
type TCPHTTPTunnelProxy struct {
// ...
}
var responseHeaderTimeout int64
var TLSVerify bool
type baseAuth struct {
// Not exported as it's only used within the package
}
```
Following these conventions improves code readability, maintains consistency with standard Go code, and makes the public API of your package more obvious.
---
## Accurate type signatures
When defining API interfaces in TypeScript, ensure that method signatures accurately reflect the actual behavior and requirements of the implementation. Pay special attention to:
1. Parameter optionality: Consider carefully whether parameters should be optional (`param?:`) or required based on their usage patterns. If a callback is expected to be called in most use cases, it might be better to make it required to guide developers toward correct usage.
2. Promise return types: Methods that return promises must specify the correct type of the resolved value. Never use `Promise` when the promise actually resolves to a useful value.
Example of correcting return type:
```typescript
// Incorrect
getSignedUrlPromise(operation: string, params: any): Promise;
// Correct
getSignedUrlPromise(operation: string, params: any): Promise;
```
Example of parameter optionality consideration:
```typescript
// With optional callback - allows but doesn't enforce callback usage
on(event: "validate", listener: (request: Request, doneCallback?: () => void) => void): Request;
// With required callback - enforces callback usage for correct implementation
on(event: "validate", listener: (request: Request, doneCallback: () => void) => void): Request;
```
Accurate type signatures improve API usability, enable better IDE support, and reduce runtime errors by catching incorrect usage patterns at compile time.
---
## Content integrity verification
When handling HTTP responses, especially with streaming data, properly verify content integrity and length to prevent data corruption or unexpected termination. Key considerations:
1. **Content-Length may not match actual data size** when responses use compression (gzip, br, deflate). In such cases:
- Check for Content-Encoding header to determine if response is compressed
- Use actual byte counts rather than Content-Length for progress tracking
- Consider sending Accept-Encoding: identity for critical operations requiring precise progress tracking
2. **Implement proper stream handling** based on environment:
- For Node.js, use Transform streams rather than 'data' event listeners to avoid backpressure issues:
```javascript
// GOOD: Use piping with Transform streams
var contentLengthCheckerStream = new ContentLengthCheckerStream(
parseInt(headers['content-length'], 10)
);
responseStream.pipe(contentLengthCheckerStream).pipe(stream);
// AVOID: Direct data event listeners can cause backpressure issues in older Node.js
responseStream.on('data', function(chunk) {
receivedLen += chunk.length;
// potential for data loss in Node.js <= 0.10.x
});
```
3. **Handle content integrity verification** for both Node.js and browser environments:
- In Node.js, implement pipe-through verification streams
- In browsers, buffer response data for integrity checks
- Verify checksums/hashes when provided in response headers
- Emit appropriate errors with descriptive messages when content length or integrity checks fail
Implementing these practices ensures data is received completely and correctly, preventing subtle bugs in network communication.
---
## Document sdk version requirements
Always explicitly document AWS SDK version requirements in your project, and include configuration instructions for different deployment environments. This is especially critical for Lambda functions where the runtime may include its own SDK version.
For Lambda deployments:
1. Specify whether you're using the bundled SDK or importing your own
2. Document the compatibility requirements clearly in your configuration files
3. Include references to runtime documentation when relevant
Example in a project README or configuration file:
```javascript
// AWS SDK Version requirements
// Current project requires: aws-sdk >= 2.466.0
//
// If using Lambda:
// - Check runtime version: https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html
// - If bundling your own SDK: npm install aws-sdk@latest
// and follow https://docs.aws.amazon.com/lambda/latest/dg/nodejs-create-deployment-pkg.html
//
// For version verification in code:
const AWS = require("aws-sdk");
console.log("Using AWS SDK version:", AWS.VERSION);
```
This documentation helps prevent compatibility issues like "Unexpected key" errors and ensures all developers understand the environment configuration requirements.
---
## Keep CI configurations updated
Regularly review and update CI configuration files to remove obsolete settings and use appropriate version specifications based on current platform capabilities. This minimizes configuration overhead, reduces maintenance burden, and ensures your CI pipeline remains efficient.
For example, in Travis CI:
- Remove unnecessary `dist` and `sudo` settings that are no longer required
- Use stable version identifiers (e.g., "3.6" instead of "3.6-dev") unless specifically testing development versions
- Verify platform documentation is current by testing configurations directly when in doubt
```yaml
# Good: Clean configuration
python:
- "3.5"
- "3.6"
- "3.7"
- "3.8"
# Avoid: Unnecessary settings
python:
- "3.5"
- "3.6"
- "3.7"
matrix:
include:
- python: 3.8
dist: xenial # Unnecessary if no longer required
sudo: true # Unnecessary if no longer required
```
---
## Validate configurations with clarity
Configuration validation should use explicit checks and clear conditional logic to improve code readability and prevent errors. When validating configuration values:
1. Use explicit string comparisons for environment variables
2. Structure conditional logic clearly with early returns
3. Group related checks together
4. Use descriptive error messages
Example:
```javascript
// ❌ Avoid complex nested conditions
if (config.stsRegionalEndpoints) {
if (typeof config.stsRegionalEndpoints === 'string') {
if (['legacy', 'regional'].indexOf(config.stsRegionalEndpoints.toLowerCase()) >= 0) {
// handle valid config
} else {
throw new Error('Invalid config');
}
}
}
// ✅ Use clear validation with early returns
function validateConfig(config) {
if (!config.stsRegionalEndpoints) return;
if (typeof config.stsRegionalEndpoints !== 'string') {
throw new Error('stsRegionalEndpoints must be a string');
}
const validValues = ['legacy', 'regional'];
if (!validValues.includes(config.stsRegionalEndpoints.toLowerCase())) {
throw new Error('stsRegionalEndpoints must be either "legacy" or "regional"');
}
// proceed with valid config
}
```
---
## Focus documentation content
Maintain streamlined primary documentation (like README files) that focuses only on currently supported functionality and recommended approaches. Move specialized details, legacy systems, or deprecated methods to secondary documentation sources like wikis or specialized guides.
**Why this matters:**
- Reduces maintenance burden
- Keeps main documentation relevant and concise
- Follows official platform recommendations
- Improves user experience for the majority of users
**Example:**
Instead of:
```markdown
## Installation
### Build from source
- Build with Go >= 1.12
```bash
GO111MODULE=on make
```
- Build with Go < 1.12 (Not maintained)
```bash
# Deprecated instructions...
```
```
Prefer:
```markdown
## Installation
### Build from source
```bash
GO111MODULE=on make
```
For special build scenarios or legacy systems, please see our [Advanced Build Guide](wiki/advanced-build.md).
```
---
## Standardize API promise patterns
When adding promise support to API methods, implement a consistent pattern that handles both callback-style and multi-parameter methods. Use a standardized promisification approach that appends the promise-determining callback as the last argument.
Example implementation:
```javascript
function promisifyMethod(methodName, PromiseDependency) {
return function promise() {
var self = this;
var args = Array.prototype.slice.call(arguments);
return new PromiseDependency(function(resolve, reject) {
args.push(function(err, data) {
if (err) {
reject(err);
} else {
resolve(data);
}
});
self[methodName].apply(self, args);
});
};
}
```
This pattern ensures:
- Consistent promise behavior across all API methods
- Support for both simple callback methods and multi-parameter methods
- Proper error handling and promise rejection
- Compatibility with different promise implementations
---
## Isolate sensitive buffer data
When handling sensitive data in Node.js, protect against data leakage by isolating sensitive content in dedicated buffers. Node.js can create Buffers that aren't fully isolated, where `buf.byteLength !== buf.buffer.byteLength`, meaning sensitive data might be accessible to other code through the shared buffer memory.
For sensitive operations like decoding credentials or encryption keys:
```javascript
// Secure approach for handling sensitive binary data
function handleSensitiveData(base64Value) {
// Decode the base64 data
const buf = util.base64.decode(value);
// For sensitive data, ensure isolation in Node.js
if (this.isSensitive && util.isNode() && typeof util.Buffer.alloc === 'function') {
/* Node.js can create a Buffer that is not isolated.
* i.e. buf.byteLength !== buf.buffer.byteLength
* This means that sensitive data is accessible to anyone with access to buf.buffer.
* If this is the node shared Buffer, then other code within this process _could_ find this secret.
* Copy sensitive data to an isolated Buffer and zero the sensitive data.
*/
const copy = util.Buffer.alloc(buf.length);
buf.copy(copy);
buf.fill(0); // Zero the original buffer
return copy;
}
return buf;
}
```
Always consider whether your data is sensitive and might require this additional protection. This pattern is particularly important when handling authentication tokens, encryption keys, and other credentials.
---
## Early return after errors
When handling errors in asynchronous functions, always return immediately after invoking a callback with an error to prevent subsequent code execution. This avoids the risk of calling callbacks multiple times or continuing execution paths that assume success.
Bad pattern:
```javascript
function loadViaCredentialProcess(profile, callback) {
proc.exec(profile['credential_process'], function(err, stdOut, stdErr) {
if (err) {
callback(err, null);
}
// Problem: execution continues even after error callback
try {
var credData = JSON.parse(stdOut);
// More processing that might fail or call callback again
callback(null, credData);
} catch(e) {
callback(e);
}
});
}
```
Good pattern:
```javascript
function loadViaCredentialProcess(profile, callback) {
proc.exec(profile['credential_process'], function(err, stdOut, stdErr) {
if (err) {
return callback(err, null); // Return immediately after error callback
}
try {
var credData = JSON.parse(stdOut);
// More processing that only happens on success path
callback(null, credData);
} catch(e) {
return callback(e); // Return after error in try/catch as well
}
});
}
```
For functions that can be called synchronously or asynchronously:
```javascript
function createPresignedPost(params, callback) {
if (typeof params === 'function' && callback === undefined) {
callback = params;
params = null;
}
// Check for errors first, return early
if (!this.config.credentials) {
var error = new Error('No credentials');
if (callback) {
return callback(error);
}
throw error; // Throw for synchronous callers
}
// Success path only executes if no errors were found
var result = this.finalizePost();
return callback ? callback(null, result) : result;
}
```
This pattern creates clear separation between error and success paths, making code more maintainable and preventing hard-to-debug issues caused by multiple callback invocations or unexpected execution after errors.
---
## Structured test resource management
Organize tests with proper resource lifecycle management to ensure reliability and maintainability. Create test resources once in `before` hooks rather than in individual tests, and clean them up in corresponding `after` hooks. For shared resources, use unique identifiers (e.g., timestamps) to prevent conflicts between test runs.
Group related tests into logical suites using descriptive `describe` blocks to improve organization and simplify cleanup:
```javascript
describe('S3 object operations', function() {
var s3;
var bucketName = 'test-bucket-' + Date.now(); // Unique identifier
before(function(done) {
s3 = new AWS.S3();
// Create resources once
s3.createBucket({Bucket: bucketName}).promise()
.then(function() {
return s3.waitFor('bucketExists', {Bucket: bucketName}).promise();
})
.then(function() {
done();
});
});
after(function(done) {
// Clean up resources in corresponding after hook
s3.deleteBucket({Bucket: bucketName}).promise()
.then(function() {
done();
});
});
// Individual tests that use the shared bucket
it('should upload an object', function() {
// Test implementation
});
it('should download an object', function() {
// Test implementation
});
});
```
This approach prevents resource exhaustion, improves test execution speed, and reduces flakiness from race conditions or rate limiting. Separating environment-specific tests (browser vs. Node.js) into different folders further improves organization and prevents execution in incorrect environments.
---
## Document APIs thoroughly
All public API elements must be thoroughly documented with JSDoc annotations that clearly explain their purpose, parameters, return values, and default behaviors. Documentation should be precise, matching the actual code behavior rather than making assumptions or using misleading descriptions.
When adding new parameters or methods:
1. Include comprehensive JSDoc annotations
2. Explain the purpose clearly (not just the type)
3. Document default values
4. Add usage examples for complex features
For example, when adding a new configuration option:
```javascript
/**
* @!attribute signatureCache
* @return [Boolean] whether the signature to sign requests with (overriding
* the API configuration) is cached. Only applies to the signature version 'v4'.
* Defaults to `true`.
*/
/**
* @option options signatureCache [Boolean] whether the signature to sign
* requests with (overriding the API configuration) is cached. Only applies
* to the signature version 'v4'. Defaults to `true`.
*/
```
For methods that return promises, clearly document what the promise resolves to:
```javascript
/**
* @!method getSignedUrlPromise()
* Returns a 'thenable' promise that will be resolved with a pre-signed URL.
*/
```
Ensure that if you're making an API public, all necessary documentation is added and the component is properly exported so it appears in generated documentation.
---
## Limit cache size
Always implement size constraints on caches to prevent memory leaks and performance degradation. Unbounded caches can grow continuously and consume excessive memory, especially in long-running applications.
Key implementation practices:
1. Set a maximum entry count for each cache
2. Implement an eviction strategy (like LRU - Least Recently Used)
3. Design efficient cache keys that include only necessary information
4. Consider providing cache control options to users
Example implementation of a size-constrained cache:
```javascript
// Cache with maximum size limit and LRU eviction
var cachedSecret = {};
var cacheQueue = [];
var maxCacheEntries = 50;
function addToCache(key, value) {
// If cache is full, remove oldest entry
if (cacheQueue.length >= maxCacheEntries) {
var oldestKey = cacheQueue.shift();
delete cachedSecret[oldestKey];
}
// Add new entry
cachedSecret[key] = value;
cacheQueue.push(key);
}
// Generate minimal but sufficient cache keys
function getCacheKey(request) {
// Only include required identifiers to keep cache size manageable
var identifiers = {};
// Add essential properties for uniqueness
// Omit unnecessary data to minimize cache size
return identifiers;
}
```
This approach prevents memory issues in applications that might generate many cache entries over time, while maintaining the performance benefits of caching.
---
## Maintain consistent formatting
Enhance code readability and maintainability by applying consistent formatting practices throughout your codebase:
1. Properly indent continuation lines (lines that are part of the same statement as the preceding line)
2. Separate logical blocks like test suites or function definitions with empty lines
3. Structure complex conditionals for readability
For complex conditionals, prefer nested if statements over lengthy, hard-to-parse single-line conditions:
```javascript
// Hard to read:
if ((AWS.HttpClient.streamsApiVersion !== 2) ||
(!(operation.hasEventOutput && service.successfulResponse(resp)) &&
(!stream || !stream.didCallback)))
// More readable:
if (!stream || !stream.didCallback) {
// don't concat response chunks when using event streams unless response is unsuccessful
if ((AWS.HttpClient.streamsApiVersion === 2) && operation.hasEventOutput && service.successfulResponse(resp)) {
return;
}
// proceed with regular processing
}
```
Consistent formatting makes code easier to scan, understand, and maintain, reducing the cognitive load for everyone working with the codebase.
---
## Follow established testing patterns
When writing tests, use existing patterns and infrastructure already established in the codebase rather than creating custom implementations. This improves consistency, reduces maintenance burden, and helps ensure comprehensive test coverage.
For feature tests:
- Identify common operations (like list/describe) that already have standard patterns
- Reuse existing step definitions when possible
For unit tests:
- Include tests for both positive and negative scenarios when features have toggles
- When implementation changes affect tests, adapt tests to maintain their original intent rather than removing them
Example:
```javascript
// GOOD: Using standard patterns for describe operations
Scenario: describe connections
When I describe the connection
Then I should get response of type "Array"
// INSTEAD OF: Creating custom step definitions
Scenario: Managing connections
Given I create a Direct Connect connection with name prefix "aws-sdk-js"
Then I should get a Direct Connect connection ID
And I describe the connection
...
// GOOD: Testing both enabled and disabled states
it('translates empty strings when convertEmptyValues is true', -> ...)
it('does not translate empty strings when convertEmptyValues is false', -> ...)
```
---
## Semantic type organization
Organize types and interfaces in intuitive namespace hierarchies and use specific types instead of generic ones. Types should be accessible through logically related namespaces, and method signatures should accurately reflect their parameters and return values. This improves code clarity, discoverability, and type safety.
```typescript
// Prefer this (specific types, logical organization)
const converter: Converter = DynamoDB.Converter;
function resolvePromise(): Promise { /* ... */ }
// Instead of these (generic types, unintuitive organization)
const converter: any = DynamoDB.Converter;
const options: DynamoDB.DocumentClient.ConverterOptions = { /* ... */ }; // accessing through DocumentClient when logically belongs to Converter
function resolvePromise(): Promise { /* ... */ }
```
---
## Avoid identifier name stuttering
Do not repeat the resource name in identifier names. This form of stuttering makes code less readable and inconsistent. Instead, use simple, descriptive identifiers without redundancy.
For example:
- Use `Id` instead of `VpnGatewayId` for a VpnGateway resource
- Use `Name` instead of `ReportName` for a ReportDefinition resource
When necessary, include a `memberName` attribute to map the simplified identifier to the actual API field name:
```json
"identifiers": [
{
"name": "Id",
"memberName": "VpnGatewayId"
}
]
```
This approach creates more concise and consistent identifiers throughout the codebase while maintaining the correct mapping to external API representations.
---
## Test configuration precedence
When implementing systems that load configuration from multiple sources, always test the precedence rules explicitly to ensure the correct values are being used. Configuration loading bugs can be subtle and difficult to diagnose in production.
For example, when testing credential loading from multiple files or environment variables:
```javascript
it('loads credentials from preferred source when available in multiple locations', () => {
// Set up multiple configuration sources
process.env.AWS_SDK_LOAD_CONFIG = '1';
helpers.spyOn(AWS.util, 'readFileSync').andCallFake((path) => {
if (path.match(/credentials/)) {
return '...[credentials file content]...';
} else {
return '...[config file content]...';
}
});
// Create a spy to verify which credentials are actually used
const credentialSpy = helpers.spyOn(AWS.STS.prototype, 'makeRequest')
.andCallThrough();
// Exercise the code that loads credentials
const creds = new AWS.SharedIniFileCredentials();
creds.get();
// Verify the correct source was used
expect(credentialSpy.calls[0].arguments[1].accessKeyId)
.to.equal('expected-key-from-preferred-source');
});
```
Don't just verify that configuration loads successfully—explicitly test that the correct values from the highest-priority source are being used when the same configuration option exists in multiple places.
---
## Consistent method interfaces
Design APIs with consistent method interfaces across related resources to improve usability and reduce learning curve. When similar operations are available on different resources, they should follow the same naming conventions, parameter structures, and behavior patterns.
Key principles:
1. **Mirror common operations across resources**: When a method makes sense for multiple resource types, provide it consistently. For example, if users can upload files to S3 objects via `client.upload_file()`, they should also be able to do it via `bucket.upload_file()` with consistent parameters.
2. **Handle parameters consistently**: Use the same parameter names and structures for similar operations. If `ExtraArgs` is used in one method to pass additional options, use it consistently in related methods.
```python
# Example of consistent method interfaces across resources
# Client-level method
s3.meta.client.upload_file('filename.txt', 'bucket-name', 'key')
# Same method available at bucket level with identical parameter structure
bucket = s3.Bucket('bucket-name')
bucket.upload_file('filename.txt', 'key')
```
3. **Consider cross-resource operations**: When designing methods that operate across resources (like copying between buckets), carefully consider authentication needs and parameter mapping between underlying API calls.
4. **Provide appropriate configuration options**: Allow users to customize behavior through configuration objects that can be reused across operations and applied consistently.
5. **Document parameter behavior**: Clearly document how parameters map to underlying operations, especially when a high-level method may call multiple lower-level operations with different parameter requirements.
Following these principles results in intuitive APIs where users can confidently apply knowledge from one part of the API to another, reducing friction and improving developer productivity.
---
## Complete configuration type definitions
Ensure configuration type definitions are complete and consistent between global and service-specific settings. When designing configuration classes, include service identifiers as optional instance variables and ensure update methods accept all relevant option types that might be used at both global and service-specific levels.
Example:
```typescript
// Proper configuration class definition
export class Config {
// Service identifiers as optional properties
s3?: ServiceConfigurationOptions;
dynamodb?: ServiceConfigurationOptions;
// Update method that accepts all relevant option types
update(options: ConfigurationOptions &
ConfigurationServicePlaceholders &
APIVersions &
CredentialsOptions,
allowUnknownKeys?: boolean): void;
}
// Usage example
AWS.config.s3 = {params: {Bucket: 'myBucket'}, useDualstack: true};
```
This approach prevents TypeScript compiler errors when users set valid configurations and maintains consistency between global and service-specific configuration options.
---
## Organize type declarations
Structure TypeScript declarations to improve maintainability and developer experience. Organize related types into appropriate namespaces and use inheritance to avoid duplication.
For service interfaces, place shape definitions in a dedicated sub-namespace to prevent cluttering code completion:
```typescript
// Instead of this:
declare namespace ACM {
interface AddTagsToCertificateRequest { /*...*/ }
interface ListCertificatesResponse { /*...*/ }
// More interfaces...
}
// Do this:
declare namespace ACM {
// Service properties here
}
declare namespace ACM.Types {
interface AddTagsToCertificateRequest { /*...*/ }
interface ListCertificatesResponse { /*...*/ }
// More interfaces...
}
```
For common properties shared across multiple interfaces or classes, use inheritance or abstract classes instead of duplicating definitions:
```typescript
// Instead of duplicating the same properties in multiple places:
interface ConfigurationOptions {
// properties and comments
}
class Config {
// Same properties and comments duplicated
}
// Use inheritance to share definitions:
abstract class BaseConfig {
// Shared properties with comments
}
class Config extends BaseConfig {
// Additional properties specific to Config
}
```
This approach improves code completion accuracy, reduces maintenance overhead, and creates a more intuitive API structure.
---
## Use standard example credentials
When including API keys, access tokens, or other credentials in documentation, examples, or test code, always use clearly marked standard formats that won't trigger security scanners or be mistaken for real credentials.
For AWS resources specifically, use the official example format (e.g., `AKIAIOSFODNN7EXAMPLE` for access keys) rather than realistic-looking keys like `APKBJCAOBHD36274ZIZA`.
```python
# Instead of this:
key_id = 'APKBJCAOBHD36274ZIZA'
# Use this:
key_id = 'AKIAIOSFODNN7EXAMPLE'
```
This practice prevents accidental credential leakage, avoids false positives in security scans like `git-secrets`, and establishes consistent patterns across your codebase. Even example credentials that aren't valid can still trigger security alerts or create confusion if they appear to be real.
---
## Example documentation standards
Organize API documentation examples for maximum clarity and usefulness. Place hand-written examples before generated examples since they're typically more valuable to users. When using @example tags, include only the descriptive title without redundant 'Example:' prefixes.
For instance:
```ruby
# Good
@example Custom implementation
# Hand-written example here
@example Calling the operation
# Generated example here
# Avoid
@example Example: Custom implementation
# Example here
```
This approach improves readability and maintains consistent documentation style.
---
## Write self-documenting tests
Tests should clearly communicate their purpose and expectations without requiring readers to analyze implementation details or scroll through files. Each test should:
1. Use descriptive names that indicate the specific scenario being tested
2. Include explicit assertions that verify all expected behaviors
3. Maintain context within the test method itself
4. Organize shared setup logically
Example of a poorly documented test:
```python
def test_upload(self):
transfer = self.create_s3_transfer()
filename = self.files.create_file_with_size('foo.txt', 1024 * 1024)
transfer.upload_file(filename, self.bucket_name, 'foo.txt')
self.assertTrue(self.object_exists('foo.txt'))
```
Improved version:
```python
def test_upload_below_threshold_uses_single_part_upload(self):
# Configure transfer to use single-part for small files
config = TransferConfig(multipart_threshold=5 * 1024 * 1024)
transfer = self.create_s3_transfer(config)
# Create a 1MB file (below threshold)
filename = self.files.create_file_with_size('foo.txt', 1024 * 1024)
# Upload should use single-part upload
transfer.upload_file(filename, self.bucket_name, 'foo.txt')
# Verify file exists and was uploaded as single part
self.assertTrue(self.object_exists('foo.txt'))
self.assertEqual(self.get_upload_type('foo.txt'), 'SINGLE_PART')
```
The improved version:
- Has a specific, descriptive name
- Documents test setup and expectations
- Includes all relevant assertions
- Maintains context within the test method
- Makes the test's purpose clear without requiring external knowledge
---
## Avoid hidden performance costs
When designing APIs that interact with remote services, be cautious about implementing convenience features that may introduce significant hidden performance costs. Collection operations like slicing, negative indexing, or operations that process all items can be unexpectedly expensive when they require fetching large amounts of data.
Consider these strategies to optimize performance:
1. Use explicit parameters like `limit` to control resource fetching
2. Avoid creating resource instances for items that won't be used
3. When implementing potentially expensive operations, consider:
- Disabling features that always require inefficient implementations (like negative indexing)
- Making expensive operations explicit through separate methods
- Documenting performance implications clearly
For example, instead of supporting negative indexing directly:
```python
# Potentially expensive - fetches all items to get the last one
last_item = collection[-1]
# Better - makes the expensive operation explicit
last_item = collection.to_list()[-1] # User is aware of full collection materialization
# Or provide a direct method
last_item = collection.get_last() # Could be optimized internally
```
This approach gives users control over performance tradeoffs and avoids surprising them with unexpectedly expensive operations.
---
## Documentation quality standards
Ensure documentation is specific, complete, and actionable for developers:
1. **Provide meaningful content** - Avoid vague descriptions like "Test changes" in changelogs. Instead, be specific about what was modified or tested:
```diff
- Test changes
+ Conducted internal testing to validate the integration of new features and ensure stability.
```
2. **Include context and references** - When mentioning external documentation or specifications, include properly formatted links to those resources. This makes it easier for developers to find related information:
```markdown
`ManagedIdentityCredential` now retries 410 status responses as required by
[Azure IMDS documentation](https://learn.microsoft.com/azure/active-directory/managed-identities-azure-resources/how-to-use-vm-token).
```
3. **Ensure code examples are valid** - All code examples in documentation should be derived from compiled, tested code snippets to ensure they work correctly and remain valid over time.
4. **Add explanatory comments** - Include comments that explain the purpose of code transformations or complex configurations to help future maintainers understand why certain decisions were made:
```
# This transform removes the `x-nullable` annotation to ensure compatibility
# with the generated SDK code, which does not support nullable collections.
```
5. **Remove redundancy** - Keep documentation concise by eliminating redundant explanations while maintaining clarity.
For changelogs specifically:
- Only mark changes as "breaking" between stable releases, not for beta versions
- Include specific details rather than placeholder headings
- Remove empty sections when there are no relevant changes
---
## Centralize configuration values
Configuration values should be defined once and referenced throughout your project to ensure consistency and simplify maintenance. Hardcoded values scattered across multiple files lead to update errors and inconsistent configurations.
For package versions, use MSBuild properties:
```xml
3.0.0-beta.20250701.1
```
For framework targets, define a central property:
```xml
net8.0
$(LtsTargetFramework)
```
For script endpoints or configuration values, use shared variables:
```powershell
# Define once at the top of the script file
$ApiViewEndpointUrl = "https://apiview.dev/api/PullRequests/CreateAPIRevisionIfAPIHasChanges"
# Use throughout the script
function Create-API-Review {
param (
[string]$apiviewEndpoint = $ApiViewEndpointUrl,
# ...
)
}
```
This approach reduces the risk of inconsistencies when updates are needed, makes your build more reliable, and clearly communicates the relationships between dependent configuration values.
---
## Preserve API compatibility
When evolving APIs, maintain backward compatibility to prevent breaking changes for existing consumers.
Key approaches:
1. **Retain removed members with obsolete attributes**: When removing or replacing public methods, mark the original as obsolete but maintain its functionality.
```csharp
// Old method
[EditorBrowsable(EditorBrowsableState.Never)]
[Obsolete("Use UpdateAsync(WaitUntil, ConnectorPatch) instead")]
public virtual Response Update(ConnectorPatch patch,
CancellationToken cancellationToken = default)
{
// Call the new implementation
return UpdateAsync(WaitUntil.Completed, patch, cancellationToken).EnsureCompleted();
}
// New method
public virtual ArmOperation Update(WaitUntil waitUntil,
ConnectorPatch patch, CancellationToken cancellationToken = default)
```
2. **Handle constructor parameter changes**: When a required parameter becomes optional, keep a constructor overload that accepts the previously required parameter:
```csharp
// Old constructor required publisherId
public MarketplaceDetails(string planId, string offerId, string publisherId)
: this(planId, offerId)
{
PublisherId = publisherId;
}
// New constructor makes publisherId optional
public MarketplaceDetails(string planId, string offerId) { }
```
3. **Add code-gen attributes for serialization**: When properties are removed from models, use code generation attributes to maintain serialization compatibility:
```csharp
[CodeGenSerialization(nameof(BlockResponseCode), "blockResponseCode")]
public partial class DnsSecurityRuleAction
{
[EditorBrowsable(EditorBrowsableState.Never)]
public BlockResponseCode? BlockResponseCode { get; set; }
}
```
These approaches ensure that existing code continues to work while allowing APIs to evolve with improved designs.
---
## Follow formatting standards
Maintain consistent code formatting by adhering to the defined standards in the .editorconfig file and Azure SDK implementation guidelines at https://azure.github.io/azure-sdk/dotnet_implementation.html. Pay attention to these specific formatting rules:
1. Avoid trailing whitespace at the end of lines
2. In tests, do not emit "Act", "Arrange", or "Assert" comments
3. When including code examples in documentation (like README files), ensure they are mirrored in corresponding test files with proper conditional compilation:
```csharp
#if SNIPPET
// Code snippet that appears in README
[DllImport("user32.dll")]
static extern IntPtr GetForegroundWindow();
#endif
```
4. Use correct casing, grammar, and formatting in changelog entries:
- Use sentence case for the first word (capitalize first letter)
- Be specific and clear about changes (e.g., "Changed `public IList` to `public IReadOnlyList`")
Consistent formatting improves readability, simplifies code reviews, and helps maintain a professional codebase.
---
## Document maintenance decisions
Add clear documentation for any decisions that affect future code maintenance. This includes:
1. Providing explanatory comments for non-obvious default values in parameters
2. Recording version updates in the CHANGELOG
3. Following established documentation structures and patterns
For example, when defining parameters with default values:
```powershell
[string]$RunDirectory = (Resolve-Path "${PSScriptRoot}/../../../"), # Default points to repo root for consistent script execution
```
This documentation practice improves maintainability by ensuring that future developers understand the reasoning behind specific implementation choices, reducing the learning curve and helping to prevent unintended side effects during code modifications.