File upload transmission

[thekid]

This pull request introduces a transmit() method for file uploads to replace the transfer() method, making uploads consistent with downloads.

Example

Given the following file upload code:

$uploads= new Folder(...);
$handler= function($req, $res) use($uploads) {
  if ($multipart= $req->multipart()) {
    if ('100-continue' === $req->header('Expect')) $res->hint(100, 'Continue');

    $files= [];
    $bytes= 0;
    foreach ($multipart->files() as $name => $file) {
      $files[]= $name;
      $bytes+= $file->transfer($uploads);
    }

    // Do something with files and bytes...
  }
};

The problem is that all other requests are blocked until all uploads have been processed. By adding a yield statement after $file->transfer($uploads);, we could hand back control to the server once a file has been transferred (which is what README suggested):

 foreach ($multipart->files() as $name => $file) {
   $files[]= $name;
   $bytes+= $file->transfer($uploads);
+  yield;
 }

However, with big file uploads (or clients with slow connection speeds), this might still be blocking other requests for a significant amount of time. With the new API, the example can be changed as follows:

 foreach ($multipart->files() as $name => $file) {
   $files[]= $name;
-  $bytes+= $file->transfer($uploads);
+  $bytes+= yield from $file->transmit($uploads);
 }

Further notes

This pull request makes use of the new features added in xp-framework/networking#22. However, the code also runs without this featureset being available!

[thekid]

Released in https://github.com/xp-forge/web/releases/tag/v3.5.0