Week 1 - M4: RemoteClient skeleton + wire protocol sketch

[aman-a-shah]

Owner: @Shuhan6017
Module: 4 - Remotes & networking
File you own: minigit/remote.py
Week: 1 of 10 - Contract & Skeletons

What "skeleton week" means

• no sockets yet -> TCP handshake is Week 2
• goal: methods exist with exact signatures, plus the wire-format decisions written down
• you depend on Modules 1 and 3 -> do not wait, stub both (step 10)
• yours is the biggest module and sits on top -> the whole team joins you later in the term

Interface contract - exact signatures, do not change alone

class RemoteClient:
    def push(self, remote_address: str, branch: str, token: str) -> None: ...
    def pull(self, remote_address: str, branch: str, token: str) -> None: ...

• remote_address is "host:port", e.g. "127.0.0.1:9418"
• every network failure raises NetworkProtocolError - bad address, bad auth, rejected push
• remotes live in .minigit/config: remote name -> address + token

Steps

0. Setup (once): clone, cd mini-git, scripts/init.sh, skim README.md + minigit/errors.py
1. Branch week1/m4-remote-client-skeleton
2. __init__(self, repo_path=".", store=None, commits=None) -> self.config_path, store or ObjectStore(...), commits or CommitManager(...)
3. _parse_address(address) -> tuple[str, int] - split on last ":"; missing ":", empty host, non-numeric port, or port outside 1-65535 -> raise NetworkProtocolError
4. push -> parse address, empty token raises NetworkProtocolError, then print a stub line
   • comment the real sequence, in order:
     1. connect over TCP
     2. ask remote for its current hash for <branch>
     3. remote hash not an ancestor of local -> someone else pushed first -> NetworkProtocolError
     4. walk local commit graph from remote's hash up to local -> collect reachable objects
     5. send only the missing objects
     6. move the remote ref LAST, only after every object arrived
5. pull -> same validation, stub print # Week 6 - same exchange in reverse
6. Wire protocol notes - short comment block at the bottom: one message per line, UTF-8, \n-terminated; verbs AUTH <token> / REF <branch> / WANT <hash> / OBJ <type> <len> / DONE / ERR
   • draft only - Week 2 makes it real, so getting it wrong now costs nothing
7. CLI: minigit push <addr> <branch>, minigit pull <addr> <branch>, --token flag default ""
8. Wire into minigit/cli.py - one import + one line; expect a small conflict
9. Do NOT: open a socket, add a dependency (socket is stdlib)
10. Tests tests/test_remote.py with FakeObjectStore + FakeCommitManager
    • cover: "127.0.0.1:9418" parses; "localhost" / "host:abc" / "host:0" / "" each raise; empty token raises; valid address + token does not raise
11. quality-check green -> commit, push, PR

Team checkpoint (all four, end of week)

• contract signatures confirmed in the group chat before anyone merges
• everyone imports everyone else's class and calls one method -> shaped fake result back
• nobody depends on you -> free to move fast and break your own stubs

Done when

• both methods, exact signatures
• _parse_address validates and raises NetworkProtocolError
• store and commits injectable via __init__
• wire-protocol sketch written down in the file
• both CLI commands run
• tests pass with the fakes
• quality-check green
• PR open + reviewed