Rules and code

What every agent reads before it works, and what code enforces: the Rulebook, the policy, the catalog of allowed changes, the coding guidelines, the code map and the project profile.

🔒 Read-only copy of main at 4c3ef2b7, refreshed by every Live Patrol (27 Oct 12:55 UTC). These files change only through a merge request; agents can never change the Rulebook, the policy or the code map.

Code map

docs/vallum/CODEMAP.mdOpen on GitLab ↗

Code map: vallum-link-shortener

Generated by code from the repository and vallum/project.yaml (python -m vallum.codemap). Never edit by hand; it is refreshed after every release.

A link shortener for small businesses: create short links, redirect visitors, see link details.

Layout

  • Language: python (fastapi)
  • Source: app; tests: tests
  • A feature lives in app/features/{module}.py, its tests in tests/test_{module}.py, its Feature Card in promises/features/{issue}-{feature}.yaml
  • Entry points: app/main.py
  • Never edited by a feature: app/main.py, app/store.py, app/security.py
  • Test command: pytest; health check: /health

Features (from Feature Cards)

FeatureTierKindRoutesFilesFlagPromises
custom-aliasstandardnew-endpointPOST /api/aliasesapp/features/custom_alias.py
tests/test_custom_alias.py		custom_aliasbehavior: alias-redirects, alias-taken-is-refused, alias-valid-chars-only, alias-url-must-be-http, alias-url-length-limit, alias-create-needs-key, alias-response-shape; reliability: alias-create-reliable; security: alias-sec-needs-key, alias-chars-only, alias-max-length, alias-no-path-traversal, alias-url-http-only, alias-url-no-ftp, alias-url-max-length, alias-no-secrets, alias-no-open-redirect; speed: alias-create-fast
healthstandardconfig-infraGET /healthapp/features/health.py-cost: health-no-store; operability: health-reports-revision; speed: health-fast
homestandardui-pageGET /app/features/home.py
app/ui.py		homebehavior: home-renders, home-shows-version, home-headline-trusted; security: home-no-secrets; speed: home-fast
limitsstandardnew-endpointGET /api/limitsapp/features/limits.py
tests/test_limits.py		limitsbehavior: limits-returns-constants, limits-public-no-key; reliability: limits-reliable; security: limits-no-api-key-required, limits-no-secrets, limits-no-ip-logging, limits-constant-response, limits-no-request-body, limits-no-path-parameters, limits-no-query-parameters; speed: limits-fast
link-existsstandardnew-endpointGET /api/links/{code}/existsapp/features/link_exists.py
tests/test_link_exists.py		link_existsbehavior: link-exists-true, link-exists-false, link-exists-no-url, link-exists-odd-code; reliability: link-exists-reliable; security: link-exists-no-url-leak, link-exists-odd-codes-safe, link-exists-long-codes-safe, link-exists-no-secrets, link-exists-public-no-key; speed: link-exists-fast
link-previewexperimentalui-pageGET /p/{code}app/features/link_preview.py
tests/test_link_preview.py		link_previewbehavior: link-preview-shows-destination, link-preview-unknown-404, link-preview-no-secrets, link-preview-odd-code-404; security: preview-no-secrets, preview-no-api-key, preview-rejects-odd-codes, preview-html-escapes-destination; speed: link-preview-fast
linksstandardnew-endpointPOST /api/links
GET /api/links/{code}
DELETE /api/links/{code}		app/features/links.py-behavior: link-create-read, link-delete; reliability: link-api-reliable; security: link-create-needs-key, link-http-only, link-url-well-formed; speed: link-details-fast
redirectcorenew-endpointGET /r/{code}app/features/redirect.py-behavior: redirect-works, redirect-unknown-404; reliability: redirect-reliable; security: redirect-rejects-odd-codes; speed: redirect-fast
redirect-old-linkscorebug-fixGET /r/{code}tests/test_redirect.py-behavior: redirect-old-links-still-work
status-pagestandardui-pageGET /status
GET /status/{rest:path}		app/features/status.py-behavior: status-forwards, status-rules-forward; security: status-no-secrets; speed: status-fast
versionstandardnew-endpointGET /api/versionapp/features/version.pyversionbehavior: version-shows-revision; reliability: version-reliable; security: version-no-secrets; speed: version-fast

Modules

app/__init__.py (python, 1 lines)

app/features/__init__.py (python, 3 lines)

