Rudder Scala
Developmentrudder-scalaRudder Scala is an Agent Skill for development published in the Normation/rudder repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Conventions and idioms for writing Scala in the Rudder codebase (webapp/sources). Use whenever reading, writing, reviewing, or refactoring Scala in the rudder repo. Covers functional style, ZIO effects and the RudderError model (IOResult), DDD / hexagonal architecture, repositories, parse-don't-validate, zio-json / chimney / quicklens data handling, java.time, security-in-depth, and dependency policy.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/Normation/rudder/blob/HEAD/.claude/skills/rudder-scala/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/rudder-scala, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Writing Scala in Rudder
Rudder is a long-lived codebase (Scala 2.8 in 2009 → Scala 3 today). We migrate step by step toward a more functional style with ZIO as the effect handler. New and changed code follows the conventions below; we do not rewrite untouched legacy code just to modernize it, but we leave every file we touch a little better.
Scope — applies to all the Rudder Scala repos. These conventions hold for the Scala
code in rudder, rudder-plugins, and rudder-plugins-private alike (the plugin
repos build on rudder-core and use the same stack: IOResult/RudderError, zio-json,
chimney, quicklens, enumeratum, the plugin API framework, etc.). This skill file lives
in the rudder repo, and its links to ADRs and example code are relative to that repo —
but when you write Scala in either plugins repo, follow this skill too (look up the
referenced rudder code/ADR in the rudder checkout). Plugin-specific points: the
dynamic plugin-status API framework (103) and license
parsing live in the plugin repos.
Golden rules (always apply)
- Functional first. Immutable data, no shared mutable state, effects reified as
values. Any mutation or I/O must be wrapped in
IOResult(see300). - Less code is better code. Minimize boilerplate and lines. Prefer the simple, short solution. Don't implement a pattern "fully" if a smaller version is clearer.
- No type-level acrobatics. Scala is powerful — lean on that power, but get it from well-chosen libraries (zio, chimney, quicklens, zio-json), not from hand-rolled implicit/type-level machinery.
- Dumb data, smart companions. Business objects are plain
case classes with as few methods as possible. Serialization, conversion and mapping live in companion objects orextensionmethods (see001,400). - Program to traits. Every service/repository has a trait defining its API, even
with a single implementation. DI is constructor-only, wired in
RudderConfig(see102). - Parse, don't validate. User input is parsed into typed domain objects at the
boundary; persistence goes through a repository (see
200,201). - Security in depth is a design constraint, not an afterthought (see
600). - Be strict about dependencies. Apache2/BSD-compatible licenses only; prefer
removing deps over adding them (see
700).
How to use this skill
Before doing substantial work in a given area, read the matching topic file. Files
are named NNN-topic.md; the first digit is the subject area (table below), the
other two digits identify the topic within it.
| 1st digit | Subject area |
|---|---|
| 0 | Generalities — coding philosophy & Scala 3 idioms |
| 1 | Architecture — DDD, hexagonal, traits & dependency injection |
| 2 | Persistence — repositories, parse-don't-validate |
| 3 | Effects & errors — ZIO, IOResult, bridging legacy code |
| 4 | Data & serialization — case classes, zio-json, chimney, quicklens |
| 5 | Datetime — java.time |
| 6 | Security — defense in depth, web/output safety, authn/authz |
| 7 | Dependencies & ecosystem |
| 8 | Build, tooling & formatting |
| 9 | Testing |
Topic index
000-coding-philosophy.md— FP, immutability, minimal LOC, no type acrobatics001-scala3-idioms.md— companions, extensions,derives,given, opaque types, minimizing imports100-package-layout.md— bounded-context-first packages, not technical-layer; migrating off legacydomain/repository/services101-architecture-ddd-hexagonal.md— bounded contexts, hexagonal, "pragmatic DDD"102-traits-and-dependency-injection.md— program-to-trait, constructor DI,RudderConfig103-rest-api-and-endpoints.md— declarativeEndpointSchema, versioning, per-endpointauthz, lift handlers104-bootstrap-and-migrations.md—BootstrapChecksearly/end phases, self-managed async DB/schema migrations,Boot.scala200-persistence-repositories.md— repository as single point of change, optional persistence layer201-parse-dont-validate.md— typed parsing at I/O boundaries300-effects-zio-ioresult.md—IOResult/PureResult, when & how to use ZIO301-error-model.md—RudderError,Chained,Accumulated, domain errors302-bridging-toio-runnow.md—.toIO,.toBox, minimizing.runNow303-logging.md—NamedZioLoggerpure loggers, migrating off liftextends Logger400-domain-case-classes.md— dumb case classes, value/opaque wrappers, ADTs401-json-zio-json.md—derives JsonCodec, manual codecs, discriminators402-chimney-transformers.md— mapping between representations403-quicklens-updates.md—.modify(...).setTo(...)instead of.copy404-serialization-contracts.md— user-facing serialization is a contract; DTOs + chimney, stable tokens, test-enforced500-datetime-java-time.md—java.time, migrating off joda600-security-in-depth.md—SecurityError, tenants, path traversal, defense in depth601-web-and-output-security.md—XmlSafe(XXE), LiftJsRaw/XSS, CSRF, CSP, sessions602-authentication-and-authorization.md— Spring auth vs Rudder authz, BouncyCastle, tokens, RBAC/ACLAuthorizationType700-dependencies-ecosystem.md— license policy, minimizing deps, ZIO scope800-build-and-formatting.md— maven/spotless/scalafmt,-Werror, license headers900-testing.md— specs2 + JUnitRunner, zio-test for new code, trait-based test doubles
The effect type is
com.normation.errors.IOResult[A] = ZIO[Any, RudderError, A].
Sources of truth
The error-management philosophy behind RudderError/IOResult (nominal cases vs
errors vs defects, WYSIWYG contracts, errors-as-signal) comes from the talk
"Systematic error management in application" (DevoxxFR 2021, F. Armand).
See 000, 301.
This skill summarizes and operationalizes decisions; the authoritative records are
the ADRs in rudder/adr/webapp/ (and some in
rudder/adr/system/). When a topic touches an ADR, the topic
file cites it — follow the link and read the ADR for the full context and rationale,
and prefer the ADR if it ever conflicts with the summary here. If you make a decision
that isn't captured yet, add an ADR (see adr/template.md)
and then update the matching topic file. ADRs already reflected here include: