ShareEncoding

it.grypho.scala.leonardo.cli.ShareEncoding
object ShareEncoding

The URL-fragment format a session travels in, shared by every producer of one (issue F_0045).

It lives here, in the module that owns Session.script, because two components need the same answer and neither can reach the other. web.ShareLink builds the fragment in the browser; docs.Lesson builds one on the JVM to put a "run this" link beside an executed lesson transcript. web is a Scala.js project and the documentation helper is a JVM one, so the only place both can import from is the cross-built repl module — and a second hand-maintained encoder is exactly the drift ColorSchemeNamesTest exists to prevent elsewhere.

encodeComponent is encodeURIComponent, re-implemented rather than delegated, and that is the substance of this object. The browser has the function as a global and the JDK does not: java.net.URLEncoder.encode is not the same thing — it is application/x-www-form-urlencoded, which emits + for a space, and decodeURIComponent returns that + as a literal plus sign. A script encoded that way reloads as a valid but different session, every space in it silently corrupted, which is the confidently-wrong failure this project declines everywhere.

So the unreserved set is spelled out and everything else is percent-encoded from its UTF-8 bytes. UTF-8 is hand-rolled from code points rather than taken from String.getBytes(UTF_8): this file compiles for both platforms, and a charset's breadth of support is precisely the kind of difference that compiles everywhere and diverges at run time — the DoubleRender lesson. Hex digits are upper case, as the browser's own function emits them, so a fragment built here is byte-identical to one built by the page.

Decoding is not here. decodeURIComponent is only ever needed in the browser, where it exists and is the authority; re-implementing it would add a second thing to keep in step for no caller. ShareLinkTest checks the two agree by decoding this encoder's output with the real one.

Published API since F_0236 (it was private[leonardo]): the course repository builds its run links through the released leonardo-repl, and a copy of the format there would be a second definition to drift. Public, MiMa now protects it. The contract a caller relies on: a fragment is Key followed by encodeURIComponent of a Session.script, hex in upper case, and a session longer than MaxFragment encoded characters yields no link at all (a Left), never a truncated one. Append it to an /app/ URL after #.

Attributes

Graph
Supertypes
class Object
trait Matchable
class Any
Self type

Members list

Value members

Concrete methods

def encodeComponent(s: String): String

Percent-encodes s exactly as JavaScript's encodeURIComponent does.

Percent-encodes s exactly as JavaScript's encodeURIComponent does.

Value parameters

s

the text to encode

Attributes

Returns

the encoded text, safe to carry in a URL fragment

def fragmentFor(script: String): Either[String, String]

The fragment for a session script, or a message when it is too long to carry.

The fragment for a session script, or a message when it is too long to carry.

Value parameters

script

the session script, from Session.script

Attributes

Returns

the fragment text including its key, or why it could not be built

Concrete fields

val Key: String

The fragment key, so the encoding can gain neighbours without becoming ambiguous.

The fragment key, so the encoding can gain neighbours without becoming ambiguous.

Attributes

val MaxFragment: Int

Browsers do not agree on a URL length limit and the practical floor is around 64k, so a long session is refused rather than truncated: half a script would :load as a valid but different session, which is worse than a link that plainly says it is too big.

Browsers do not agree on a URL length limit and the practical floor is around 64k, so a long session is refused rather than truncated: half a script would :load as a valid but different session, which is worse than a link that plainly says it is too big.

Attributes