Packmatic.Encoder (Packmatic v2.0.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:

  1. 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.

  2. Journaling, where each successfully encoded Entry is journaled again at the end of the archive, with the Central Directory structure.

    Both Zip and Zip64 field formats are used for maximum compatibility.

    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.

  3. Done, which is the terminal status.

Summary

Types

encoding_state()

Represents the intenral state used when encoding entries.

journaling_state()

Represents the internal state used when journaling entries.

option()

Represents possible options to use with the Encoder.

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.

Functions

stream_after(status, state)

Completes the Stream.

stream_next(status, state)

Iterates the Stream.

stream_start(manifest, options)

Starts the Stream.

Types

encoding_state()

@opaque encoding_state()

Represents the intenral state used when encoding entries.

journaling_state()

@opaque journaling_state()

Represents the internal state used when journaling entries.

option()

@type 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. See Packmatic.Event for further information.

stream_id()

@opaque 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.

Functions

stream_after(status, state)

@spec stream_after(:done, nil) :: :ok

Completes the Stream.

stream_next(status, state)

@spec stream_next(:encoding, encoding_state()) ::
  {:ok, iodata(), :encoding, encoding_state()}
  | {:ok, iodata(), :journaling, journaling_state()}
  | {:error, term()}
@spec stream_next(:journaling, journaling_state()) ::
  {:ok, iodata(), :journaling, journaling_state()} | {:ok, iodata(), :done, nil}
@spec 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.

stream_start(manifest, options)

@spec stream_start(manifest, [option()]) :: {:ok, :encoding, encoding_state()}
when manifest: Packmatic.Manifest.valid()
@spec 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.