Packmatic.Encoder (Packmatic v1.2.0) View Source
Holds logic which can be used to put together a Zip file in an interative fashion, suitable for
wrapping within a Stream
. The format of Zip files emitted by Packmatic.Encoder
is documented
under the modules implementing the Packmatic.Field
protocol.
The Encoder is wrapped in Stream.resource/3
for consumption as an Elixir Stream, under
Packmatic.build_stream/1
. Further, the Stream can be used with Plug.Conn
to serve a chunked
connection easily, as provided in Packmatic.Conn.send_chunked/3
.
The Encoder has three statuses:
Encoding, where each Entry within the Manifest is transformed to a Source, which is subsequently consumed.
If the
on_error
option is set to:skip
when building the stream, then sources which have raised error are skipped, although at this time portions of the source may have already been sent. Otherwise, and as the default behaviour, an uncaught exception will be raised and the consumer of the Stream will crash. During Encoding, content is dynamically deflated.Journaling, where each successfully encoded Entry is journaled again at the end of the archive, with the Central Directory structure.
Both Zip and Zip64 formats are used for maximum flexibility. In case the
on_error
option is set to:skip
, any source which has raised an error during its consumption will not be journaled. Due to the nature of streaming archives, this may still leave portions of unusable data within the archive.Done, which is the terminal status.
Link to this section Summary
Types
Represents the intenral state used when encoding entries.
Represents the internal state used when journaling entries.
Represents possible options to use with the Encoder.
Represents an unique identifier of the Stream in operation. This allows you to distinguish between multiple series of Events raised against the same Manifest in multiple Streams concurrently.
Link to this section Types
Specs
encoding_state()
Represents the intenral state used when encoding entries.
Specs
journaling_state()
Represents the internal state used when journaling entries.
Specs
option() :: {:on_error, :skip | :halt} | {:on_event, Packmatic.Event.handler_fun()}
Represents possible options to use with the Encoder.
on_error
can be set to either:skip
or:halt
, which controls how the Encoder behaves when there is an error with one of the Sources.on_event
can be set to a function which will be called when events are raised by the Encoder during its lifecycle. SeePackmatic.Event
for further information.
Specs
stream_id()
Represents an unique identifier of the Stream in operation. This allows you to distinguish between multiple series of Events raised against the same Manifest in multiple Streams concurrently.
Link to this section Functions
Specs
stream_after(:done, nil) :: :ok
Completes the Stream.
Specs
stream_next(:encoding, encoding_state()) :: {:ok, iodata(), :encoding, encoding_state()} | {:ok, iodata(), :journaling, journaling_state()} | {:error, term()}
stream_next(:journaling, journaling_state()) :: {:ok, iodata(), :journaling, journaling_state()} | {:ok, iodata(), :done, nil}
stream_next(:done, nil) :: {:ok, :halt, :done, nil}
Iterates the Stream.
When the Stream is in :encoding
status, this function may continue encoding of the current
item, or advance to the next item, or advance to the :journaling
status when there are no
further items to encode.
When the Stream is in :journaling
status, this function may continue journaling the next item,
or advance to the :done
status.
When the Stream is in :done
status, it can not be iterated further.
Specs
stream_start(manifest, [option()]) :: {:ok, :encoding, encoding_state()} when manifest: Packmatic.Manifest.valid()
stream_start(manifest, [option()]) :: {:error, manifest} when manifest: Packmatic.Manifest.invalid()
Starts the Stream.
If the Manifest provided is invalid, the call will not succeed and the invalid Manifest will be returned.