From bdcfe42a1e5438eec4dde2b38f9ea61bc76e8d68 Mon Sep 17 00:00:00 2001 From: Mark Sinclair Date: Tue, 8 Nov 2022 11:33:16 +0000 Subject: [PATCH] Add docs and diagrams --- .../examples/docs/packet_format.svg | 4 + sdk/typescript/examples/docs/packet_jpeg.svg | 4 + .../examples/docs/packet_string.svg | 4 + sdk/typescript/examples/docs/sphinx.svg | 4 + sdk/typescript/examples/docs/sphinx2.svg | 4 + sdk/typescript/examples/docs/worker.svg | 4 + sdk/typescript/examples/plain-html/README.md | 92 ++--------------- .../README.md | 99 +++++-------------- 8 files changed, 57 insertions(+), 158 deletions(-) create mode 100644 sdk/typescript/examples/docs/packet_format.svg create mode 100644 sdk/typescript/examples/docs/packet_jpeg.svg create mode 100644 sdk/typescript/examples/docs/packet_string.svg create mode 100644 sdk/typescript/examples/docs/sphinx.svg create mode 100644 sdk/typescript/examples/docs/sphinx2.svg create mode 100644 sdk/typescript/examples/docs/worker.svg diff --git a/sdk/typescript/examples/docs/packet_format.svg b/sdk/typescript/examples/docs/packet_format.svg new file mode 100644 index 0000000000..9cb2bfb6eb --- /dev/null +++ b/sdk/typescript/examples/docs/packet_format.svg @@ -0,0 +1,4 @@ + + + +
Binary Chat App Message
Binary Chat App Message
kind
(uint8)
kind...
header_size
(uint64)
header_size...
headers
(UTF-8 string as uint8 byte array of size header_size)
headers...
data
(uint8 byte array)
data...Text is not SVG - cannot display \ No newline at end of file diff --git a/sdk/typescript/examples/docs/packet_jpeg.svg b/sdk/typescript/examples/docs/packet_jpeg.svg new file mode 100644 index 0000000000..324994c49f --- /dev/null +++ b/sdk/typescript/examples/docs/packet_jpeg.svg @@ -0,0 +1,4 @@ + + + +
Chat App Binary Message (JPEG image)
Chat App Binary Message (JPEG image)
1
1
00 00 00 00 00 00 00 32
00 00 00 00 00 00 00 32
'{"filename": "test.jpeg", mimeType: "image/jpeg"}'
...
'{"filename": "test.jpeg", mimeType: "image/jpeg"}'...
d8 ff ed ff 84 00 ...
d8 ff ed ff 84 00 ...Text is not SVG - cannot display \ No newline at end of file diff --git a/sdk/typescript/examples/docs/packet_string.svg b/sdk/typescript/examples/docs/packet_string.svg new file mode 100644 index 0000000000..25f4421bf4 --- /dev/null +++ b/sdk/typescript/examples/docs/packet_string.svg @@ -0,0 +1,4 @@ + + + +
Chat App String Message
Chat App String Message
0
0
0
0
(not present)
(not present)
"Hello world"
65 48 6c 6c 20 6f 6f 77 6c 72 0a 64
"Hello world"...Text is not SVG - cannot display \ No newline at end of file diff --git a/sdk/typescript/examples/docs/sphinx.svg b/sdk/typescript/examples/docs/sphinx.svg new file mode 100644 index 0000000000..d01a0d3946 --- /dev/null +++ b/sdk/typescript/examples/docs/sphinx.svg @@ -0,0 +1,4 @@ + + + +
Encrypted wrapper with gateway <=> client long-term session key
Encrypted wrapper with gateway <=> client long-term session key
Sphinx Packet
Sphinx Packet
Mixnode 1 Layer
Mixnode 1 Layer
Mixnode 2 Layer
Mixnode 2 Layer
Mixnode 3 Layer
Mixnode 3 Layer
Egress Gateway Layer
Egress Gateway Layer
End-to-end encryption with ephemeral key (only known to chat app, so gateway can't view payload)
End-to-end encryption with ephemeral key (only known to chat app, so gateway can't view payload)
Binary Chat App Message
Binary Chat App Message
kind
(uint8)
kind...
header_size
(uint64)
header_size...
headers
(UTF-8 string as uint8 byte array of size header_size)
headers...
data
(uint8 byte array)
data...Text is not SVG - cannot display \ No newline at end of file diff --git a/sdk/typescript/examples/docs/sphinx2.svg b/sdk/typescript/examples/docs/sphinx2.svg new file mode 100644 index 0000000000..0552bd9585 --- /dev/null +++ b/sdk/typescript/examples/docs/sphinx2.svg @@ -0,0 +1,4 @@ + + + +
Encrypted wrapper with gateway <=> client long-term session key
Encrypted wrapper with gateway <=> client long-term session key
Sphinx Packet
Sphinx Packet
Mixnode 1 Layer
Mixnode 1 Layer
Mixnode 2 Layer
Mixnode 2 Layer
Mixnode 3 Layer
Mixnode 3 Layer
Egress Gateway Layer
Egress Gateway Layer
End-to-end encryption with ephemeral key (only known to chat app, so gateway can't view payload)
End-to-end encryption with ephemeral key (only known to chat app, so gateway can't view payload)
Binary Chat App Message
Binary Chat App Message
string message converted as UTF-8 to uint8 byte array
(uint8 byte array)
string message converted as UTF-8 to uint8 byte array...Text is not SVG - cannot display \ No newline at end of file diff --git a/sdk/typescript/examples/docs/worker.svg b/sdk/typescript/examples/docs/worker.svg new file mode 100644 index 0000000000..c9e4f662d1 --- /dev/null +++ b/sdk/typescript/examples/docs/worker.svg @@ -0,0 +1,4 @@ + + + +
index.js
index.js
const nym = await createNymMixnetClient();
const nym = await createNymMixnetClient();
worker.js
worker.js
websocket
websocket
WASM
WASM
MIX
2
MIX...
MIX
1
MIX...
MIX
3
MIX...
GW
GW
mixnet topology
mixnet topology
Nym Mixnet Directory
Nym Mixnet Directory
Main browser thread
Main browser th...
Web Worker thread
Web Worker thre...
Message sent to worker
Message sent...
onmessage
onmessage
class ClientWrapper
class ClientWra...
interface IWebWorker {
  start () => {...},
  sendTextMessage () => {...}
  sendBinaryMessage () => {...}
}
interface IWebWorker {...
events
events
client
client
events
events
interface IWebWorker {
  start () => {...},
  sendTextMessage () => {...}
  sendBinaryMessage () => {...}
}
interface IWebWorker {...
interface IWebWorkerEvents {
  subscribeToLoaded (handler) => {...}
  subscribeToConnected (handler) => {...}
  subscribeToTextMessageReceivedEvent (handler) => {...}
  subscribeToBinaryMessageReceivedEvent (handler) => {...}
}
interface IWebWorkerEvents {...
onmessage
onmessage
Event sent to main thread
Event sent to...
nym.sendTextMessage("Hello World", recipient)
nym.sendTextMessage("Hello World", recipient)
handleTextMessageReceived( { payload } ) {
  console.log('Got string message: ', payload)
}
handleTextMessageReceived( { payload } ) {...Text is not SVG - cannot display \ No newline at end of file diff --git a/sdk/typescript/examples/plain-html/README.md b/sdk/typescript/examples/plain-html/README.md index 490d88f27a..cd071de5ef 100644 --- a/sdk/typescript/examples/plain-html/README.md +++ b/sdk/typescript/examples/plain-html/README.md @@ -1,98 +1,26 @@ -# Example with React + Typescript + Webpack 5 + MUI +# HTML Nym Mixnet Chat App -An example of using default Webpack and Typescript settings with React and MUI, including theming. +This is an example of using the Nym Mixnet to send text chat messages, with optional binary file attachments. You can use this example as a seed for a new project. -Remember to build the dependency packages from the root of this repo by running: +Try out the chat app by running: ``` yarn -yarn build +yarn start ``` -If you need to make changes to the dependency packages, you can run `yarn watch` in that package to watch for chagnes and build them. This project will pick up the changes in the built package and hot-reload / recompile. +## How does it work? -## Features +The Nym Mixnet Client runs a [Web Worker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) that wraps +a WASM library that builds and encrypts Sphinx packets in the browser to send over the Nym mixnet: -### Yarn workspaces +![Sphinx packet](../docs/worker.svg) -Packages from `ts-packages` are shared using Yarn workspaces. Make sure you add you new project to [package.json](../../package.json) to use the shared packages. +The WASM code encrypts each layer of the Sphinx packet in the browser, before sending the Sphinx packet over a websocket to the ingress gateway: -> ⚠️ **Warning**: Yarn workspaces will share all dependencies between projects and works by falling back to parent directories until a `node_modules` directory is found. So be careful when messing around with `node_modules` and resolution, because unexpected things could happen - for example, if you do not run `yarn` from the root and you have a `node_modules` in a directory that is a parent of the directory where you checkout out this repository, that `node_modules` will be used for resolving packages 🙀. +![Sphinx packet](../docs/sphinx2.svg) -### Typescript -Shared Typescript config is in [tsconfig.json](./tsconfig.json), with specific production settings in [tsconfig.prod.json](./tsconfig.prod.json) that: -- exclude Storybook stories and Jest tests -- do not output typing `*.d.ts` files - -### Webpack - -Inherit config for Webpack 5 with additional tweaks including: - -- favicon generation from [favicon asset files](../../../../assets/favicon/favicon.png) -- asset handling (svg, png, fonts, css, etc) -- minification - -The development settings include: - -- `ts-loader` for quick transpilation -- threaded type checking using `tsc` -- hot reloading using `react-refresh` - -### Storybook - -Storybook is available in [@nymproject/react](../../../../ts-packages/react-components/src/stories/Introduction.stories.mdx) and can be run using `yarn storybook`. - -### MUI and theming - -The [Nym theme](../mui-theme/src/theme/theme.ts) provides a theme provider that you can add as follows: - -```typescript jsx -export const App: React.FC = () => ( - - - - - -); - -export const AppTheme: React.FC = ({ children }) => { - const { mode } = useAppContext(); - - return {children}; -}; - -export const Content: React.FC = () => { -... -} -``` - -And augment typings for the Theme by adding [mui-theme.d.ts](./src/theme/mui-theme.d.ts): - -```typescript -import { Theme, ThemeOptions, Palette, PaletteOptions } from '@mui/material/styles'; -import { NymTheme, NymPaletteWithExtensions, NymPaletteWithExtensionsOptions } from '@nymproject/mui-theme'; - -declare module '@mui/material/styles' { - interface Theme extends NymTheme {} - interface ThemeOptions extends Partial {} - interface Palette extends NymPaletteWithExtensions {} - interface PaletteOptions extends NymPaletteWithExtensionsOptions {} -} -``` - -Adding the above, means that any component now has the correct typings, for example, below the Nym palette interface is available for all MUI `Theme` instances with code completion for VSCode and IntelliJ: - -```typescript jsx -import { Typography } from '@mui/material'; - -... - - theme.palette.nym.networkExplorer.mixnodes.status.active }}> - The quick brown fox jumps over the white fence - - -``` diff --git a/sdk/typescript/examples/react-webpack-with-theme-example/README.md b/sdk/typescript/examples/react-webpack-with-theme-example/README.md index 490d88f27a..4afa796f9b 100644 --- a/sdk/typescript/examples/react-webpack-with-theme-example/README.md +++ b/sdk/typescript/examples/react-webpack-with-theme-example/README.md @@ -1,98 +1,45 @@ -# Example with React + Typescript + Webpack 5 + MUI +# React Nym Mixnet Chat App -An example of using default Webpack and Typescript settings with React and MUI, including theming. +This is an example of using the Nym Mixnet to send text chat messages, with optional binary file attachments. -You can use this example as a seed for a new project. +You can use this example as a seed for a new project, and it uses: -Remember to build the dependency packages from the root of this repo by running: +- React +- Webpack +- WASM +- Web Workers +- Material UI (MUI) + +Try out the chat app by running: ``` yarn -yarn build +yarn start ``` -If you need to make changes to the dependency packages, you can run `yarn watch` in that package to watch for chagnes and build them. This project will pick up the changes in the built package and hot-reload / recompile. +## How does it work? -## Features +The Nym Mixnet Client runs a [Web Worker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) that wraps +a WASM library that builds and encrypts Sphinx packets in the browser to send over the Nym mixnet: -### Yarn workspaces +![Web worker](../docs/worker.svg) -Packages from `ts-packages` are shared using Yarn workspaces. Make sure you add you new project to [package.json](../../package.json) to use the shared packages. +The chat app has a custom payload that sends either string messages or binary files: -> ⚠️ **Warning**: Yarn workspaces will share all dependencies between projects and works by falling back to parent directories until a `node_modules` directory is found. So be careful when messing around with `node_modules` and resolution, because unexpected things could happen - for example, if you do not run `yarn` from the root and you have a `node_modules` in a directory that is a parent of the directory where you checkout out this repository, that `node_modules` will be used for resolving packages 🙀. +![Packet format](../docs/packet_format.svg) -### Typescript +String messages are sent like this: -Shared Typescript config is in [tsconfig.json](./tsconfig.json), with specific production settings in [tsconfig.prod.json](./tsconfig.prod.json) that: +![Packet format - string](../docs/packet_string.svg) -- exclude Storybook stories and Jest tests -- do not output typing `*.d.ts` files +Files include the filename and mime-type, so that the recipient can download them with the correct name: -### Webpack +![Packet format - binary](../docs/packet_jpeg.svg) -Inherit config for Webpack 5 with additional tweaks including: +The WASM code encrypts each layer of the Sphinx packet in the browser, before sending the Sphinx packet over a websocket to the ingress gateway: -- favicon generation from [favicon asset files](../../../../assets/favicon/favicon.png) -- asset handling (svg, png, fonts, css, etc) -- minification +![Sphinx packet](../docs/sphinx.svg) -The development settings include: -- `ts-loader` for quick transpilation -- threaded type checking using `tsc` -- hot reloading using `react-refresh` -### Storybook -Storybook is available in [@nymproject/react](../../../../ts-packages/react-components/src/stories/Introduction.stories.mdx) and can be run using `yarn storybook`. - -### MUI and theming - -The [Nym theme](../mui-theme/src/theme/theme.ts) provides a theme provider that you can add as follows: - -```typescript jsx -export const App: React.FC = () => ( - - - - - -); - -export const AppTheme: React.FC = ({ children }) => { - const { mode } = useAppContext(); - - return {children}; -}; - -export const Content: React.FC = () => { -... -} -``` - -And augment typings for the Theme by adding [mui-theme.d.ts](./src/theme/mui-theme.d.ts): - -```typescript -import { Theme, ThemeOptions, Palette, PaletteOptions } from '@mui/material/styles'; -import { NymTheme, NymPaletteWithExtensions, NymPaletteWithExtensionsOptions } from '@nymproject/mui-theme'; - -declare module '@mui/material/styles' { - interface Theme extends NymTheme {} - interface ThemeOptions extends Partial {} - interface Palette extends NymPaletteWithExtensions {} - interface PaletteOptions extends NymPaletteWithExtensionsOptions {} -} -``` - -Adding the above, means that any component now has the correct typings, for example, below the Nym palette interface is available for all MUI `Theme` instances with code completion for VSCode and IntelliJ: - -```typescript jsx -import { Typography } from '@mui/material'; - -... - - theme.palette.nym.networkExplorer.mixnodes.status.active }}> - The quick brown fox jumps over the white fence - - -```