element-hq / hydrogen-web

Lightweight matrix client with legacy and mobile browser support

Hydrogen

A minimal Matrix chat client, focused on performance, offline functionality, and broad browser support. This is work in progress and not yet ready for primetime. Bug reports are welcome, but please don't file any feature requests or other missing things to be on par with Element Web.

Goals

Hydrogen's goals are:

• Work well on desktop as well as mobile browsers
• UI components can be easily used in isolation
• It is a standalone webapp, but can also be easily embedded into an existing website/webapp to add chat capabilities.
• Loading (unused) parts of the application after initial page load should be supported

For embedded usage, see the SDK instructions.

If you find this interesting, come and discuss on #hydrogen:matrix.org.

How to use

Hydrogen is deployed to hydrogen.element.io. You can also deploy Hydrogen on your own web server:

1. Download the latest release package.
2. Extract the package to the public directory of your web server.
3. If this is your first deploy:

   1. copy config.sample.json to config.json and if needed, make any modifications (unless you've set up your own sygnal instance, you don't need to change anything in the push section).

   2. Disable caching entirely on the server for:

      • index.html
      • sw.js
      • config.json
      • All theme manifests referenced in the themeManifests of config.json, these files are typically called theme-{name}.json.

      These resources will still be cached client-side by the service worker. Because of this; you'll still need to refresh the app twice before config.json changes are applied.

Set up a dev environment

You can run Hydrogen locally by the following commands in the terminal:

• yarn install (only the first time)
• yarn start in the terminal

Now point your browser to http://localhost:3000. If you prefer, you can also use docker.

PS: You need nodejs, running yarn on top of any other js platform is not supported.

FAQ

Some frequently asked questions are answered here.

hydrogen-web's Issues

Add avatars and display names to timeline

Unread state and notification in room list

• show unread state in room list. A function should be passed to the session to determine whether an event can be displayed and hence should cause a room to be marked as unread. This will check in the viewmodel whether there is a tile for it.
• show notification count; use highlight_count and notification_count in sync response
• sort room list by recent activity and notification count.

Sync halts with AbortError after app is backgrounded for some minutes on Android.

Status bar says: Sync failed because of AbortError: The user aborted a request.

Sync errors during initial sync are hidden in SessionLoadViewModel

Cleanup: don't return promise for write requests from store

As it doesn't make sense to await them, we should await the transaction rather. This can create a lot of unnecessary promises during a big sync response.

Installed PWA doesn't seem to load if server is unavailable

Request seems to make it to service worker, which does a failing request, but we don't seem to fallback to cache?

Provide API documentation

http://clenemt.github.io/docdash/

[Feature] Guest Login

Guest Login will be nice

Finetune font-sizes and spacing to element-web

Add structured logging

See https://gist.github.com/bwindels/1632a4254627242ca9a7c38f522bbf0b and https://github.com/bwindels/timeline-log-viewer and bwindels/logtree branch for details

• finish logger
• add logs
• on error, expose button that allows to download logs. To make downloading the logs work on edge mobile, use http://jsbin.com/metacocuge/edit?html,js,output

[Bug] Element Theme bricks Chat Layout

