ADR Amalgamation

• http
  • api
    • h2c in server
      • we are always operating behind a reverse proxy (caddy)
      • why not http3
        • http3 with Jetty means native libraries
        • http3 requires encryption
        • we can always enable http3 in Caddy
      • why not http1
        • http2 offers better performance
    • jetty client vs native client
      • native client does not support h2c
  • caddy
    • locahost for testing https://caddyserver.com/docs/automatic-https#local-https
• documentation
  • java
    • javadoc markdown in code. plus we build source jar. no javadoc site
  • es
    • jsdoc in code. no jsdoc site
  • markdown documents in repo root src/main/resources. this is also the home of fossil
• repository layout
  • promontory does not conform to standard, see blueprint for that
    • additional layer above promontory-dev, need place for parent poms
  • naming top modules vs sub modules. eg. provisioning -> provisioning-common
• testing
  • single test module, no tests in individual modules (test dependencies are not transitive, etc.)
  • default timeout of 30 seconds
  • junit concurrent tests
    • paralell at surefire/jvm level https://maven.apache.org/surefire/maven-surefire-plugin/examples/fork-options-and-parallel-execution.html
    • parallel at junit level https://docs.junit.org/6.0.1/user-guide/index.html#writing-tests-parallel-execution
    • we use junit, but tests must opt in using @Execution(ExecutionMode.CONCURRENT)
• provisioning
  • naming
    • in dev repo: provisioning module
    • in ops repo: ops module
    • built zip: installer
    • password protected: update
  • install
    • runbooks
      • unversions, versioned + idempotent
      • builtin props
        • provisioning_dir
        • runbook_name / runbook_version (resolved during step queue creation, otherwise we can't do it due to nested runbooks, slots, etc.)
    • lockfiles
    • installer
      • include provisioning jar in installer instead of reusing server jar. easier handling, makes versio in ops independent of provisioning module but adds some size
      • ./install.sh my_runbook
      • toolDir, etc. not known to framework-provisioning
      • root script mechanism. some commands like systemd-creds need to be run in PID 1
• o11y
  • logging
    • slf4j vs jul
      • logback is a mess
      • jul is a mess (eg. system classloader)
  • tracer creates wide spans. no logs, metrics
  • https://jsonlines.org/
  • https://docs.rs/tracing-error/latest/tracing_error/struct.SpanTrace.html
• es
  • es specific maven/npm modules
  • package.json is in root instead of promontory-dev, because we use rootDirectory in maven build
  • overrides in package.json so we don't have to specify dependency versions in rest of workspace
  • tsc to lint types and generate type declarations. uses types in package.json
• db
  • pool with a single read and a single write connection
  • migrations
  • https://ericdraken.com/sqlite-performance-testing/
• charset
  • UTF-8 everywhere. set as default in java, see defaultJavaArgs

TODO

• TOTP
• fossil chat
• jvm.config comments
• --illegal-final-field-mutation=deny
• Schema changes