Http: Review stream interfaces

- Add `MultipartStreamInterface::getParts()` for completeness
- Rename `StreamPartInterface` methods for clarity and consistency:
  - `getFallbackFilename()` -> `getAsciiFilename()`
  - `getContent()` -> `getBody()`
- Review `HttpMultipartStream` (rename pending)
  - Do not remain operational after `close()` or `detach()` are called

Author: lkrms

src/Toolkit/Contract/Http/Message/MultipartStreamInterface.php

@@ -4,10 +4,20 @@
 
 use Salient\Contract\Http\HasHttpHeader;
 
+/**
+ * @api
+ */
 interface MultipartStreamInterface extends StreamInterface, HasHttpHeader
 {
     /**
-     * Get the stream's encapsulation boundary
+     * Get an array that contains each of the stream's parts
+     *
+     * @return StreamPartInterface[]
+     */
+    public function getParts(): array;
+
+    /**
+     * Get the encapsulation boundary of the stream
      */
     public function getBoundary(): string;
 }

src/Toolkit/Contract/Http/Message/StreamInterface.php

@@ -5,6 +5,7 @@
 use Psr\Http\Message\StreamInterface as PsrStreamInterface;
 use Stringable;
 
-interface StreamInterface extends
-    PsrStreamInterface,
-    Stringable {}
+/**
+ * @api
+ */
+interface StreamInterface extends PsrStreamInterface, Stringable {}

src/Toolkit/Contract/Http/Message/StreamPartInterface.php

@@ -6,35 +6,40 @@
 use Salient\Contract\Core\Immutable;
 use Salient\Contract\Http\HasMediaType;
 
+/**
+ * @api
+ */
 interface StreamPartInterface extends Immutable, HasMediaType
 {
     /**
-     * Get an instance with the given field name
+     * Get the field name of the part
      */
-    public function withName(string $name): StreamPartInterface;
+    public function getName(): string;
 
     /**
-     * Get the field name of the part
+     * Get an instance with the given field name
+     *
+     * @return static
      */
-    public function getName(): string;
+    public function withName(string $name): StreamPartInterface;
 
     /**
      * Get the filename of the part
      */
     public function getFilename(): ?string;
 
     /**
-     * Get the ASCII fallback filename of the part
+     * Get the ASCII filename of the part
      */
-    public function getFallbackFilename(): ?string;
+    public function getAsciiFilename(): ?string;
 
     /**
      * Get the media type of the part
      */
     public function getMediaType(): ?string;
 
     /**
-     * Get the content of the part
+     * Get the body of the part
      */
-    public function getContent(): PsrStreamInterface;
+    public function getBody(): PsrStreamInterface;
 }