Native Messaging — 확장이 로컬 바이너리를 실행하는 법

확장 샌드박스 안: content.js → runtime.sendMessage → background.js(service worker). content.js 에서는 네이티브 통신을 못 한다. background.js → sendNativeMessage → Chrome. Chrome 은 OS 지정 위치의 manifest 에서 allowed_origins 에 이 확장이 있는지 대조한 뒤 호스트를 자식 프로세스로 spawn 한다. Chrome → 호스트는 stdin 으로 최대 64MiB, 호스트 → Chrome 은 stdout 으로 최대 1MB. 메시지 하나는 4바이트 길이 헤더 다음 UTF-8 JSON 이다. stdout 에 print 한 글자라도 새면 길이 자리에 끼어 프로토콜이 깨지므로 로그는 stderr 로 보낸다.

호스트를 OS 의 정해진 자리에 manifest 로 올린다 — Windows 는 레지스트리 키, macOS·Linux 는 지정된 디렉터리(macOS 는 ~/Library/Application Support/Google/Chrome/NativeMessagingHosts/). manifest 는 name·description·path·type(stdio)·allowed_origins 를 갖는다. path 는 절대경로여야 한다. allowed_origins 가 게이트다: 확장이 호출하면 Chrome 이 이 목록에 그 확장이 있는지 대조해 있을 때만 path 의 바이너리를 띄운다. 와일드카드는 못 쓴다 — 확장이 아무 프로그램이나 실행하지 못하는 이유다.

Chrome 이 path 의 바이너리를 자식 프로세스로 spawn 하고, 대화는 소켓도 HTTP 도 아니고 stdin/stdout 이다. 메시지마다 네이티브 바이트 순서의 4바이트 길이 헤더 다음에 UTF-8 JSON 본문이 온다. 읽을 때는 4바이트를 읽어 길이를 풀고 그만큼 본문을 읽는다 — 4바이트가 비어 있으면 Chrome 이 파이프를 닫은 것이니 종료한다. 보낼 때도 길이를 먼저 쓰고 본문을 쓰고 flush 한다. stdout 에 print 로 글자 하나라도 새면 그게 길이 헤더 자리에 끼어 프로토콜이 깨지니 로그는 stderr 로 보낸다. 호스트가 부르는 프로그램(yt-dlp)도 절대경로로 부른다 — GUI 로 띄운 Chrome 은 .zshrc 를 안 읽고 호스트는 사용자 셸 환경을 물려받지 않는다.

sendNativeMessage·connectNative 는 background(service worker)에서만 부를 수 있다. content script 는 통로 밖이라 흐름이 두 파일로 갈라진다: content.js 는 페이지에서 값만 뽑아 runtime.sendMessage 로 넘기고, background.js 가 네이티브 통신을 한다 — 응답이 비동기라 onMessage 리스너에서 true 를 돌려 채널을 열어둔다. sendNativeMessage 는 첫 응답 뒤 프로세스가 끝나 값 던지고 끝에 맞고, 진행률을 흘려보내려면 connectNative 로 Port 를 열어둔다. 크기 제한이 비대칭이다: 호스트 → Chrome 은 1MB, Chrome → 호스트는 64MiB. 돌려보낼 게 크면 잘라 보내거나(stderr 를 500자로) connectNative 로 나눠 보낸다.

근거 — manifest 필드·와일드카드 불가·크기 제한은 공식 문서 그대로다.1

Footnotes

  1. manifest는 name·description·path·type·allowed_origins 를 갖는다. “List of extensions that should have access to the native messaging host. allowed_origins values can’t contain wildcards.” / 크기 제한 — “The maximum size of a single message from the native messaging host is 1 MB…”, “The maximum size of the message sent to the native messaging host is 64 MiB.” (Native messaging — Chrome for Developers) ↩

#browser-extension#native-messaging#chrome
#553

Chrome 외부 앱 딥링크 "항상 열기" 해제

커스텀 스킴(myapp://) 다이얼로그에서 “항상 열기 허용”을 실수로 체크해 되돌리고 싶을 때. 설정 UI 에는 항목이 없다 — 체크는 프로필의 Preferences JSON 에 origin 단위로 저장된다.1

"protocol_handler": {
  "allowed_origin_protocol_pairs": { "https://example.com": { "myapp": true } }
}

“항상 열기”를 체크하면 허용이 origin 단위로 저장된다. chrome://settings/handlers 는 웹 프로토콜 핸들러(mailto: 등)만 다루는 별개 화면이라 여기서는 못 푼다. ① chrome://settings/content/all 에서 사이트 데이터를 삭제한다 → 재시작해 다이얼로그가 다시 뜨면 해제된 것이다. 안 뜨면 ② Chrome 을 백그라운드까지 완전 종료하고 → Preferences 에서 그 origin 의 스킴 항목을 지운 뒤 → 재시작해 다시 확인한다. ② 를 건너뛰고 실행 중에 편집하면 종료 시 메모리 상태로 덮어써 되돌아간다. excluded_schemes 에 true 인 스킴은 반대로 차단 상태이고, 같은 파일에서 푼다.

OS 경로
macOS ~/Library/Application Support/Google/Chrome/<Profile>/Preferences
Windows %LOCALAPPDATA%\Google\Chrome\User Data\<Profile>\Preferences
Linux ~/.config/google-chrome/<Profile>/Preferences

Footnotes

  1. “Dictionary of origins that have permission to launch at least one protocol without first prompting the user. Each origin is a nested dictionary. Within an origin dictionary, if a protocol is present with value |true|, that protocol may be launched by that origin without first prompting the user.” — kProtocolHandlerPerOriginAllowedProtocols = "protocol_handler.allowed_origin_protocol_pairs" (chrome/common/pref_names.h — Chromium) ↩

#chrome#deep-link#troubleshooting#macos
#593