host

README

Native Messaging Host Module for Go

native-messaging-host is a module for sending native messaging protocol message marshalled from struct and receiving native messaging protocol message unmarshalled to struct. native-messaging-host can auto-update itself using update URL that response with Google Chrome update manifest, as well as it provides hook to install and uninstall manifest file to native messaging host location.

Installation and Usage

Package documentation can be found on GoDoc.

Installation can be done with a normal go get:

$ go get github.com/rickypc/native-messaging-host

Receiving Message

// Ensure func main returned after calling [runtime.Goexit][5].
defer os.Exit(0)

messaging := (&host.Host{}).Init()

// host.H is a shortcut to map[string]interface{}
request := &host.H{}

// Read message from os.Stdin to request.
if err := messaging.OnMessage(os.Stdin, request); err != nil {
  log.Fatalf("messaging.OnMessage error: %v", err)
}

// Log request.
log.Printf("request: %+v", request)

Sending Message

messaging := (&host.Host{}).Init()

// host.H is a shortcut to map[string]interface{}
response := &host.H{"key":"value"}

// Write message from response to os.Stdout.
if err := messaging.PostMessage(os.Stdout, response); err != nil {
  log.Fatalf("messaging.PostMessage error: %v", err)
}

// Log response.
log.Printf("response: %+v", response)

Auto Update Configuration

updates.xml example for cross platform executable:

<?xml version='1.0' encoding='UTF-8'?>
<gupdate xmlns='http://www.google.com/update2/response' protocol='2.0'>
  <app appid='tld.domain.sub.app.name'>
    <updatecheck codebase='https://sub.domain.tld/app.download.all' version='1.0.0' />
  </app>
</gupdate>

updates.xml example for individual platform executable:

<?xml version='1.0' encoding='UTF-8'?>
<gupdate xmlns='http://www.google.com/update2/response' protocol='2.0'>
  <app appid='tld.domain.sub.app.name'>
    <updatecheck codebase='https://sub.domain.tld/app.download.darwin' os='darwin' version='1.0.0' />
    <updatecheck codebase='https://sub.domain.tld/app.download.linux' os='linux' version='1.0.0' />
    <updatecheck codebase='https://sub.domain.tld/app.download.exe' os='windows' version='1.0.0' />
  </app>
</gupdate>

// It will do daily update check.
messaging := (&host.Host{
  AppName:   "tld.domain.sub.app.name",
  UpdateUrl: "https://sub.domain.tld/updates.xml", // It follows [update manifest][2]
  Version:   "1.0.0",                              // Current version, it must follow [SemVer][6]
}).Init()

Install and Uninstall Hooks

// AllowedExts is a list of extensions that should have access to the native messaging host. 
// See [native messaging manifest][7]
messaging := (&host.Host{
  AppName:     "tld.domain.sub.app.name",
  AllowedExts: []string{"chrome-extension://XXX/", "chrome-extension://YYY/"},
}).Init()

...

// When you need to install.
if err := messaging.Install(); err != nil {
  log.Printf("install error: %v", err)
}

...

// When you need to uninstall.
if err := host.Uninstall(); err != nil {
  log.Printf("uninstall error: %v", err)
}

Contributing

If you would like to contribute code to Native Messaging Host repository you can do so through GitHub by forking the repository and sending a pull request.

If you do not agree to Contribution Agreement, do not contribute any code to Native Messaging Host repository.

When submitting code, please make every effort to follow existing conventions and style in order to keep the code as readable as possible. Please also include appropriate test cases.

That's it! Thank you for your contribution!

License

Copyright (c) 2018 - 2020 Richard Huang.

This utility is free software, licensed under: Mozilla Public License (MPL-2.0).

Documentation and other similar content are provided under Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.

Documentation

Overview

Package host provides native-messaging host configurations, send and receive message handler, manifest install and uninstall, as well as auto update daily check.

Index

• Constants
• type App
• type H
• type Host
  • func (h *Host) AutoUpdateCheck()
  • func (h *Host) GetHttpClient() *http.Client
  • func (h *Host) Init() *Host
  • func (h *Host) Install() error
  • func (h *Host) MustGet(url string) *http.Response
  • func (h *Host) OnMessage(reader io.Reader, v interface{}) error
  • func (h *Host) PostMessage(writer io.Writer, v interface{}) error
  • func (h *Host) Uninstall() error
• type Update
• type UpdateCheckResponse
  • func (u *UpdateCheckResponse) GetUrlAndVersion(appName string) (string, string)

Constants

const (
	HttpContinueTimeout   = 5
	HttpKeepAlive         = 600
	HttpDialTimeout       = 10
	HttpOverallTimeout    = 15
	IdleTimeout           = 90
	MaxConnections        = 100
	ResponseHeaderTimeout = 10
	TLSDialTimeout        = 15
)

The Http connection and timeout configurations.

