Design architecture, write specification, make a plan

lukebarnard1 commented 6 years ago

Architecture

To wrap the js-sdk, each event emitted by it will be handled by the store as an action. Each action will update the store state accordingly with a set of reducers.

Many actions will reduce state in a similar fashion; updating the stored values for matrix state. All state will be copied from the js-sdk to prevent bugs from state changing without an action having been fired. This has many advantages but one major disadvantage is memory footprint. The plan is to replace this wrapper with a proper matrix-redux-store that has its own logic for handling the /sync response, effectively replacing stateful parts of the js-sdk but leaving HTTP API wrappers intact.

Apps wanting multi-account support for their app should simply create multiple stores; the accounts should be effectively sandboxed.

Glossary

User: The currently logged-in user.

Store structure

Store key	Type	Description
mrw.wrapped_api.login.credentials	Object	The credentials of the User.
mrw.wrapped_api.login.credentials.userId	String	The user ID of the User.
mrw.wrapped_api.login.credentials.accessToken	String	The access token of the User.
mrw.wrapped_state.sync	Object	The sync data for the current session.
mrw.wrapped_state.sync.state	String	The sync state of the matrix client.
mrw.wrapped_state.rooms	Array	Rooms that the User has interacted with before.

lukebarnard1 commented 6 years ago

I've realised that redux apps will want to store non-matrix state in the same store under a different state key. This is still compatible with all of the above, but we leave the store creation to the app.

So this library will only expose:

A single matrix reducer (which is a keyed composition of several reducers)
Several action creators to create actions for the reducer

lukebarnard1 commented 6 years ago

To be specified:

[x] The action creator that will wrap emitted events of matrix-js-sdk
[x] The action creators that will wrap the API of matrix-js-sdk
[x] The reducers that will update mrw.* state in response to dispatched actions

lukebarnard1 commented 6 years ago

Action Creators

matrix-js-sdk events

The events will be as actions fairly simply:

{
    "type": "mrw.wrapped_event",
    "emittedType": emittedType,
    "emittedArgs": emittedArgs,
}

where:

type - the name-spaced action type (mrw = matrix-redux-wrap);
emittedType - the name of the event emitted (e.g. "Room.name");
emittedArgs- the arguments emitted.

The advantages of this are:

every action has the same structure;
one action creator for any emitted event.

and the disadvantages are:

individual actions don't have key-value pairs for the arguments, which isn't the most readable thing;
we have to specify each type of event; EventEmitter doesn't support a catch-all listener.

matrix-js-sdk Client-Server API

The API is exposed in a series of many Promise-returning functions that do some asynchronous work. These can easily be encapsulated in Asynchronous Action Creators, which are essentially actions that take the form:

    (dispatch) => { ... }

and when dispatched on the Redux store (which has the redux-thunk middleware applied), the function will be called with a reference to the dispatch function of the store, allowing it to be called asynchronously.

The three async actions that are:

a "pending" action, indicating that there is some work ongoing;
a "success" action, indicating that some work was successfully completed and
a "failure" action, indicating that some work has failed to complete due to an error.

These will be encapsulated in actions that resemble:

{
    "type": "mrw.wrapped_api.pending",
    "method": "login",
    "pendingState": pendingState,
    "id": "48ghdkh9"
}

where:

type is the name-spaced action type (mrw = matrix-redux-wrap);
method is the name of the function that will be called on the MatrixClient instance;
pendingState is the a useful way to pass state known at the point of calling the API;
id the request ID that links this pending action with a potential future "failure" or "success".

{
    "type": "mrw.wrapped_api.success",
    "method": "login",
    "result": { ... },
    "id": "48ghdkh9"
}

where:

type is the name-spaced action type (mrw = matrix-redux-wrap);
method is the name of the function called on the MatrixClient instance;
result is the value that the returned promise resolves to;
id the request ID that links this success with the previously emitted "pending" action.

{
    "type": "mrw.wrapped_api.failure",
    "method": "login",
    "error": new Error(':slight_frown:'),
    "id": "48ghdkh9"
}

where:

type is the name-spaced action type (mrw = matrix-redux-wrap);
method is the name of the function called on the MatrixClient instance;
error is the thrown value;
id the request ID that links this success with the previously emitted "pending" action.

lukebarnard1 commented 6 years ago

Closing due to progress being made, I shall make a big checklist of things that need to be done next 🙂

lukebarnard1 / matrix-redux-wrap