Add a multipart HTTP request class.

pkg/http/lib/src/multipart_file.dart

+// Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+library multipart_file;
+
+import 'dart:io';
+
+import 'utils.dart';
+
+/// A file to be uploaded as part of a [MultipartRequest]. This doesn't need to
+/// correspond to a physical file.
+class MultipartFile {
+  /// The name of the form field for the file.
+  final String field;
+
+  /// The size of the file in bytes. This must be known in advance, even if this
+  /// file is created from an [InputStream].
+  final int length;
+
+  /// The basename of the file. May be null.
+  final String filename;
+
+  /// The content-type of the file. Defaults to `application/octet-stream`.
+  final ContentType contentType;
+
+  /// The stream that will emit the file's contents.
+  final InputStream _stream;
+
+  /// Whether [finalize] has been called.
+  bool get finalized => _finalized;

[Bob Nystrom, 2012/11/06 22:00:08]

How about "isFinalized" here? I think "if (file.isFinalized)" reads a bit more
naturally to me.

[nweiz, 2012/11/06 23:15:56]

Done.

+  bool _finalized = false;
+
+  /// Creates a new [MultipartFile] from an [InputStream]. The length of the
+  /// file in bytes must be known in advance. If it's not, read the data from
+  /// the stream and use [MultipartFile.fromBytes] instead.
+  ///
+  /// [contentType] currently defaults to `application/octet-stream`, but in the

[Bob Nystrom, 2012/11/06 22:00:08]

I try to avoid sentences that start with identifiers just because it makes
capitalization a bit odd. This is OK, but maybe do "The [contentType]..."?

[nweiz, 2012/11/06 23:15:56]

I think using the definite article only for identifiers that start sentences
reads even weirder.

[Bob Nystrom, 2012/11/07 00:50:26]

Fair enough.

+  /// future may be inferred from [filename].
+  MultipartFile(this.field, this._stream, this.length,
+      {this.filename, ContentType contentType})
+    : this.contentType = contentType != null ? contentType :
+          new ContentType("application", "octet-stream");
+
+  /// Creates a new [MultipartFile] from a byte array.
+  ///
+  /// [contentType] currently defaults to `application/octet-stream`, but in the
+  /// future may be inferred from [filename].
+  factory MultipartFile.fromBytes(String field, List<int> value,
+      {String filename, ContentType contentType}) {
+    var stream = new ListInputStream();
+    stream.write(value);
+    stream.markEndOfStream();
+    return new MultipartFile(
+        field, stream, value.length,
+        filename: filename,
+        contentType: contentType);

[Bob Nystrom, 2012/11/06 22:00:08]

Style nit. Put the positional args on the same line as new and put the named
args on one line?

[nweiz, 2012/11/06 23:15:56]

Done.

+  }
+
+  /// Creates a new [MultipartFile] from a string.
+  ///
+  /// The encoding to use when translating [value] into bytes is taken from
+  /// [contentType] if it has a charset set. Otherwise, it defaults to UTF-8.
+  /// [contentType] currently defaults to `text/plain; charset=utf-8`, but in the

[Bob Nystrom, 2012/11/06 22:00:08]

Long line.

[nweiz, 2012/11/06 23:15:56]

Done.

+  /// future may be inferred from [filename].
+  factory MultipartFile.fromString(String field, String value,
+      {String filename, ContentType contentType}) {
+    contentType = contentType == null ? new ContentType("text", "plain") :
+        new ContentType.fromString(contentType.toString());

[Bob Nystrom, 2012/11/06 22:00:08]

Why the toString / fromString dance here?

[nweiz, 2012/11/06 23:15:56]

We want to be able to modify the charset below without affecting the original
object. I've added a comment explaining this.

+    var charset = contentType.charset;
+    var encoding = encodingForCharset(contentType.charset, Encoding.UTF_8);
+    contentType.charset = encoding.name;
+
+    return new MultipartFile.fromBytes(
+        field,
+        encodeString(value, encoding),
+        filename: filename,
+        contentType: contentType);
+  }
+
+  // TODO(nweiz): infer the content-type from the filename

[Bob Nystrom, 2012/11/06 22:00:08]

Should be a sentence: "Infer ... filename."

[nweiz, 2012/11/06 23:15:56]

Done.

+  /// Creates a new [MultipartFile] from a [File].
+  ///
+  /// [filename] defaults to the name of the file on disk. [contentType]
+  /// currently defaults to `application/octet-stream`, but in the future may be
+  /// inferred from [filename].
+  static Future<MultipartFile> fromFile(String field, File file,
+      {String filename, ContentType contentType}) {
+    if (filename == null) filename = new Path(file.name).filename;
+    return file.length().transform((length) {

[Bob Nystrom, 2012/11/06 22:00:08]

You could do lengthSync() here. Do you think it's better to make this async?

[nweiz, 2012/11/06 23:15:56]

Yeah, I don't like using synchronous IO in library code.

+      return new MultipartFile(
+          field, file.openInputStream(), length,
+          filename: filename,
+          contentType: contentType);
+    });
+  }
+
+  // Finalizes the file in preparation for it being sent as part of a
+  // [MultipartRequest]. This returns an [InputStream] that should emit the body
+  // of the file. The stream may be closed to indicate an empty file.
+  InputStream finalize() {
+    if (finalized) {
+      throw new StateError("Can't finalize a finalized MultipartFile.");
+    }
+    _finalized = true;
+    return _stream;
+  }
+}