Bringing the go-toolkit up-to-date with the kotlin-toolkit changes

[chocolatkey]

@mickael-menu I was looking into implementing RAR support in the toolkit, however I noticed that in the meantime, the kotlin toolkit's handling of archives has significantly changed. Could you suggest me the best docs/links that would help me determine what changes have been made in general, so I can re-sync the toolkits?

[HadrienGardeur]

RAR handling to target CBR files in addition to CBZ?

[chocolatkey]

@HadrienGardeur that's correct, this is about #96

[mickael-menu]

Yes these are the changes part of the mobile toolkits v3.

Here's a summary of the related changes:

• Resource is simplified and doesn't have any notion of Link anymore. It just provides a way to stream bytes, with only three additional metadata:
  • estimatedLength: Int? which is a hint of the length of the resource (e.g. pulled from encryption.xml/OriginalLength in the case of LCP).
  • sourceURL: AbsoluteURL? which locates the resource on the file system or on a remote HTTP server, if any.
  • properties: [String: Any] is akin to the Link.properties and used for extensions. This is for example where you store a ZIP entry's compressed length.
• Fetcher and Archive are both deprecated and replaced with a single Container interface, which also doesn't have any dependency on Link.
  • It represents a collection of known Resources, for example an archive, a folder on the file system, or a list of known HTTP URLs forming a single package.
  • It is much simpler:
    • a list of entries: [URL] which are the available entries in the container. Could be relative URLs or absolute ones for an HTTPContainer.
    • a get(URL) -> Resource? method.
    • sourceURL: AbsoluteURL? which locates the container on the file system or on a remote HTTP server, if any.
• Asset replaces PublicationAsset and represents any type of asset.
  • In practice an asset is either a Resource or a Container.
  • It also contains the format: Format of the asset, which is basically a MediaType + file extension and additional spec conformances (e.g. "is this asset protected by LCP?")

From there, we have several classes using and producing these objects:

• ResourceFactory takes an absolute URL and returns a Resource object.
  • Each implementation supports a different access scheme (e.g. file system, HTTP, etc.)
• ArchiveOpener takes a Resource object and converts it into a Container, e.g.
  1. A FileResourceFactory takes a file:// URL to a ZIP file, to provides access to the raw ZIP file bytes.
  2. The ZIPArchiveOpener takes a Resource to a ZIP file and converts it to a ZIPContainer.
• AssetRetriever combines a list of ResourceFactory and ArchiveOpener instances to convert absolute URLs into an Asset instance.
• The PublicationOpener takes an Asset and creates a Publication instance using a PublicationParser.

Some relevant documentation can be found here:

• https://github.com/readium/kotlin-toolkit/blob/develop/docs/guides/getting-started.md#data-models
• https://github.com/readium/kotlin-toolkit/blob/develop/docs/guides/open-publication.md

[chocolatkey]

Work has begun on the v3 URL helpers, in #139