Improve the comment watermark format

[0x2b3bfa0]

Watermarks are invisible strings inserted on CML comments¹ so they can be differentiated from comments created by users. Our current watermark format is all but uniquely identifiable, and should probably be updated.

cml/src/cml.js

Line 181 in 7bd9257

: '';

Note that watermarks use a blank image instead of an HTML comment, because not all forges support the latter in their respective flavours of Markdown.

Proposal

Use the image description to store arbitrary data encoded as Base64 (e.g. useful for live metrics) and the image link to point to an invisible, tiny image in a static host of our choice.

![eyJrZXkiOiAidmFsdWUifQ==](https://cml.dev/9b0e332381649d87112c181dae1568640ea055b3100e5253d86410d276db8af9/pixel.gif) 

Precursors

• Integrate cml publish with cml send-comment #1026 (comment)

Footnotes

1. E.g. created by running cml send-comment ↩

[0x2b3bfa0]

Parsing data in watermarks

Simple use case of embedding machine-readable metrics into reports; hacky¹ but functional.

import base64
import commonmark
import json


WATERMARK = "https://cml.dev/9b0e332381649d87112c181dae1568640ea055b3100e5253d86410d276db8af9/pixel.gif"


def extract_metrics(report: str) -> any:
    for node, _ in commonmark.Parser().parse(report).walker():
        if node.t == "image" and node.destination == WATERMARK:
            return json.loads(base64.b64decode(node.first_child.literal))


if __name__ == "__main__":
    with open("report.md", "r") as report:
        print(extract_metrics(report.read()))

Footnotes

1. Note that the commonmark package is deprecated; a production-ready example would look slightly different and use another library. ↩

[casperdcl]

Use the image description to store arbitrary data encoded as Base64

🤢

[0x2b3bfa0]

We can also use Unicode zero-width watermarks: 🤔

• https://doi.org/10.1109/iThings-GreenCom-CPSCom-SmartData-Cybermatics50389.2020.00116
• https://github.com/offdev/zwsp-steg-js & https://github.com/enodari/zwsp-steg-py
• https://mayadevbe.me/posts/zw_steg

[tasdomas]

Looks like there are several ways to do this:

1. Add a base64 string to the image alt text: ![CML watermark <base64 snipped>](https://raw.githubusercontent.com/iterative/cml/master/assets/watermark.svg)

2. Add a base64 string to the image title: ![CML watermark](https://raw.githubusercontent.com/iterative/cml/master/assets/watermark.svg "base64")z

3. Add a CML logo with a link to https://cml.dev/ and the link title being base64 encoded data: [![CML](https://cml.dev/logo.png)](https://cml.dev "base64")

4. There's also the option of using zero-width unicode characters, but this feels a tad hacky

Also, I think it looks a bit amateurish to include resources hosted by github (the watermark svg) - we should at least host it ourselves.

[0x2b3bfa0]

it looks a bit amateurish to include resources hosted by github (#1076) - we should at least host it ourselves

Playing devil's advocate: hosting it on GitHub is a good guarantee it can't be used for tracking. 🤷🏼‍♂️

[tasdomas]

Playing devil's advocate: hosting it on GitHub is a good guarantee it can't be used for tracking. 🤷🏼‍♂️

That's putting a lot of faith in github :)

[0x2b3bfa0]

There's also the option of using zero-width unicode characters, but this feels a tad hacky

I proposed this because as David Ortega pointed out a few days ago, the current image-based watermarks are visible at the bottom of mail notifications. Yes, it's “a little bit” more hacky. 😄

Example

[tasdomas]

Option 1

Option 2

Option 3
(obviously the logo would need to be smaller)

[0x2b3bfa0]

Option $e$¹

Footnotes

1. https://en.wikipedia.org/wiki/E_(mathematical_constant) ↩

[0x2b3bfa0]

How it looks in email notifications:

[tasdomas]

Option $e$ and 3 appear to be most viable

[casperdcl]

1. poor rendering: could this be fixed by using PNG instead of SVG?
2. poor URL: I'd be fine with replacing raw.githubusercontent.com/iterative/cml/master/assets -> static.iterative.ai/cml
3. guaranteeing no hidden tracking: the above (static.iterative.ai) is open sourced at https://github.com/iterative/static to prove no nefarious activity
4. base64: why? what is the use case? What metadata do we actually need to inject? If it's just a comment ID then plaintext | urllib.parse.quote is enough?

[0x2b3bfa0]

urllib.parse.quote

hashlib 🤺

[tasdomas]

4. base64: why? what is the use case? What metadata do we actually need to inject? If it's just a comment ID then plaintext | `urllib.parse.quote` is enough?

base64 is not strictly necessary - my current thinking is to store the watermark scope with the watermark.

[dacbd]

completed
#1173
#1309