Module service_protocol 

Messages between the wrapper and the resident commit service. What: The messages between the wrapper and the resident commit service, one JSON object per line. Why: A client sends a prepared change with a request identity and waits; the service answers with a landing, a queue position, a request to prepare again, or a failure from a closed list. The line form needs no framing library and every field is checked on read, so a damaged or hostile line is refused rather than guessed (doc/planning/cli-git-resident-service.md, “Protocol and request identity”).

In TS you’d write (pseudocode):

socket.write(JSON.stringify(encodeRequest(request)) + '\n'); const reply = decodeResponse(await readLine(socket));

Structs

Change

What: One path a commit changes: a file to set, or a file to delete. Why: The client has already written the file’s content into the repository’s object store, so the service names the object and never reads the user’s worktree.

Cleanup

What: What the landing of a merge, cherry-pick or revert conclusion removes from the worktree’s Git directory once the commit is on the branch. Why: Native git commit removes MERGE_HEAD and its siblings when it concludes; the client built the commit with real Git in a scratch repository that holds the state it was given, so the entries real Git removed there are the ones the landing removes here, each only while it still holds the bytes copied at preparation.

CommitRequest

What: A request to land one commit. Why: Every field the service needs to land it on the current branch without asking the client anything.

LandedCapture

A commit the service landed and when its bytes were captured, as the service tells a client whose commit it sends back.

Enums

ClientMessage

What a client sends.

FailureCode

The closed list of reasons the service gives for not landing a request.

ServiceMessage

What the service sends.

Constants

ALLOWED_MODES

Modes a change may give a file.

MAX_CHANGES

The most paths one request may change.

MAX_LINE_BYTES

The longest line either side accepts, in bytes.

PROTOCOL_VERSION

The protocol version this build speaks; a service and a client agree when their versions are equal.

RELEASE

The release of this build: the crate version, which the wrapper and the service program share because they are built and installed together. A service from another release is retired even when it speaks the same protocol, since the program its unit names, and the behavior behind the same messages, may differ.

SCRATCH_PREFIX

The name prefix of a commit’s scratch directory.

Functions

decode_client

What: Reads and checks one client line. Why: The service trusts nothing from a socket: sizes, names, paths, modes and the object names are all checked.

decode_service

What: Reads one service line. Why: The client checks what it is told as strictly as the service checks what it is sent.

encode_client

What: The line for a client message. Why: One object per line, no newline inside any field.

encode_retire

What: The line that asks a service to retire, written in the protocol version that service speaks. Why: A service reads a line only in its own version, except that services built with this check read a retire at any version. A service of an earlier release (the ones that sent no release in their greeting) refuses a retire written in a newer version as unsupported and stays, so the line must carry the version the service announced.

encode_service

What: The line for a service message. Why: The same one-object form in the other direction.

is_object_name

Whether text is a full object name in hexadecimal (40 or 64 digits).

is_plain_path

Whether path is a plain repository-relative path: no leading slash, no empty, . or .. part, no NUL or newline.

is_scratch_path

What: Whether path is the scratch directory of a commit in the worktree whose own Git directory is git_dir. Why: The service removes whatever a client names when the client’s connection closes, so the name must be one only the wrapper makes (the prefix and an identity of letters, digits and dashes) and the place must be directly inside the worktree’s own Git directory, with no relative part that could lead elsewhere.

is_zero_object

Whether name is the all-zero object name, which stands for a branch that does not exist yet.