Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 37 additions & 6 deletions packages/comfyui-desktop-bridge-types/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,20 +41,23 @@ while omitting part of it.

## Comfy pages hosted in Desktop's Apps view

A Comfy page that Desktop shows in its Apps view gets two objects instead, and
nothing else of the bridge above: `window.comfyDesktopAuth`, Desktop's account
session, and `window.comfyDesktopLocal`, a ComfyUI on this computer.
A Comfy page that Desktop shows in its Apps view gets three objects instead,
and nothing else of the bridge above: `window.comfyDesktopAuth`, Desktop's
account session, `window.comfyDesktopLocal`, a ComfyUI on this computer, and
`window.comfyDesktopTelemetry`, the page's usage events.

```ts
import type {
ComfyDesktopHostedAuthBridge,
ComfyDesktopHostedLocalBridge
ComfyDesktopHostedLocalBridge,
ComfyDesktopHostedTelemetryBridge
} from '@comfyorg/comfyui-desktop-bridge-types'

declare global {
interface Window {
comfyDesktopAuth?: ComfyDesktopHostedAuthBridge
comfyDesktopLocal?: ComfyDesktopHostedLocalBridge
comfyDesktopTelemetry?: ComfyDesktopHostedTelemetryBridge
}
}
```
Expand Down Expand Up @@ -83,8 +86,36 @@ the workflow, or `{ opened: false, error }` with the reason in words. Both
members are absent on Desktop builds that predate them, so a page checks for
them and keeps its file download as the fallback.

Both objects are absent in a browser, so a page keeps its own sign-in and its
own way to reach a local ComfyUI as the fallback.
`track(name, props)` reports what the person does on the page, such as
`track('click', { target: 'run' })`. Desktop sends it as
`comfy.desktop.apps.<name>` only when the person allows telemetry, and adds
`app_id`, the app whose page Desktop loaded in that view. An event the page
sends while the view loads another app is dropped.

- A name starts with a lowercase letter, then lowercase letters, digits and
`_`, up to 48 characters in all (`^[a-z][a-z0-9_]{0,47}$`), so `2_click` is
dropped. `app_opened` and `app_page_failed` are Desktop's own and are
refused, and so is `error`.
- Desktop keeps up to 16 properties. A key starts with a lowercase letter,
then lowercase letters, digits and `_`, up to 32 characters in all
(`^[a-z][a-z0-9_]{0,31}$`), so `{ Run: true }` is dropped. A value is a
boolean, a finite number or a slug of up to 64 characters
(`^[a-z0-9][a-z0-9._-]{0,63}$`). Free text, any other key or value, and an
`app` or `app_id` from the page are dropped.
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
- Desktop sets these keys on every event itself, so the page's value for any
of them is dropped: `app_version`, `app_channel`, `app_env`, `is_packaged`,
`platform`, `arch`, `client`, `installation_id` and `sac_state`.
- Desktop sends at most 60 events a minute for one app and 1,000 page events a
session. Events telemetry did not send, as while consent is off, do not
count.
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
- Desktop's telemetry also sends at most 60 of one event name a minute, shared
by every app. If one app sends 60 `click` events in a minute, a `click` from
another app in that minute is dropped too.

The page is not told when Desktop drops an event.

All three objects are absent in a browser, so a page keeps its own sign-in and
its own way to reach a local ComfyUI as the fallback, and sends no events.

## Provenance

