I think there are two high-level issues here:

Client Recovery of Errors: If the client passes a sha1 for x/y.exe, but the server does not have the corresponding binary, it looks like the whole thing will die right now (I think). We could fix that and just generate a null -> modern y.exe patch for y.exe, but the client won't know how to apply it, because it can't tell whether a patch applies against its y.exe or whether the server failed to find the original binary and the patch applies against emptiness.

One approach would be to return both a list of patches and a map of which sha1 each patch is based on. The client can then delete all the files for which the patches are against null.

Binary Data and JSON: We can't encode arbitrary binary data in JSON -- it isn't valid and PHP isn't OK with it, at least on deserialization. So I would expect this will not actually work end-to-end for most binaries.

I think the easiest approach is for this method to return URIs, not patches. So maybe it returns a map like this:

{
  "a.exe" : {
    "action" : "update",
    "originalSHA1" : "98sdba9yb9d8g8abb",
    "newSHA1" : "as9bga9s8hb9a8sb",
    "patchURI" : "http://.../path/to/patch"
  },
  "b.jpg" : {
    "action" : "create",
    "originalSHA1" : null,
    "newSHA1" : "zxc98b7zcx98b7zx",
    "patchURI" : "http://.../path/to/file"
  },
  "c.bin" : {
    "action" : "delete",
    "originalSHA1" : "298y893r2f3",
    "newSHA1" : null,
    "patchURI" : null
  }
}

The client then examines the return record:

• If a file has been removed, it doesn't need to download anything. Particularly, it doesn't need to download a potentially huge negative-patch just to delete a file. It can just remove the file.
• If a file has been added, the URL can just point at the download URI. The client can download it and drop it into the directory, without dealing with patch application.
• If a file has been updated, the client can download and apply the patch for it.
• The "action" field is optional, I've included it only for clarity. We could omit it, since you can figure it out by examining the sha1s.

This will probably perform a lot better, and centralizes all of the large-file performance issues discussed in https://secure.phabricator.com/T4205#6 into Files, which will let us deal with them in one place. And it works around all the JSON/base64 issues in a simple way.

It's safe to return the getBestURI() URI, clients can always access it without authentication. For new files, you can just return the URI of the File directly. For not-new files, we could compute the patch inline today and save it to a File. Eventually, we could move this to caching, etc.