# backtrip — Architecture
## Overview
backtrip is a pipeline with two independent front ends sharing one CLI and
one control-flow engine:
```
.NET: .dll/.exe bytes → pe.rs → metadata/ → Reader → cil/ → decompile/csharp.rs → C#
Java: .class bytes → java/classfile.rs → java/decoder.rs → decompile/java.rs → Java
.jar bytes → java/jar.rs (zip + raw-DEFLATE) ↘ (per .class entry)
↘ java/disasm.rs → javap-style
```
Format detection happens in `main.rs` by magic bytes: `MZ` → .NET path,
`0xCAFEBABE` → Java path, `PK\x03\x04` → jar (unpacked, then the Java path
per class entry). Both back ends emit a flat, goto-based statement
list that is folded into structured source by the shared passes in
`decompile/flow.rs` (if/else, while/do-while/for, switch, goto cleanup).
```
input bytes (MZ or 0xCAFEBABE)
|
v (.NET) (Java)
pe.rs java/classfile.rs (constant pool, members, attrs)
| |
v v
metadata/ java/descriptor.rs (JVMS 4.3 types)
| |
v v
Reader java/decoder.rs + java/opcodes.rs (JVM bytecode)
| |
+----------+--------------+
v v
decompile/csharp.rs decompile/java.rs (expression-stack machines)
| | decompile/flow.rs (shared restructuring passes)
v v
output.rs — one file per type
```
## Modules
### `pe`
`PeImage::parse` validates the MZ/PE signature, reads the COFF + optional
header (PE32 vs PE32+), the 16 data directories, and section headers. It
exposes `rva_to_offset` (used everywhere RVA resolution is needed) and
`cli_header` to obtain the metadata directory and entry-point token.
### `metadata`
- `streams` — `MetadataRoot` parses the `BSJB` root and stream headers, and
provides heap accessors. `#US` user strings are decoded as UTF-16LE.
`decode_compressed_uint` implements ECMA-335 compressed-integer decoding.
- `tables` — defines table numbers (`tbl`), coded-index kinds (`Coded`), the
per-table column schemas (`schema`), index-size computation (`IndexSizes`),
and the row parser (`parse_tables`). `decode_coded` turns a coded column
value into `(Option<table>, row)`.
- `signatures` — `Type`, `MethodSig`, `ArrayShape` and the recursive
`parse_type` / `parse_method_sig` / `parse_field_sig` decoders.
- `reader` — `Reader` borrows `PeImage`, `MetadataRoot`, and `Tables` and
offers ergonomic accessors: type/method/field names, signatures, method
bodies (tiny/fat), local types, generic parameters, nested-class parents,
and C#-ish type-name rendering.
### `cil`
- `opcodes` — the complete opcode → `OpInfo` lookup (1-byte and `0xFE`-prefix
2-byte), sourced from dotnet/runtime `opcode.def`.
- `decoder` — `decode(&[u8]) -> Vec<Instruction>`. Each `Instruction` carries
its offset, opcode value, name, typed `Operand`, and total size.
- `disasm` — renders instructions as `IL_NNNN: op operand` text, resolving
tokens through the `Reader`.
### `java` (JVM class files)
- `classfile` — `ClassFile::parse` validates the `0xCAFEBABE` magic and parses
the constant pool (all 17 tags, `Long`/`Double` occupying two slots,
modified UTF-8 decoding), access flags, fields, methods, and attributes.
Structured attributes: `Code` (with exception table and LocalVariableTable),
`ConstantValue`, `Exceptions`, `InnerClasses`, `Signature`, `SourceFile`.
`BootstrapMethods` is kept raw for `invokedynamic` decoding.
- `descriptor` — JVMS 4.3 field/method descriptor parsing to dotted Java
type names, plus class generic type-parameter names from `Signature`.
- `opcodes` — the complete 0x00–0xC9 JVM opcode table with operand kinds;
branch offsets are relative to the opcode address (unlike CIL).
- `decoder` — `decode(&[u8]) -> Vec<Instruction>`; expands `wide` prefixes,
decodes `tableswitch`/`lookupswitch` with 4-byte padding, and stores
absolute branch targets.
- `disasm` — javap-style text output for `--il` on class files.
- `jar` — `.jar` archive support: locates the zip end-of-central-directory
record by a backward scan, walks the central directory, and reads entry
data with a built-in raw-DEFLATE (RFC 1951) decoder (stored entries pass
through). Broken `.class` entries are skipped rather than failing the
whole archive.
### `decompile`
Two back ends (`csharp.rs`, `java.rs`) plus a shared control-flow engine
(`flow.rs`):
- `flow.rs` — language-neutral passes over the flat `Vec<String>` statement
list both back ends emit: `restructure_if_else`, `restructure_while_loops`
(Roslyn shape), `restructure_while_loops_javac` (condition-header shape),
`restructure_do_while_loops`, `restructure_for_loops`, `restructure_switch`,
`cleanup_goto_labels` (comments out leftover jumps — mandatory for valid
Java), and the precedence-aware expression helpers (`binop`, `prec`,
`strip_outer_parens`).
- `csharp.rs` contains:
- `decompile_assembly` — iterates `TypeDef` rows (skipping `<Module>`),
producing one `DecompiledType` per type.
- `decompile_type` — emits the namespace, kind (`class`/`struct`/`interface`/
`enum`), base type + interfaces, fields, then methods.
- `decompile_method` — renders the signature (access, `static`/`virtual`/
`override`/`abstract`, return type, parameters, generics) and the body.
- `decompile_body` — the expression-stack machine, plus .NET-specific
passes (locks, using, foreach, lambdas, exception markers).
- `java.rs` mirrors that shape: `render_class`/`render_method`/`render_field`
for declarations, and `decompile_body` — an expression-stack machine with
Java-specific handling:
- **join frames**: values live across branches are flushed into per-target
temp variables (`T{offset}_{i}`), sound because the JVM verifier
guarantees consistent stack depth per join point;
- **`invokedynamic` string concat**: javac 9+ recipes
(`makeConcatWithConstants`) are decoded from BootstrapMethods back into
`+` expressions;
- **lazy exception-var binding**: catch variables are named when the walk
reaches the handler (javac reuses slots for locals and catch vars);
- **ternary/boolean-return reconstruction** from javac's materialized
branches;
- `insert_exception_markers` — Java EH clauses have no explicit length; a
handler region ends where the next handler starts, and javac's
self-covering finally ranges are collapsed.
- `json.rs` — `assembly_to_json` renders a structured JSON model (types,
fields, methods) for `--json`, built with manual string escaping (no
serde).
- `obfuscation.rs` — `detect_obfuscation` scans for non-printable/very long
names, control-flow flattening (large switches), and string-encryption
patterns, formatted into a severity-tagged report.
- `verify.rs` — `verify` checks that every metadata type/method/field name
appears in the decompiled output (`--verify`), skipping compiler-generated
members (accessors, delegates, backing fields) to avoid false positives.
### `output`
`write_types` creates the output directory and writes one file per
`DecompiledType`, returning the count.
### `error`
`Error` (IO, invalid PE/metadata/CIL/class-file/signature, `NotImplemented`,
`NotFound`, `Usage`) + the crate-wide `Result<T>` alias used by every module.
### `main` / `lib`
`main.rs` is the clap CLI (`--il`, `--list`, `-o`). `lib.rs` re-exports all
modules so integration tests can exercise the pipeline directly without
shelling out.
## Key design decisions
- **Generic table schema**: rather than a typed struct per table, tables use a
column-type list (`&[Col]`). This keeps sizing correct for every present
table (required to find later tables' offsets) with minimal code, while
typed accessors live in `Reader`.
- **Coded indexes decoded lazily**: raw column values are stored as `u32`;
`decode_coded` is applied at access time. A value of `0` is "no reference".
- **Stack-machine decompiler**: a full C# decompiler needs control-flow
graphs and expression trees. The stack-machine approach produces correct,
readable output for straight-line code immediately and degrades gracefully
(goto labels) for complex control flow, giving a working tool today and a
clear path to structured reconstruction later.
## Test strategy
- **.NET fragments** — `tests/integration.rs` loads the prebuilt
`tests/fixtures/bin/Release/net8.0/Sample.dll` and asserts that decompiled
output contains expected C# fragments (class/struct kinds, method
signatures, arithmetic bodies, control flow, initializers, lambdas,
properties/events/delegates, generics).
- **Round-trip gate** — the prebuilt `Roundtrip.dll` is decompiled, the
output recompiled with `dotnet` (must be 0 errors), and the recompiled
assembly re-decompiled with the same type set.
- **Java** — the same integration file covers class and jar fixtures:
fragment assertions, `--il` disassembly, and recompiling decompiled output
with `javac` (skipped when `javac` is absent).
- **CLI smoke tests** — shell out to the built binary via
`CARGO_BIN_EXE_backtrip` for flag wiring and exit codes.
- **Unit tests** live inline (`#[cfg(test)]`) in the decoders, metadata
streams/tables/signatures, `flow.rs`, and both decompiler back ends.
- **Doc sync** — `tests/docs_sync.rs` fails `cargo test` when the AGENTS.md
module list or TODO.md test counts drift from the code.