Align is only on the left side :( looks strange for me

File & image uploads/downloads

• show images in timeline
• automatically load images (when in view?), have service worker cache them.
• show files in timeline, allow download
• upload files, storing them locally in indexedb before sending

SSO Login

SAML / OpenID Connect login support

Sort low-priority rooms at the bottom of the room list

comes in as account_data:

{
  "events": [
    {
      "type": "m.tag",
      "content": {
        "tags": {
          "m.lowpriority": {}
        }
      }
    }
  ]
}

Sync failed because of SyntaxError: Unexpected token < in JSON at position 0

With response body:

content-type: text/html

<html><body><h1>429 Too Many Requests</h1>
No server is available to handle this request.
</body></html>

Sync halts when /sync returns 429, 500

Heroes don't handle member leave events well

{
  "type": "m.room.member",
  "sender": "@bruno1:localhost",
  "content": {
    "membership": "leave"
  },
  "state_key": "@bruno1:localhost",
  "origin_server_ts": 1598466841459,
  "unsigned": {
    "replaces_state": "$JGaEFO-E10_WO8ii6gHAtb5kYRRqFIGa15RZqH23Ntc",
    "prev_content": {
      "membership": "join",
      "displayname": "Problembär Bruno",
      "avatar_url": "mxc://localhost/lsZyAmPfrxGYbtQTUdXWenjC"
    },
    "prev_sender": "@bruno1:localhost",
    "age": 83
  },
  "event_id": "$DY_s7cDSr_HvgyjQe183kSYeyxHFcRLAGbiX8Vepduo"
}

Synapse doesn't send displayname nor avatar_url, hydrogen updates the member without these fields and the sort function in Heroes.applyChanges fails, bricking opening a session.

Throwing while adding to the timeline will result in all the messages in the backfill or load-from-storage missing from the timeline

E.g. element-hq/element-meta#1390 was an image in with no content.url which threw in ImageTile, blocking 10 or so messages from ever being displayed, without a clear error.

We should have a mechanism where we render the tile with errorToDOM or something similar.

Also we should have a safe function to read fields/paths of an event, and act predictably when that field is missing/wrong type/ ...

Make sure initial syncs that take longer than 30s work

Room list ordering isn't always stable

Sometimes when you close a room/go to another one that was unread, the room you left goes all the way to the bottom or somewhere close.

One reason could be that the properties of the room have changed without causing a rerendering somehow, so what you see isn't what is being sorted anymore. Unsure how that could happen though.

Another reason could be that lastMessageTimestamp ends up something else than null or a number (e.g. undefined).

Redactions

I don't think we need the "relations infrastructure" for this, as we when we receive a redaction, we either:

• have the redacted event in storage, and we remove the fields, etc ...
• don't have the redacted event. We don't need to do anything, and if we fetch it in the future, we will get the already redacted version.

Accept invites

• invite_state doesn't update over /sync
• can we reuse room summary? need to clear when joining
• rely on filter operator to split membership=join from membership=invite?

Can't load session with rooms that have no events

Because of matrix-org/synapse#7083

Relations

• edits
• reactions
• replies

Also see https://github.com/vector-im/hydrogen-web/blob/master/doc/impl-thoughts/RELATIONS.md

Session backup (read-only)

Implement session backup so we can read encrypted history from before we logged in.

• derive AES key from passphrase using pbkdf2 (https://github.com/uhoreg/matrix-doc/blob/ssss/proposals/1946-secure_server-side_storage.md)
  • use https://github.com/brix/crypto-js/blob/develop/src/pbkdf2.js for IE11? or look if we can use https://www.npmjs.com/package/pbkdf2 which can use the native sha512 hashing which should be supported in IE11. Or maybe not.
• decrypt session backup private key in m.megolm_backup.v1 using AES
• implement session backup, see https://github.com/matrix-org/matrix-doc/blob/ce286dac02ca79e505592df58a658a63408497ff/proposals/1219-storing-megolm-keys-serverside.md#auth_data-backup-versions
• prompt to enter passphrase when a session id is missing
• fetch a missing session key from backup once backup is enabled

As we don't have a concept of trust yet, we will only verify that the backup came from a session we trust by the fact that you enter the 4S passphrase, which gives us the session backup key.

[Feature] Link selected Channel as Link / URI

possible website embed possible?

Accept invites

• invite_state doesn't update over /sync
• can we reuse room summary? need to clear when joining
• rely on filter operator to split membership=join from membership=invite?

Sending unsent messages stops after server rate-limits us

Add support for IE11

• compile down to ES5
• include all needed polyfills
• implement XHR request handling (instead of fetch)
• initial loading message isn't rendered for some reason. Problem with bindings?
• find solution for usage of DOMElement.closest
• fix likely storage errors
• Element.remove method not supported

Messages are sent out of order

used to happen only after we got rate limited and we had to refresh. Recently I've seen it happen when only sending 2 messages in fresh page load.

Add IE11 as supported platform for Javascript

Implements #1

Note that CSS will be fixed in another PR, this PR is just JS.

Room avatar doesn't update in room list and room header when uploading one

Sync failed because of TypeError: Failed to fetch

should have been converted to a ConnectionError?
This is in Chromium Version 83.0.4103.116 (Developer Build) Fedora Project (64-bit)

[Feature] small Config

e.g. configure for HS URL & other stuff to toggle

Sync after reconnecting can stall

After the /versions response comes back successfully to the Reconnector, sync will be retried. If the server is not fully ready yet to respond to sync requests, this can stall (seemingly) forever with "Trying to reconnect now ...". Not sure how this can happen as the sync request has a timeout of of 30+80s now... I waited for what I think was longer than 1min50s.

End-to-end encryption

TODO

• have a basic idea of how we would build a wasm/asm.js version of the sdk. See https://github.com/vector-im/crypto-wrapper-hydrogen/, but deciding not to go this way, mainly because it's a PITA to debug and because we will need more flexibility to make E2EE fast enough in IE11 than the sdk can offer (run olm decryption in a web worker, ...), and asm.js seems very slow in IE11 so the fewer asm.js (e.g. libolm) we can run, the better.
• persist olm account in session store
• upload identity keys and OTKs after login
• sync device_one_time_keys_count and upload more OTKs if needed
• device tracking in e2ee rooms
• decrypt olm messages, persisting olm sessions
• handle to_device messages and decrypt them
• store room keys shared over olm as inbound megolm sessions
• decrypt megolm encrypted messages
• don't remove olmAccount and areDeviceKeysUploaded keys from session store when clearing the session, otherwise e2ee keys would rotate while keeping same device id/access token. Important to do this before doing a release!
• encrypt olm messages over to_device
• start new megolm outbound sessions, store them and share them over olm with required devices
• send megolm encrypted messages
• mark events as verified
• rotate megolm session when member changes , and share our outbound session at the current ratchet position with new members?
• make it fast on IE11
• make sure decryption errors don't block other events from being decryption, or block the client.
• block multiple open sessions
• write unit tests

Remaining questions/remarks wrt to rust-sdk (not relevant anymore atm)

• how to implement CryptoStore? Try to anticipate all the data that will be requested and preload a memory store? Or actually implement something that calls into idb? If this breaks, it would be painful to debug. E.g. before we call receive_sync_response, go over all to_device messages encrypted with olm and get their sender_key.
• One way or another, I don't think it will be very feasible to have the OlmMachine live longer than one of our txns.
• sync responses will be parsed and loaded into memory twice :(

Sync failed because of Error: Unknown Fragment id 10

after catchup sync on Android device after opening the app. This was right after upgrading to 0.0.21, with having synced this session only a few minutes before with 0.0.20

Sending a message isn't retried until refresh when server responds with 500

Show display name and avatar on messages

We need to store either the most recent m.room.member eventId or the display name and avatar on an incoming event. We can have a FILO cache of x members for synced messages, and load a state event from store if it's not in there. But how do we handle filling gaps? How do we find out what the room state was at the beginning of the fragment we're trying to backfill (end, forward-fill, respectively).

Add url-based router for navigation

Structural persisted logging

• implement logger persisted in IDB
• reduce sync logging volume by setting loglevel in smart way
  • log catchup syncs in detail
  • log any sync taking over 1 second?
  • log device messages in detail always
  • log room ids in sync
  • only log detailed sync if there is a error
  • only log requests if they are >= 400
• log sending messages
• log opening a room
• log login
• log opening account
• add export/clear button in settings
• add button to upload to rageshake server

Join room

Join room from room directory & link.

This will allow hydrogen to be added to matrix.to as well

Get version from serviceworker

Rather than hardcode it in html, as html and service worker can be out of sync (especially on github pages)

failing to persist initial sync events and fragments

failing to persist initial sync on firefox with local "main" synapse on bruno2

I get a ton of:

Error: add on undefined failed: (name: TransactionInactiveError) (code: TransactionInactiveError) A request was placed against a transaction which is currently not active, or which is finished.

and no items in timelineEvents or timelineFragments are stored, presumably something is going wrong in the SyncWriter.
The error was not introduced in bwindels/fixconstrainterror-part2, and is already on master. Use git bisect to find out where it was introduced?

it's easy to repro on my local ff, just clear the bruno2 session and click on it to do an initial sync. the console is full of errors

Use handleEvent everywhere in DOM code

https://medium.com/@WebReflection/dom-handleevent-a-cross-platform-standard-since-year-2000-5bf17287fd38

Timeline does not update even though sync is running

Timeline stopped showing new incoming message. Clicking the room tile again (several times? can't remember) refreshed the timeline. Might have clicked the room tile quite a few times before and/or have scrolled up/filled gaps before this happened.

Confirmed sync was running with the devtools. No errors in the console.

Did something close the timeline (e.g. disposed the TimelineViewModel?) this is on bwindels/reconnect btw.

Style hydrogen somewhat similar to element-web

...

Render replies a little bit better

Show replied to text as quoted, until we support them properly.

Unread state and notification in room list

• show unread state in room list. A function should be passed to the session to determine whether an event can be displayed and hence should cause a room to be marked as unread. This will check in the viewmodel whether there is a tile for it.
• mute toggle per room
• show notification count; use highlight_count and notification_count in sync response
• sort room list by recent activity and notification count.

Constraint error on byEventId during sync

Error in status bar:

Sync failed because of Error: wrapped DOMException: (name: ConstraintError) (code: ConstraintError) Unable to add key to index 'byEventId': at least one key does not satisfy the uniqueness requirements.

In console:

Uncaught (in promise) Error: add on undefined failed: (name: ConstraintError) (code: ConstraintError) Unable to add key to index 'byEventId': at least one key does not satisfy the uniqueness requirements.
    at Store.add (brawl.js:3685)
8brawl.js:3685 Uncaught (in promise) Error: add on undefined failed: (name: AbortError) (code: AbortError) The transaction was aborted, so the request cannot be fulfilled.
    at Store.add (brawl.js:3685)
brawl.js:3676 Uncaught (in promise) Error: put on undefined failed: (name: AbortError) (code: AbortError) The transaction was aborted, so the request cannot be fulfilled.
    at Store.put (brawl.js:3676)
brawl.js:686 unable to commit sync tranaction
_syncRequest @ brawl.js:686