Expand Down
17 changes: 17 additions & 0 deletions packages/comfyui-desktop-bridge-types/comfyDesktopBridge.d.ts
Original file line number Diff line number Diff line change
Expand Up @@ -305,6 +305,23 @@ export interface ComfyDesktopHostedLocalBridge {
/** The person's ComfyUI builds on this computer. Absent on Desktop builds that predate it. */
localBuilds?(): Promise<ComfyDesktopLocalBuild[]>
}
/**
* Usage events from a Comfy page hosted in Desktop's Apps view. Desktop
* exposes it to that page as `window.comfyDesktopTelemetry` and sends an event
* as `comfy.desktop.apps.<name>` only when the person allows telemetry.
* `name` matches `^[a-z][a-z0-9_]{0,47}$`; `app_opened` and `app_page_failed`
* are refused because Desktop sends them itself, and so is `error`. Desktop
* sends at most 60 events a minute for one app and 1,000 page events a
* session, and drops the rest. Desktop keeps at most 16
* properties, each named `^[a-z][a-z0-9_]{0,31}$` with a boolean, a finite
* number or a slug of at most 64 characters (`^[a-z0-9][a-z0-9._-]{0,63}$`),
* and drops anything else. Desktop sets `app_id` itself, to the app whose
* page it loaded in that view; an `app` or `app_id` from the page is ignored,
* and an event sent while the view loads another app is dropped.
*/
export interface ComfyDesktopHostedTelemetryBridge {
track(name: string, props?: Record<string, string | number | boolean>): void
}
export interface ComfyDesktop2TerminalBridge {
subscribe(installationId?: string): Promise<TerminalRestore>
unsubscribe(installationId?: string): Promise<void>
Expand Down
2 changes: 1 addition & 1 deletion packages/comfyui-desktop-bridge-types/package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@comfyorg/comfyui-desktop-bridge-types",
"version": "0.12.0",
"version": "0.13.0",
"description": "TypeScript definitions for the Comfy Desktop hosted frontend bridge",
"type": "module",
"main": "./index.js",
Expand Down
230 changes: 230 additions & 0 deletions src/main/apps/appPageEvents.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,230 @@
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import os from 'os'
import path from 'path'

vi.mock('electron', () => ({
app: {
getPath: () => path.join(os.tmpdir(), 'launcher-test'),
isPackaged: true,
on: () => {}
},
BrowserWindow: { getAllWindows: () => [] }
}))

const sdkCaptures = vi.hoisted(
() => [] as Array<{ event: string; properties?: Record<string, unknown> }>
)

vi.mock('posthog-node', () => ({
PostHog: class {
on(): () => void {
return () => {}
}
capture(call: { event: string; properties?: Record<string, unknown> }): void {
sdkCaptures.push(call)
}
identify(): void {}
flush(): Promise<void> {
return Promise.resolve()
}
shutdown(): Promise<void> {
return Promise.resolve()
}
}
}))

import * as telemetry from '../lib/telemetry'
import {
APP_PAGE_EVENT_PREFIX,
DESKTOP_APP_EVENTS,
MAX_PAGE_EVENT_PROPERTIES,
UNLIMITED_EVENT_NAMES,
_resetPageEventLimitsForTest,
checkAppPageEvent,
trackAppPageEvent
} from './appPageEvents'

const APP = 'remove-background'

describe('checkAppPageEvent', () => {
it('sends a page event under the Apps prefix with the app id Desktop holds', () => {
expect(
checkAppPageEvent(
'run_started',
{ where: 'cloud', model: 'birefnet', seconds: 12.4, fast: true },
APP
)
).toEqual({
event: 'comfy.desktop.apps.run_started',
properties: { where: 'cloud', model: 'birefnet', seconds: 12.4, fast: true, app_id: APP }
})
})

it.each(['click', 'run_started', 'example_used', 'a', `a${'b'.repeat(47)}`, 'step_2_done'])(
'accepts the event name %s',
(name) => {
expect(checkAppPageEvent(name, {}, APP)?.event).toBe(`${APP_PAGE_EVENT_PREFIX}${name}`)
}
)

it.each([
['too long', `a${'b'.repeat(48)}`],
['starting with a digit', '2fast'],
['starting with an underscore', '_hidden'],
['with capitals', 'RunStarted'],
['with a dot', 'apps.run_started'],
['with a dash', 'run-started'],
['with a space', 'run started'],
['empty', ''],
['not a string', 42]
])('refuses an event name %s', (_why, name) => {
expect(checkAppPageEvent(name, {}, APP)).toBeNull()
})

it.each([...DESKTOP_APP_EVENTS])('refuses %s, which only Desktop sends', (name) => {
expect(['app_opened', 'app_page_failed']).toContain(name)
expect(checkAppPageEvent(name, {}, APP)).toBeNull()
})

it('takes app_id from Desktop and ignores the app the page names', () => {
expect(
checkAppPageEvent('click', { app: 'other-app', app_id: 'other-app', target: 'run' }, APP)
).toEqual({
event: 'comfy.desktop.apps.click',
properties: { target: 'run', app_id: APP }
})
})

it.each([
['no app id', null],
['an app id the catalog would not list', 'Remove Background'],
['an app id with a dot', 'remove.background'],
['an app id longer than the catalog allows', `a${'b'.repeat(128)}`]
])('drops the event when Desktop holds %s for the page', (_why, appId) => {
expect(checkAppPageEvent('click', { target: 'run' }, appId)).toBeNull()
})

it.each(['HDR', 'Upscale_4x', `a${'b'.repeat(127)}`])(
'keeps the catalog app id %s as Desktop holds it',
(appId) => {
expect(checkAppPageEvent('click', {}, appId)?.properties).toEqual({ app_id: appId })
}
)

it('refuses error, whose full name the shared telemetry limit lets through unlimited', () => {
expect(UNLIMITED_EVENT_NAMES.has('error')).toBe(true)
expect(checkAppPageEvent('error', {}, APP)).toBeNull()
expect(checkAppPageEvent('run_error', {}, APP)?.event).toBe('comfy.desktop.apps.run_error')
})

it('drops free text, bad values and bad property names, keeping the event', () => {
expect(
checkAppPageEvent(
'run_started',
{
where: 'local',
prompt: 'a cat on the moon',
file: '/Users/someone/Pictures/me.png',
name: 'My Model.safetensors',
long: 'a'.repeat(65),
nan: Number.NaN,
forever: Number.POSITIVE_INFINITY,
nothing: null,
list: ['a'],
nested: { a: 1 },
Capital: 'x',
'1st': 'x',
[`a${'b'.repeat(32)}`]: 'x',
$set: 'x',
app_version: '9.9.9',
installation_id: 'fake',
ok: false,
count: 0
},
APP
)
).toEqual({
event: 'comfy.desktop.apps.run_started',
properties: { where: 'local', ok: false, count: 0, app_id: APP }
})
})

it('keeps a 64-character slug and a 32-character property name', () => {
const key = `a${'b'.repeat(31)}`
const value = `a${'b'.repeat(63)}`
expect(checkAppPageEvent('click', { [key]: value }, APP)?.properties).toEqual({
[key]: value,
app_id: APP
})
})

it(`keeps at most ${MAX_PAGE_EVENT_PROPERTIES} properties besides app_id`, () => {
const many = Object.fromEntries(Array.from({ length: 20 }, (_, i) => [`p${i}`, i]))
const kept = checkAppPageEvent('click', many, APP)?.properties ?? {}
expect(Object.keys(kept)).toHaveLength(MAX_PAGE_EVENT_PROPERTIES + 1)
expect(kept).toMatchObject({ p0: 0, p15: 15, app_id: APP })
expect(kept).not.toHaveProperty('p16')
})

it.each([
['not an object', 'run'],
['a list', ['run']],
['missing', undefined]
])('sends only app_id when the properties are %s', (_why, props) => {
expect(checkAppPageEvent('click', props, APP)?.properties).toEqual({ app_id: APP })
})
})

describe('trackAppPageEvent through Desktop telemetry', () => {
beforeEach(() => {
process.env['POSTHOG_API_KEY'] = 'test-key'
process.env['POSTHOG_ENABLED'] = '1'
telemetry._resetForTest()
_resetPageEventLimitsForTest()
telemetry.initTelemetry({ appVersion: '0.0.0', appEnv: 'test', isPackaged: true })
})

afterEach(() => {
telemetry._resetForTest()
sdkCaptures.length = 0
delete process.env['POSTHOG_API_KEY']
delete process.env['POSTHOG_ENABLED']
})

function appCaptures(): Array<{ event: string; properties?: Record<string, unknown> }> {
return sdkCaptures.filter((c) => c.event.startsWith(APP_PAGE_EVENT_PREFIX))
}

it('sends a good event to PostHog when the person allows telemetry', () => {
telemetry.setConsentState('granted')
telemetry.bindAnonymousId('anon-1', 'anon-1', {})

expect(trackAppPageEvent('run_started', { where: 'cloud', prompt: 'a cat' }, APP)).toBe(true)

const sent = appCaptures()
expect(sent.map((c) => c.event)).toEqual(['comfy.desktop.apps.run_started'])
expect(sent[0]?.properties).toMatchObject({ app_id: APP, where: 'cloud' })
expect(sent[0]?.properties).not.toHaveProperty('prompt')
})

it.each(['denied', 'undecided'] as const)('sends nothing while consent is %s', (consent) => {
telemetry.setConsentState(consent)
telemetry.bindAnonymousId('anon-1', 'anon-1', {})

expect(trackAppPageEvent('run_started', { where: 'cloud' }, APP)).toBe(false)
expect(trackAppPageEvent('click', { target: 'run' }, APP)).toBe(false)

expect(appCaptures()).toEqual([])
})

it('sends nothing for an event it refuses, even with consent', () => {
telemetry.setConsentState('granted')
telemetry.bindAnonymousId('anon-1', 'anon-1', {})

expect(trackAppPageEvent('app_opened', {}, APP)).toBe(false)
expect(trackAppPageEvent('Not An Event', {}, APP)).toBe(false)
expect(trackAppPageEvent('click', {}, null)).toBe(false)

expect(appCaptures()).toEqual([])
})
})
Loading
Loading