Types

type App

type App struct {
	AppId   *string   `xml:"appid,attr"`
	Updates []*Update `xml:"updatecheck"`
}

An App is represent one application returned by updates.xml.

<app appid='tld.domain.sub.app.name'></app>

type H

type H map[string]interface{}

H is a map[string]interface{} type shortcut and represents a dynamic key-value-pair data.

type Host

type Host struct {
	AppName     string           `json:"name"`
	AppDesc     string           `json:"description"`
	ExecName    string           `json:"path"`
	AppType     string           `json:"type"`
	AllowedExts []string         `json:"allowed_origins"`
	AutoUpdate  bool             `json:"-"`
	ByteOrder   binary.ByteOrder `json:"-"`
	UpdateUrl   string           `json:"-"`
	Version     string           `json:"-"`
}

Host represents a single native messaging host, where all native messaging host operations can be done.

func (*Host) AutoUpdateCheck

func (h *Host) AutoUpdateCheck()

AutoUpdateCheck downloads the latest update as necessary.

func (*Host) GetHttpClient

func (h *Host) GetHttpClient() *http.Client

GetHttpClient provides http client with configured connection and timeout.

func (*Host) Init

func (h *Host) Init() *Host

Init sets default value to its fields and return the Host pointer back.

* AppName is an application name in manifest file and will be defaulted to current executable file name without extension, if any.

* AppDesc is an application description in manifest file and will be defaulted to current AppName.

* AppType is an application communication type in manifest file and will be defaulted to "stdio".

* AutoUpdate indicates whether update check will be perform for this application and will be defaulted to true only if UpdateUrl and application Version are present, otherwise it will be false.

* ByteOrder specifies how to convert byte sequences into unsigned integers and will be defaulted to binary.LittleEndian.

* ExecName is an executable path used across the module and will get assigned to current executable's absolute path after the evaluation of any symbolic links.

messaging := (&host.Host{}).Init()

func (*Host) Install

func (h *Host) Install() error

Install creates native-messaging manifest file on appropriate location. It will return error when it come across one. See https://developer.chrome.com/extensions/nativeMessaging#native-messaging-host-location-nix

func (*Host) MustGet

func (h *Host) MustGet(url string) *http.Response

MustGet is a helper that wraps a http GET call to given URL and log error if any.

func (*Host) OnMessage

func (h *Host) OnMessage(reader io.Reader, v interface{}) error

OnMessage reads message header and message body from given reader and unmarshal to given struct. It will return error when it come across one.

// Ensure func main returned after calling runtime.Goexit
// See https://golang.org/pkg/runtime/#Goexit.
defer os.Exit(0)

messaging := (&host.Host{}).Init()

// host.H is a shortcut to map[string]interface{}
request := &host.H{}

// Read message from os.Stdin to request.
if err := messaging.OnMessage(os.Stdin, request); err != nil {
  log.Fatalf("messaging.OnMessage error: %v", err)
}

// Log request.
log.Printf("request: %+v", request)

func (*Host) PostMessage

func (h *Host) PostMessage(writer io.Writer, v interface{}) error

PostMessage marshals given struct and writes message header and message body to given writer. It will return error when it come across one.

messaging := (&host.Host{}).Init()

// host.H is a shortcut to map[string]interface{}
response := &host.H{"key":"value"}

// Write message from response to os.Stdout.
if err := messaging.PostMessage(os.Stdout, response); err != nil {
  log.Fatalf("messaging.PostMessage error: %v", err)
}

// Log response.
log.Printf("response: %+v", response)

func (*Host) Uninstall

func (h *Host) Uninstall() error

Uninstall removes native-messaging manifest file from installed location. It will return error when it come across one. See https://developer.chrome.com/extensions/nativeMessaging#native-messaging-host-location-nix

type Update

type Update struct {
	Goos    *string `xml:"os,attr"`
	Url     *string `xml:"codebase,attr"`
	Version *string `xml:"version,attr"`
}

An Update is represent application download URL and latest version.

It can have target OS optionally. This is an extended attribute that is not part of original Google Chrome update manifest.

<updatecheck codebase='https://sub.domain.tld/app.download.all' os='darwin' version='1.0.0' />

type UpdateCheckResponse

type UpdateCheckResponse struct {
	Apps    []*App   `xml:"app"`
	XMLName xml.Name `xml:"gupdate"`
}

An UpdateCheckResponse implements Google Chrome update manifest XML format borrowed from Google's Omaha. See https://developer.chrome.com/apps/autoupdate#update_manifest

<gupdate xmlns='http://www.google.com/update2/response' protocol='2.0'></gupdate>

func (*UpdateCheckResponse) GetUrlAndVersion

func (u *UpdateCheckResponse) GetUrlAndVersion(appName string) (string, string)

GetUrlAndVersion returns download URL and latest version of given application name.