@rnzeus/heimdall-sdk 0.6.1 → 0.7.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +47 -5
- package/dist/core/connection/session/constants.d.ts +2 -0
- package/dist/core/connection/session/constants.js +9 -2
- package/dist/core/connection/socket/capabilities.d.ts +7 -0
- package/dist/core/connection/socket/capabilities.js +8 -0
- package/dist/core/connection/socket/connect-socket.js +15 -9
- package/dist/core/connection/socket/host-lines.d.ts +5 -0
- package/dist/core/connection/socket/host-lines.js +16 -0
- package/dist/core/connection/socket/host-message.d.ts +12 -0
- package/dist/core/connection/socket/host-message.js +62 -0
- package/dist/core/connection/socket/index.d.ts +2 -0
- package/dist/core/connection/socket/index.js +2 -0
- package/dist/core/connection/socket/secure-transport.js +4 -11
- package/dist/core/connection/socket/send-event.d.ts +2 -1
- package/dist/core/connection/socket/send-event.js +4 -2
- package/dist/core/frames/index.d.ts +43 -0
- package/dist/core/frames/index.js +140 -0
- package/dist/frames/index.d.ts +11 -0
- package/dist/frames/index.js +35 -0
- package/dist/noop/frames.d.ts +2 -0
- package/dist/noop/frames.js +1 -0
- package/dist/public/prompt/component.js +3 -3
- package/dist/public/prompt/local-network.d.ts +31 -0
- package/dist/public/prompt/local-network.js +34 -0
- package/dist/public/prompt/theme.d.ts +6 -1
- package/dist/public/prompt/theme.js +23 -21
- package/dist/public/prompt/ui/action-button.d.ts +2 -1
- package/dist/public/prompt/ui/action-button.js +14 -3
- package/dist/public/prompt/ui/footer.d.ts +5 -2
- package/dist/public/prompt/ui/footer.js +3 -4
- package/dist/public/prompt/ui/header.js +2 -2
- package/dist/public/prompt/ui/screen-recording.d.ts +8 -0
- package/dist/public/prompt/ui/screen-recording.js +40 -0
- package/dist/public/prompt/ui/status-line.d.ts +11 -0
- package/dist/public/prompt/ui/status-line.js +12 -0
- package/dist/public/prompt/use-connect-awaiter.d.ts +3 -2
- package/dist/public/prompt/use-connect-awaiter.js +55 -9
- package/dist/public/prompt/views/cloud-view.d.ts +3 -1
- package/dist/public/prompt/views/cloud-view.js +4 -2
- package/dist/public/prompt/views/connected-view.js +2 -1
- package/dist/public/prompt/views/manual-view.d.ts +5 -2
- package/dist/public/prompt/views/manual-view.js +4 -2
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/frames/index.d.ts +1 -0
- package/frames/index.js +1 -0
- package/metro/index.cjs +8 -2
- package/noop/frames.d.ts +1 -0
- package/noop/frames.js +1 -0
- package/package.json +22 -2
package/README.md
CHANGED
|
@@ -7,6 +7,7 @@ React Native client for **Heimdall** — a desktop debug inspector for dev and s
|
|
|
7
7
|
- **Zustand** — state snapshots per store, with the action that caused them
|
|
8
8
|
- **Console** — `console.*`, uncaught JS errors and unhandled promise rejections
|
|
9
9
|
- **App and device info** — version, build, environment, OS, model
|
|
10
|
+
- **Screenshots** — optional: the screen around a bug, with the taps on it, for bug reports
|
|
10
11
|
|
|
11
12
|