app/features/custom_alias.py (python, 71 lines) · feature custom-alias

  • route POST /api/aliases -> create_alias()
  • class NewAlias [letters_digits_dashes, http_only] :27
  • def create_alias(body, request) :65

app/features/health.py (python, 11 lines) · feature health

  • route GET /health -> health()
  • def health(request) :9

app/features/home.py (python, 161 lines) · feature home

  • route GET / -> home()
  • def home(request) :123

app/features/limits.py (python, 16 lines) · feature limits

  • route GET /api/limits -> limits()
  • def limits() :14

app/features/link_exists.py (python, 22 lines) · feature link-exists

  • route GET /api/links/{code}/exists -> link_exists()
  • def link_exists(code, request) :16

app/features/link_preview.py (python, 42 lines) · feature link-preview

  • route GET /p/{code} -> preview()
  • def preview(code, request) :35

app/features/links.py (python, 77 lines) · feature links

  • route POST /api/links -> create_link()
  • route GET /api/links/{code} -> get_link()
  • route DELETE /api/links/{code} -> delete_link()
  • class NewLink [http_only] :20
  • def valid_url(value) :29
  • def create_link(body, request) :54
  • def get_link(code, request) :66
  • def delete_link(code, request) :74

app/features/redirect.py (python, 22 lines) · feature redirect

  • route GET /r/{code} -> follow()
  • def follow(code, request) :15

app/features/status.py (python, 23 lines) · feature status-page

  • route GET /status -> status_page()
  • route GET /status/{rest:path} -> status_subpage()
  • def status_page() :16
  • def status_subpage(rest) :21

app/features/version.py (python, 13 lines) · feature version

  • route GET /api/version -> version()
  • def version(request) :11

app/flags.py (python, 46 lines)

  • def is_enabled(flag, store, revision) :27
  • def require(flag) :37

app/main.py (python, 77 lines)

  • class RevisionAndTiming :16
  • def discover_features() :53
  • def create_app(store) :63

app/security.py (python, 28 lines)

  • def api_key(request) :12
  • def require_api_key(request, x_api_key) :22

app/store.py (python, 106 lines)

  • class LinkExists :12
  • class MemoryStore [create, get, delete, read_doc, write_doc] :20
  • class FirestoreStore [create, get, delete, read_doc, write_doc] :49
  • def make_store() :99

app/telemetry.py (python, 37 lines)

  • def setup() :12
  • def log(severity, message) :22
  • def log_request(method, route, status, ms, revision) :26

app/ui.py (python, 64 lines) · feature home

  • def esc(value) :48
  • def header() :52
  • def page(title, body) :58

Routes

RouteDefined inFeature
DELETE /api/links/{code}app/features/links.pylinks
GET /app/features/home.pyhome
GET /api/limitsapp/features/limits.pylimits
GET /api/links/{code}app/features/links.pylinks
GET /api/links/{code}/existsapp/features/link_exists.pylink-exists
GET /api/versionapp/features/version.pyversion
GET /healthapp/features/health.pyhealth
GET /p/{code}app/features/link_preview.pylink-preview
GET /r/{code}app/features/redirect.pyredirect
GET /statusapp/features/status.pystatus-page
GET /status/{rest:path}app/features/status.pystatus-page
POST /api/aliasesapp/features/custom_alias.pycustom-alias
POST /api/linksapp/features/links.pylinks

Tests

  • tests/__init__.py: 0 test(s)
  • tests/conftest.py: 0 test(s)
  • tests/test_app.py: 7 test(s)
  • tests/test_cards.py: 6 test(s)
  • tests/test_checker.py: 8 test(s)
  • tests/test_custom_alias.py: 11 test(s)
  • tests/test_desk.py: 1 test(s)
  • tests/test_drive_logic.py: 7 test(s)
  • tests/test_gate.py: 16 test(s)
  • tests/test_gitlab_client.py: 2 test(s)
  • tests/test_layer2.py: 12 test(s)
  • tests/test_layer3.py: 73 test(s)
  • tests/test_layer4.py: 20 test(s)
  • tests/test_limits.py: 9 test(s)
  • tests/test_link_exists.py: 12 test(s)
  • tests/test_link_preview.py: 10 test(s)
  • tests/test_redirect.py: 5 test(s)
  • tests/test_state_notify_priority.py: 9 test(s)
  • tests/test_version.py: 1 test(s)