|
|
12
13
|
|
|
@@ -21,6 +22,7 @@ It is built for development and stage builds only and is off by default in produ
|
|
|
21
22
|
| `react-native-tcp-socket` | `>=6` | transport |
|
|
22
23
|
| `react-native-mmkv` | `>=3` | remembers the last connection |
|
|
23
24
|
| `zustand` | `>=3` | optional, only for the Zustand middleware |
|
|
25
|
+
| [`@rnzeus/heimdall-lens`](https://github.com/rnzeus/heimdall-lens) | `>=0.1` | optional, only for screenshots in bug reports |
|
|
24
26
|
|
|
25
27
|
`react-native-tcp-socket` and `react-native-mmkv` are native modules. With Expo you need a [development build](https://docs.expo.dev/develop/development-builds/introduction/) — Expo Go will not work.
|
|
26
28
|
|
|
@@ -127,6 +129,31 @@ A report can also start from one event — a request, a log line, a socket frame
|
|
|
127
129
|
|
|
128
130
|
Trackers are connected in the desktop app (Settings → Integrations); nothing extra is needed in your code. Adapters are open source: [`@rnzeus/heimdall-trackers`](https://github.com/rnzeus/heimdall-trackers).
|
|
129
131
|
|
|
132
|
+
## Screenshots in bug reports
|
|
133
|
+
|
|
134
|
+
A report can show the screen around the bug: what the tester tapped and what they saw after it. Install the native module and turn it on once at startup:
|
|
135
|
+
|
|
136
|
+
```sh
|
|
137
|
+
yarn add @rnzeus/heimdall-lens
|
|
138
|
+
cd ios && pod install
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
```ts
|
|
142
|
+
import { heimdallFrames } from "@rnzeus/heimdall-sdk/frames";
|
|
143
|
+
|
|
144
|
+
heimdallFrames();
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
- **When.** Capture runs only while Heimdall is connected and screen capture is on in it (Settings → Connection). A screenshot is taken at a tap, once the screen settles after it, and when a report is opened in Heimdall — not on a timer. Scrolls are not recorded.
|
|
148
|
+
- **How.** Android copies the window with `PixelCopy` off the UI thread. iOS records the app's own screen with `ReplayKit` — it asks the tester once; without the permission iOS sends a single snapshot of the app's views when a report asks for it, where forms and video may come out blank. Capture slows down or pauses on its own when the device is busy.
|
|
149
|
+
- **What is in them.** Only your app's window: other apps, notifications and the system UI are not captured. The screenshots are not masked — the mask of a report does not cover what is on the screen.
|
|
150
|
+
- **The tester decides.** The connect prompt has a switch, **Record the screen for bug reports**. Off, the device sends nothing, and the choice is remembered.
|
|
151
|
+
- Screenshots stay in the desktop app's memory for a few minutes and go only into the reports the tester attaches them to.
|
|
152
|
+
|
|
153
|
+
Without `@rnzeus/heimdall-lens` in the app, `heimdallFrames()` does nothing and warns in development.
|
|
154
|
+
|
|
155
|
+
To leave the module out of production builds, together with the SDK, see [Removing the SDK from production builds](#removing-the-sdk-from-production-builds).
|
|
156
|
+
|
|
130
157
|
## Without the prompt
|
|
131
158
|
|
|
132
159
|
```ts
|
|
@@ -198,7 +225,7 @@ The cloud only stores accounts, devices and the current address of the desktop.
|
|
|
198
225
|
|
|
199
226
|
## Removing the SDK from production builds
|
|
200
227
|
|
|
201
|
-
This is optional: without it the SDK works as described above. With `enabled: false` the SDK is off, but its code and `react-native-tcp-socket` are still in the build. To leave them out of production builds:
|
|
228
|
+
This is optional: without it the SDK works as described above. With `enabled: false` the SDK is off, but its code and its native modules (`react-native-tcp-socket`, and `@rnzeus/heimdall-lens` if you added it) are still in the build. To leave them out of production builds:
|
|
202
229
|
|
|
203
230
|
**1. Replace the SDK with no-ops in `metro.config.js`:**
|
|
204
231
|
|
|
@@ -215,24 +242,28 @@ module.exports = withHeimdall(config, {
|
|
|
215
242
|
});
|
|
216
243
|
```
|
|
217
244
|
|
|
218
|
-
- `include: false` — `@rnzeus/heimdall-sdk` and `@rnzeus/heimdall-sdk/
|
|
245
|
+
- `include: false` — `@rnzeus/heimdall-sdk`, `@rnzeus/heimdall-sdk/zustand` and `@rnzeus/heimdall-sdk/frames` are replaced with modules that have the same API and do nothing: `connect` and the other calls are no-ops, `<HeimdallConnectPrompt />` renders nothing, `heimdallZustand` returns your store creator as is, `heimdallFrames` does nothing. Your code does not change.
|
|
219
246
|
- `include: true` — the config is returned unchanged.
|
|
220
247
|
- The `include` option has no default, so the choice is always explicit. Wrap your final config, after any other wrappers.
|
|
221
248
|
- Any other runtime import of the SDK, such as `@rnzeus/heimdall-sdk/dist/...`, fails the build with an error that names the file. Type-only imports (`import type`) are fine.
|
|
222
249
|
|
|
223
|
-
**2. Leave the native
|
|
250
|
+
**2. Leave the native modules out** in `react-native.config.js`:
|
|
224
251
|
|
|
225
252
|
```js
|
|
226
253
|
const production = process.env.APP_ENV === "production";
|
|
227
254
|
|
|
228
255
|
module.exports = {
|
|
229
256
|
dependencies: production
|
|
230
|
-
? {
|
|
257
|
+
? {
|
|
258
|
+
"react-native-tcp-socket": { platforms: { ios: null, android: null } },
|
|
259
|
+
// only if you added it for screenshots
|
|
260
|
+
"@rnzeus/heimdall-lens": { platforms: { ios: null, android: null } },
|
|
261
|
+
}
|
|
231
262
|
: {},
|
|
232
263
|
};
|
|
233
264
|
```
|
|
234
265
|
|
|
235
|
-
Do this only together with step 1, otherwise the app crashes on the missing native
|
|
266
|
+
Do this only together with step 1, otherwise the app crashes on the missing native modules. The setting applies to the whole `pod install` run, so run `pod install` again without the variable before a dev or stage build. Leave `react-native-mmkv` alone if your app uses it for anything else.
|
|
236
267
|
|
|
237
268
|
**Which variable to use.** Both files read environment variables of the build process. Use one that is set for the whole build — usually a variable of your CI job, such as the build stage. Values from `.env` files are not visible here. `APP_ENV` above is only an example.
|
|
238
269
|
|
|
@@ -242,6 +273,7 @@ A production bundle built this way contains no `heimdall://` strings — only th
|
|
|
242
273
|
|
|
243
274
|
- Events go **directly** from the app to the Heimdall desktop app over TCP on your network, encrypted with TLS when connected through the cloud. Nothing is sent to us or to any third party.
|
|
244
275
|
- Headers and bodies are sent **as they are**, including auth tokens; a manual connection carries them unencrypted. Use the SDK in dev and stage builds, and narrow the capture with `allowedHosts` / `ignoreUrls` where needed.
|
|
276
|
+
- Screenshots, when turned on, go the same way and are not masked; see [Screenshots in bug reports](#screenshots-in-bug-reports).
|
|
245
277
|
- `cloud` is optional and never sees captured traffic — see [Connecting without typing an address](#connecting-without-typing-an-address).
|
|
246
278
|
|
|
247
279
|
## Testing with Jest
|
|
@@ -268,6 +300,16 @@ jest.mock("react-native-tcp-socket", () => ({ createConnection: jest.fn() }));
|
|
|
268
300
|
|
|
269
301
|
[`example/`](./example) is a minimal React Native app with ready-made network, WebSocket, Zustand and console scenarios.
|
|
270
302
|
|
|
303
|
+
## Heimdall ecosystem
|
|
304
|
+
|
|
305
|
+
| | |
|
|
306
|
+
|---|---|
|
|
307
|
+
| [Heimdall desktop](https://heimdall.rnzeus.dev/download) | the inspector for macOS and Windows |
|
|
308
|
+
| [`@rnzeus/heimdall-sdk`](https://github.com/rnzeus/heimdall-sdk) | React Native client: network, WebSocket, state, console |
|
|
309
|
+
| [`@rnzeus/heimdall-lens`](https://github.com/rnzeus/heimdall-lens) | native screenshots and taps for bug reports |
|
|
310
|
+
| [`@rnzeus/heimdall-protocol`](https://github.com/rnzeus/heimdall-protocol) | messages between the SDK and the desktop app |
|
|
311
|
+
| [`@rnzeus/heimdall-trackers`](https://github.com/rnzeus/heimdall-trackers) | issue tracker adapters for bug reports |
|
|
312
|
+
|
|
271
313
|
## License
|
|
272
314
|
|
|
273
315
|
MIT
|
|
@@ -5,6 +5,8 @@ export declare const SESSION: {
|
|
|
5
5
|
KEY_LAST_PORT: string;
|
|
6
6
|
KEY_LAST_CHANNEL: string;
|
|
7
7
|
KEY_LAST_SOURCE: string;
|
|
8
|
+
/** "off" when the tester turned screen recording off on this device */
|
|
9
|
+
KEY_FRAMES_RECORDING: string;
|
|
8
10
|
};
|
|
9
11
|
type SessionStorage = {
|
|
10
12
|
getString(key: string): string | undefined;
|
|
@@ -6,12 +6,19 @@ export const SESSION = {
|
|
|
6
6
|
KEY_LAST_PORT: "lastPort",
|
|
7
7
|
KEY_LAST_CHANNEL: "lastChannel",
|
|
8
8
|
KEY_LAST_SOURCE: "lastSource",
|
|
9
|
+
/** "off" when the tester turned screen recording off on this device */
|
|
10
|
+
KEY_FRAMES_RECORDING: "framesRecording",
|
|
9
11
|
};
|
|
10
12
|
function createSessionStorage() {
|
|
11
13
|
const mmkv = MMKVModule;
|
|
12
|
-
// react-native-mmkv v4+
|
|
14
|
+
// react-native-mmkv v4+ renamed delete to remove
|
|
13
15
|
if (typeof mmkv.createMMKV === "function") {
|
|
14
|
-
|
|
16
|
+
const storage = mmkv.createMMKV({ id: SESSION.STORAGE_ID });
|
|
17
|
+
return {
|
|
18
|
+
getString: (key) => storage.getString(key),
|
|
19
|
+
set: (key, value) => storage.set(key, value),
|
|
20
|
+
delete: (key) => storage.remove(key),
|
|
21
|
+
};
|
|
15
22
|
}
|
|
16
23
|
// react-native-mmkv v3
|
|
17
24
|
if (typeof mmkv.MMKV === "function") {
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
import type { HelloCapabilities } from "@rnzeus/heimdall-protocol";
|
|
2
|
+
/** Optional features announced in `hello`; set by the feature when the app turns it on. */
|
|
3
|
+
export declare function setCapability<K extends keyof HelloCapabilities>({ name, value, }: {
|
|
4
|
+
name: K;
|
|
5
|
+
value: HelloCapabilities[K];
|
|
6
|
+
}): void;
|
|
7
|
+
export declare function getCapabilities(): HelloCapabilities | undefined;
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
let capabilities = {};
|
|
2
|
+
/** Optional features announced in `hello`; set by the feature when the app turns it on. */
|
|
3
|
+
export function setCapability({ name, value, }) {
|
|
4
|
+
capabilities = { ...capabilities, [name]: value };
|
|
5
|
+
}
|
|
6
|
+
export function getCapabilities() {
|
|
7
|
+
return Object.keys(capabilities).length > 0 ? capabilities : undefined;
|
|
8
|
+
}
|
|
@@ -5,6 +5,9 @@ import { handleSocketLost } from "./handle-socket-lost.js";
|
|
|
5
5
|
import { flushEarlyEvents } from "./flush-early-events.js";
|
|
6
6
|
import { normalizeSocketError } from "./normalize-socket-error.js";
|
|
7
7
|
import { SOCKET } from "./constants.js";
|
|
8
|
+
import { getCapabilities } from "./capabilities.js";
|
|
9
|
+
import { handleHostLine } from "./host-message.js";
|
|
10
|
+
import { readHostLines } from "./host-lines.js";
|
|
8
11
|
import { getCurrentSession, setCurrentSession, } from "../session/index.js";
|
|
9
12
|
import { SDK_VERSION } from "../../../version.js";
|
|
10
13
|
import { normaliseAppInfo, readDeviceInfo } from "../../system/index.js";
|
|
@@ -32,6 +35,9 @@ function buildHello({ session, options, secure, }) {
|
|
|
32
35
|
hello.app = app;
|
|
33
36
|
if (secure)
|
|
34
37
|
hello.auth = { token: secure.token };
|
|
38
|
+
const capabilities = getCapabilities();
|
|
39
|
+
if (capabilities)
|
|
40
|
+
hello.capabilities = capabilities;
|
|
35
41
|
return hello;
|
|
36
42
|
}
|
|
37
43
|
function fail(message) {
|
|
@@ -87,6 +93,7 @@ export function connectSocket(optionsOrSession) {
|
|
|
87
93
|
const onPlainConnect = () => {
|
|
88
94
|
clearTimeout(connectTimeout);
|
|
89
95
|
setConnected(true);
|
|
96
|
+
readHostLines({ socket: newSocket, onLine: handleHostLine });
|
|
90
97
|
try {
|
|
91
98
|
newSocket.write(JSON.stringify(buildHello({ session, options })) + "\r\n");
|
|
92
99
|
}
|
|
@@ -104,21 +111,20 @@ export function connectSocket(optionsOrSession) {
|
|
|
104
111
|
fail(CERTIFICATE_MISMATCH);
|
|
105
112
|
return;
|
|
106
113
|
}
|
|
107
|
-
let
|
|
114
|
+
let answered = false;
|
|
108
115
|
const answerTimeout = setTimeout(() => {
|
|
109
116
|
if (getSocket() === newSocket && !isConnected())
|
|
110
117
|
fail(NO_ANSWER);
|
|
111
118
|
}, HOST_ANSWER_TIMEOUT_MS);
|
|
112
|
-
const
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
const end = pending.indexOf("\r\n");
|
|
116
|
-
if (end === -1)
|
|
119
|
+
const onLine = (line) => {
|
|
120
|
+
if (answered) {
|
|
121
|
+
handleHostLine(line);
|
|
117
122
|
return;
|
|
118
|
-
|
|
123
|
+
}
|
|
124
|
+
answered = true;
|
|
119
125
|
clearTimeout(answerTimeout);
|
|
120
126
|
clearTimeout(connectTimeout);
|
|
121
|
-
const answer = parseHostAnswer(
|
|
127
|
+
const answer = parseHostAnswer(line);
|
|
122
128
|
if (!answer) {
|
|
123
129
|
fail(NO_ANSWER);
|
|
124
130
|
return;
|
|
@@ -130,7 +136,7 @@ export function connectSocket(optionsOrSession) {
|
|
|
130
136
|
setConnected(true);
|
|
131
137
|
flushEarlyEvents();
|
|
132
138
|
};
|
|
133
|
-
newSocket
|
|
139
|
+
readHostLines({ socket: newSocket, onLine });
|
|
134
140
|
try {
|
|
135
141
|
newSocket.write(JSON.stringify(buildHello({ session, options, secure })) + "\r\n");
|
|
136
142
|
}
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
/** The host writes one JSON message per line; calls `onLine` for every complete line until unsubscribed. */
|
|
2
|
+
export function readHostLines({ socket, onLine, }) {
|
|
3
|
+
let pending = "";
|
|
4
|
+
const onData = (data) => {
|
|
5
|
+
pending += typeof data === "string" ? data : String(data);
|
|
6
|
+
let end = pending.indexOf("\r\n");
|
|
7
|
+
while (end !== -1) {
|
|
8
|
+
const line = pending.slice(0, end);
|
|
9
|
+
pending = pending.slice(end + 2);
|
|
10
|
+
onLine(line);
|
|
11
|
+
end = pending.indexOf("\r\n");
|
|
12
|
+
}
|
|
13
|
+
};
|
|
14
|
+
socket.on("data", onData);
|
|
15
|
+
return () => { var _a; return (_a = socket.off) === null || _a === void 0 ? void 0 : _a.call(socket, "data", onData); };
|
|
16
|
+
}
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
import type { HostConfigFrames } from "@rnzeus/heimdall-protocol";
|
|
2
|
+
/** A host message of wire version 1, or null when the line is not one. */
|
|
3
|
+
export declare function parseHostMessage(line: string): Record<string, unknown> | null;
|
|
4
|
+
export type HostConfig = {
|
|
5
|
+
frames?: HostConfigFrames;
|
|
6
|
+
};
|
|
7
|
+
export declare function parseHostConfig(line: string): HostConfig | null;
|
|
8
|
+
/** Notified with every `hostConfig` the host sends; the latest one wins. */
|
|
9
|
+
export declare function subscribeHostConfig(listener: (config: HostConfig) => void): () => void;
|
|
10
|
+
/** Notified when the host asks for a frame of the screen now (`captureScreen`). */
|
|
11
|
+
export declare function subscribeCaptureScreen(listener: () => void): () => void;
|
|
12
|
+
export declare function handleHostLine(line: string): void;
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
/** A host message of wire version 1, or null when the line is not one. */
|
|
2
|
+
export function parseHostMessage(line) {
|
|
3
|
+
let json;
|
|
4
|
+
try {
|
|
5
|
+
json = JSON.parse(line);
|
|
6
|
+
}
|
|
7
|
+
catch {
|
|
8
|
+
return null;
|
|
9
|
+
}
|
|
10
|
+
if (!json || typeof json !== "object")
|
|
11
|
+
return null;
|
|
12
|
+
const message = json;
|
|
13
|
+
return typeof message.kind === "string" && message.v === 1 ? message : null;
|
|
14
|
+
}
|
|
15
|
+
const optionalNumber = (value) => typeof value === "number" && Number.isFinite(value) ? value : undefined;
|
|
16
|
+
// Hand-written on purpose, like parseHostAnswer: mirrors the tolerant HostConfigWireMessageV1Schema,
|
|
17
|
+
// unknown sections and fields are ignored.
|
|
18
|
+
export function parseHostConfig(line) {
|
|
19
|
+
const message = parseHostMessage(line);
|
|
20
|
+
if ((message === null || message === void 0 ? void 0 : message.kind) !== "hostConfig")
|
|
21
|
+
return null;
|
|
22
|
+
const { frames } = message;
|
|
23
|
+
if (frames === undefined)
|
|
24
|
+
return {};
|
|
25
|
+
if (!frames || typeof frames !== "object")
|
|
26
|
+
return null;
|
|
27
|
+
const { enabled, fps, maxWidth } = frames;
|
|
28
|
+
if (typeof enabled !== "boolean")
|
|
29
|
+
return null;
|
|
30
|
+
return {
|
|
31
|
+
frames: { enabled, fps: optionalNumber(fps), maxWidth: optionalNumber(maxWidth) },
|
|
32
|
+
};
|
|
33
|
+
}
|
|
34
|
+
const configListeners = new Set();
|
|
35
|
+
/** Notified with every `hostConfig` the host sends; the latest one wins. */
|
|
36
|
+
export function subscribeHostConfig(listener) {
|
|
37
|
+
configListeners.add(listener);
|
|
38
|
+
return () => {
|
|
39
|
+
configListeners.delete(listener);
|
|
40
|
+
};
|
|
41
|
+
}
|
|
42
|
+
const captureListeners = new Set();
|
|
43
|
+
/** Notified when the host asks for a frame of the screen now (`captureScreen`). */
|
|
44
|
+
export function subscribeCaptureScreen(listener) {
|
|
45
|
+
captureListeners.add(listener);
|
|
46
|
+
return () => {
|
|
47
|
+
captureListeners.delete(listener);
|
|
48
|
+
};
|
|
49
|
+
}
|
|
50
|
+
export function handleHostLine(line) {
|
|
51
|
+
var _a;
|
|
52
|
+
const config = parseHostConfig(line);
|
|
53
|
+
if (config) {
|
|
54
|
+
for (const listener of configListeners)
|
|
55
|
+
listener(config);
|
|
56
|
+
return;
|
|
57
|
+
}
|
|
58
|
+
if (((_a = parseHostMessage(line)) === null || _a === void 0 ? void 0 : _a.kind) === "captureScreen") {
|
|
59
|
+
for (const listener of captureListeners)
|
|
60
|
+
listener();
|
|
61
|
+
}
|
|
62
|
+
}
|
|
@@ -4,3 +4,5 @@ export * from "./destroy-socket.js";
|
|
|
4
4
|
export * from "./send-event.js";
|
|
5
5
|
export * from "./early-buffer.js";
|
|
6
6
|
export * from "./state.js";
|
|
7
|
+
export { setCapability } from "./capabilities.js";
|
|
8
|
+
export { subscribeCaptureScreen, subscribeHostConfig } from "./host-message.js";
|
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { parseHostMessage } from "./host-message.js";
|
|
1
2
|
const REJECT_REASONS = [
|
|
2
3
|
"auth",
|
|
3
4
|
"channel",
|
|
@@ -34,18 +35,10 @@ export async function readPeerCertificate(socket) {
|
|
|
34
35
|
// Hand-written on purpose: the protocol schemas would pull zod into every consumer app. Mirrors the
|
|
35
36
|
// tolerant HelloAckWireMessageV1Schema: extra fields are ignored, an unknown reason becomes undefined.
|
|
36
37
|
export function parseHostAnswer(line) {
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
json = JSON.parse(line);
|
|
40
|
-
}
|
|
41
|
-
catch {
|
|
42
|
-
return null;
|
|
43
|
-
}
|
|
44
|
-
if (!json || typeof json !== "object")
|
|
45
|
-
return null;
|
|
46
|
-
const { kind, v, status, reason } = json;
|
|
47
|
-
if (kind !== "helloAck" || v !== 1)
|
|
38
|
+
const message = parseHostMessage(line);
|
|
39
|
+
if ((message === null || message === void 0 ? void 0 : message.kind) !== "helloAck")
|
|
48
40
|
return null;
|
|
41
|
+
const { status, reason } = message;
|
|
49
42
|
if (status === "accepted")
|
|
50
43
|
return { accepted: true };
|
|
51
44
|
if (status !== "rejected")
|
|
@@ -1,3 +1,4 @@
|
|
|
1
1
|
import type { EventWirePayload } from "../../../types";
|
|
2
2
|
export declare function sendEvent(payload: EventWirePayload): void;
|
|
3
|
-
|
|
3
|
+
/** @returns false when the event was not handed to the socket */
|
|
4
|
+
export declare function internalSendNetworkEvent(payload: EventWirePayload): boolean;
|
|
@@ -19,12 +19,13 @@ export function sendEvent(payload) {
|
|
|
19
19
|
}
|
|
20
20
|
internalSendNetworkEvent(payload);
|
|
21
21
|
}
|
|
22
|
+
/** @returns false when the event was not handed to the socket */
|
|
22
23
|
export function internalSendNetworkEvent(payload) {
|
|
23
24
|
const currentSession = getCurrentSession();
|
|
24
25
|
const socket = getSocket();
|
|
25
26
|
const connected = isConnected();
|
|
26
27
|
if (!socket || !connected || !currentSession)
|
|
27
|
-
return;
|
|
28
|
+
return false;
|
|
28
29
|
const { options, clientId, sessionId } = currentSession;
|
|
29
30
|
const message = {
|
|
30
31
|
kind: "event",
|
|
@@ -39,8 +40,9 @@ export function internalSendNetworkEvent(payload) {
|
|
|
39
40
|
};
|
|
40
41
|
try {
|
|
41
42
|
socket.write(JSON.stringify(message) + "\r\n");
|
|
43
|
+
return true;
|
|
42
44
|
}
|
|
43
45
|
catch {
|
|
44
|
-
|
|
46
|
+
return false;
|
|
45
47
|
}
|
|
46
48
|
}
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
import type { FrameSource, FramesCapability, FramesStatusEventPayload, ScreenTapEventPayload } from "@rnzeus/heimdall-protocol";
|
|
2
|
+
type FramesSourceFrame = {
|
|
3
|
+
data: string;
|
|
4
|
+
width: number;
|
|
5
|
+
height: number;
|
|
6
|
+
ts: number;
|
|
7
|
+
source?: FrameSource;
|
|
8
|
+
};
|
|
9
|
+
type FramesSourceTap = Pick<ScreenTapEventPayload, "x" | "y" | "ts" | "kind">;
|
|
10
|
+
type FramesSourceStatus = Pick<FramesStatusEventPayload, "state" | "reason" | "fps" | "deviceClass" | "source">;
|
|
11
|
+
/** A native screen capturer, e.g. @rnzeus/heimdall-lens; the SDK only decides when it runs. */
|
|
12
|
+
export type FramesSource = {
|
|
13
|
+
capability: FramesCapability;
|
|
14
|
+
start: (options: {
|
|
15
|
+
fps: number;
|
|
16
|
+
maxWidth: number;
|
|
17
|
+
allowRecording: boolean;
|
|
18
|
+
}) => void;
|
|
19
|
+
stop: () => void;
|
|
20
|
+
/** one frame of the screen as it is now, also while no loop runs */
|
|
21
|
+
captureNow: (options: {
|
|
22
|
+
maxWidth: number;
|
|
23
|
+
}) => Promise<FramesSourceFrame>;
|
|
24
|
+
subscribe: (handlers: {
|
|
25
|
+
onFrame: (frame: FramesSourceFrame) => void;
|
|
26
|
+
onStatus: (status: FramesSourceStatus) => void;
|
|
27
|
+
onTap: (tap: FramesSourceTap) => void;
|
|
28
|
+
}) => () => void;
|
|
29
|
+
};
|
|
30
|
+
/** What the connect prompt shows: whether this app can capture, the tester's choice and how capture goes. */
|
|
31
|
+
export type FramesRecordingState = {
|
|
32
|
+
isAvailable: boolean;
|
|
33
|
+
/** the tester's choice on this device, kept across launches */
|
|
34
|
+
isAllowed: boolean;
|
|
35
|
+
status: FramesSourceStatus | null;
|
|
36
|
+
};
|
|
37
|
+
export declare function getFramesRecordingState(): FramesRecordingState;
|
|
38
|
+
export declare function subscribeFramesRecording(listener: () => void): () => void;
|
|
39
|
+
/** The tester's choice: off keeps frames off on this device — iOS does not even ask — until turned back on. */
|
|
40
|
+
export declare function setFramesRecordingAllowed(isAllowed: boolean): void;
|
|
41
|
+
/** Announces frames in `hello`; capture runs only while the host asks for it over a live connection. */
|
|
42
|
+
export declare function registerFramesSource(next: FramesSource): void;
|
|
43
|
+
export {};
|
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
import { generateRandomId } from "../../utils/index.js";
|
|
2
|
+
import { getSocket, internalSendNetworkEvent, isConnected, setCapability, subscribeCaptureScreen, subscribeHostConfig, subscribeSocketState, } from "../connection/index.js";
|
|
3
|
+
import { SESSION, SESSION_STORAGE } from "../connection/session/constants.js";
|
|
4
|
+
let source = null;
|
|
5
|
+
let running = null;
|
|
6
|
+
let unsubscribeSource = null;
|
|
7
|
+
let lastHostFrames;
|
|
8
|
+
const RECORDING_OFF = "off";
|
|
9
|
+
let recordingState = {
|
|
10
|
+
isAvailable: false,
|
|
11
|
+
isAllowed: SESSION_STORAGE.getString(SESSION.KEY_FRAMES_RECORDING) !== RECORDING_OFF,
|
|
12
|
+
status: null,
|
|
13
|
+
};
|
|
14
|
+
const recordingListeners = new Set();
|
|
15
|
+
function updateRecordingState(next) {
|
|
16
|
+
recordingState = { ...recordingState, ...next };
|
|
17
|
+
for (const listener of recordingListeners)
|
|
18
|
+
listener();
|
|
19
|
+
}
|
|
20
|
+
export function getFramesRecordingState() {
|
|
21
|
+
return recordingState;
|
|
22
|
+
}
|
|
23
|
+
export function subscribeFramesRecording(listener) {
|
|
24
|
+
recordingListeners.add(listener);
|
|
25
|
+
return () => {
|
|
26
|
+
recordingListeners.delete(listener);
|
|
27
|
+
};
|
|
28
|
+
}
|
|
29
|
+
/** The tester's choice: off keeps frames off on this device — iOS does not even ask — until turned back on. */
|
|
30
|
+
export function setFramesRecordingAllowed(isAllowed) {
|
|
31
|
+
if (isAllowed)
|
|
32
|
+
SESSION_STORAGE.delete(SESSION.KEY_FRAMES_RECORDING);
|
|
33
|
+
else
|
|
34
|
+
SESSION_STORAGE.set(SESSION.KEY_FRAMES_RECORDING, RECORDING_OFF);
|
|
35
|
+
updateRecordingState({ isAllowed });
|
|
36
|
+
applyFrames(lastHostFrames);
|
|
37
|
+
}
|
|
38
|
+
function sendFrame(frame) {
|
|
39
|
+
var _a;
|
|
40
|
+
// Frames are the first thing to give up: never queued, dropped while the socket is still busy.
|
|
41
|
+
if ((_a = getSocket()) === null || _a === void 0 ? void 0 : _a.writableNeedDrain)
|
|
42
|
+
return;
|
|
43
|
+
sendFrameNow(frame);
|
|
44
|
+
}
|
|
45
|
+
function sendFrameNow(frame) {
|
|
46
|
+
internalSendNetworkEvent({
|
|
47
|
+
type: "screenFrame",
|
|
48
|
+
id: generateRandomId(),
|
|
49
|
+
ts: frame.ts,
|
|
50
|
+
width: frame.width,
|
|
51
|
+
height: frame.height,
|
|
52
|
+
mime: "image/jpeg",
|
|
53
|
+
data: frame.data,
|
|
54
|
+
source: frame.source,
|
|
55
|
+
});
|
|
56
|
+
}
|
|
57
|
+
function sendStatus(status) {
|
|
58
|
+
updateRecordingState({ status });
|
|
59
|
+
internalSendNetworkEvent({
|
|
60
|
+
type: "framesStatus",
|
|
61
|
+
id: generateRandomId(),
|
|
62
|
+
ts: Date.now(),
|
|
63
|
+
state: status.state,
|
|
64
|
+
reason: status.reason,
|
|
65
|
+
fps: status.fps,
|
|
66
|
+
deviceClass: status.deviceClass,
|
|
67
|
+
source: status.source,
|
|
68
|
+
});
|
|
69
|
+
}
|
|
70
|
+
// Taps are tiny and mark where frames were touched, so unlike frames they are never dropped.
|
|
71
|
+
function sendTap(tap) {
|
|
72
|
+
internalSendNetworkEvent({
|
|
73
|
+
type: "screenTap",
|
|
74
|
+
id: generateRandomId(),
|
|
75
|
+
ts: tap.ts,
|
|
76
|
+
x: tap.x,
|
|
77
|
+
y: tap.y,
|
|
78
|
+
kind: tap.kind,
|
|
79
|
+
});
|
|
80
|
+
}
|
|
81
|
+
function stopCapture() {
|
|
82
|
+
if (!source || !running)
|
|
83
|
+
return;
|
|
84
|
+
running = null;
|
|
85
|
+
updateRecordingState({ status: null });
|
|
86
|
+
unsubscribeSource === null || unsubscribeSource === void 0 ? void 0 : unsubscribeSource();
|
|
87
|
+
unsubscribeSource = null;
|
|
88
|
+
source.stop();
|
|
89
|
+
}
|
|
90
|
+
/** The host asks for a rate and width; the SDK never goes above what the app allowed. */
|
|
91
|
+
function applyFrames(frames) {
|
|
92
|
+
var _a, _b;
|
|
93
|
+
lastHostFrames = frames;
|
|
94
|
+
if (!source)
|
|
95
|
+
return;
|
|
96
|
+
if (!(frames === null || frames === void 0 ? void 0 : frames.enabled) || !isConnected()) {
|
|
97
|
+
stopCapture();
|
|
98
|
+
return;
|
|
99
|
+
}
|
|
100
|
+
const { maxFps, maxWidth } = source.capability;
|
|
101
|
+
const next = {
|
|
102
|
+
fps: Math.min((_a = frames.fps) !== null && _a !== void 0 ? _a : maxFps, maxFps),
|
|
103
|
+
maxWidth: Math.min((_b = frames.maxWidth) !== null && _b !== void 0 ? _b : maxWidth, maxWidth),
|
|
104
|
+
allowRecording: recordingState.isAllowed,
|
|
105
|
+
};
|
|
106
|
+
if (running &&
|
|
107
|
+
running.fps === next.fps &&
|
|
108
|
+
running.maxWidth === next.maxWidth &&
|
|
109
|
+
running.allowRecording === next.allowRecording) {
|
|
110
|
+
return;
|
|
111
|
+
}
|
|
112
|
+
stopCapture();
|
|
113
|
+
running = next;
|
|
114
|
+
unsubscribeSource = source.subscribe({ onFrame: sendFrame, onStatus: sendStatus, onTap: sendTap });
|
|
115
|
+
source.start(next);
|
|
116
|
+
}
|
|
117
|
+
/** Announces frames in `hello`; capture runs only while the host asks for it over a live connection. */
|
|
118
|
+
export function registerFramesSource(next) {
|
|
119
|
+
if (source)
|
|
120
|
+
return;
|
|
121
|
+
source = next;
|
|
122
|
+
setCapability({ name: "frames", value: next.capability });
|
|
123
|
+
updateRecordingState({ isAvailable: true });
|
|
124
|
+
subscribeHostConfig((config) => applyFrames(config.frames));
|
|
125
|
+
subscribeCaptureScreen(captureScreen);
|
|
126
|
+
subscribeSocketState(() => {
|
|
127
|
+
if (!isConnected())
|
|
128
|
+
stopCapture();
|
|
129
|
+
});
|
|
130
|
+
}
|
|
131
|
+
/** A bug report opened on the host: the screen as it is now, also while frames are off — not if the tester said no. */
|
|
132
|
+
function captureScreen() {
|
|
133
|
+
var _a;
|
|
134
|
+
if (!source || !isConnected() || !recordingState.isAllowed)
|
|
135
|
+
return;
|
|
136
|
+
source
|
|
137
|
+
.captureNow({ maxWidth: (_a = running === null || running === void 0 ? void 0 : running.maxWidth) !== null && _a !== void 0 ? _a : source.capability.maxWidth })
|
|
138
|
+
.then(sendFrameNow)
|
|
139
|
+
.catch(() => { });
|
|
140
|
+
}
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
export type HeimdallFramesOptions = {
|
|
2
|
+
/** upper bound for the rate the host may ask for; 2 by default */
|
|
3
|
+
maxFps?: number;
|
|
4
|
+
/** upper bound for the frame width in pixels; 480 by default */
|
|
5
|
+
maxWidth?: number;
|
|
6
|
+
};
|
|
7
|
+
/**
|
|
8
|
+
* Lets Heimdall attach the last seconds of the screen to a bug report. Call once at startup; capture
|
|
9
|
+
* runs only while Heimdall is connected and asks for frames. Needs `@rnzeus/heimdall-lens` in the app.
|
|
10
|
+
*/
|
|
11
|
+
export declare function heimdallFrames(options?: HeimdallFramesOptions): void;
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
import { addFrameListener, addStatusListener, addTapListener, captureFrame, isFramesAvailable, startFrames, stopFrames, } from "@rnzeus/heimdall-lens";
|
|
2
|
+
import { registerFramesSource } from "../core/frames/index.js";
|
|
3
|
+
const DEFAULT_MAX_FPS = 2;
|
|
4
|
+
const DEFAULT_MAX_WIDTH = 480;
|
|
5
|
+
/**
|
|
6
|
+
* Lets Heimdall attach the last seconds of the screen to a bug report. Call once at startup; capture
|
|
7
|
+
* runs only while Heimdall is connected and asks for frames. Needs `@rnzeus/heimdall-lens` in the app.
|
|
8
|
+
*/
|
|
9
|
+
export function heimdallFrames(options = {}) {
|
|
10
|
+
var _a, _b;
|
|
11
|
+
if (!isFramesAvailable()) {
|
|
12
|
+
if (__DEV__) {
|
|
13
|
+
console.warn("[Heimdall] heimdallFrames: @rnzeus/heimdall-lens is not linked, rebuild the app after installing it.");
|
|
14
|
+
}
|
|
15
|
+
return;
|
|
16
|
+
}
|
|
17
|
+
registerFramesSource({
|
|
18
|
+
capability: {
|
|
19
|
+
maxFps: (_a = options.maxFps) !== null && _a !== void 0 ? _a : DEFAULT_MAX_FPS,
|
|
20
|
+
maxWidth: (_b = options.maxWidth) !== null && _b !== void 0 ? _b : DEFAULT_MAX_WIDTH,
|
|
21
|
+
},
|
|
22
|
+
start: ({ fps, maxWidth, allowRecording }) => startFrames({ fps, maxWidth, allowRecording }),
|
|
23
|
+
captureNow: ({ maxWidth }) => captureFrame({ maxWidth }),
|
|
24
|
+
stop: () => {
|
|
25
|
+
stopFrames().catch(() => { });
|
|
26
|
+
},
|
|
27
|
+
subscribe: ({ onFrame, onStatus, onTap }) => {
|
|
28
|
+
const subscriptions = [addFrameListener(onFrame), addStatusListener(onStatus), addTapListener(onTap)];
|
|
29
|
+
return () => {
|
|
30
|
+
for (const subscription of subscriptions)
|
|
31
|
+
subscription.remove();
|
|
32
|
+
};
|
|
33
|
+
},
|
|
34
|
+
});
|
|
35
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export const heimdallFrames = () => { };
|