go-omaha: github.com/coreos/go-omaha/omaha Index | Examples | Files | Directories

package omaha

import "github.com/coreos/go-omaha/omaha"

Google's Omaha application update protocol, version 3.

Omaha is a poll based protocol using XML. Requests are made by clients to check for updates or report events of an update process. Responses are given by the server to provide update information, if any, or to simply acknowledge the receipt of event status.

https://github.com/google/omaha/blob/master/doc/ServerProtocolV3.md

Index

Examples

Package Files

codes.go handler.go isclosed.go package.go parse.go protocol.go server.go system.go trivial_server.go update.go

Variables

var (
    PackageHashMismatchError = errors.New("package hash is invalid")
    PackageSizeMismatchError = errors.New("package size is invalid")
)

func LocalArch Uses

func LocalArch() string

Translate GOARCH to Omaha's choice of names, because no two independent software projects *ever* use the same set of architecture names. ;-)

func LocalPlatform Uses

func LocalPlatform() string

Translate GOOS to Omaha's platform names as best as we can.

type Action Uses

type Action struct {
    Event string `xml:"event,attr"`

    // update engine extensions for event="postinstall"
    DisplayVersion        string `xml:"DisplayVersion,attr,omitempty"`
    SHA256                string `xml:"sha256,attr,omitempty"`
    NeedsAdmin            bool   `xml:"needsadmin,attr,omitempty"`
    IsDeltaPayload        bool   `xml:"IsDeltaPayload,attr,omitempty"`
    DisablePayloadBackoff bool   `xml:"DisablePayloadBackoff,attr,omitempty"`
    MaxFailureCountPerURL uint   `xml:"MaxFailureCountPerUrl,attr,omitempty"`
    MetadataSignatureRsa  string `xml:"MetadataSignatureRsa,attr,omitempty"`
    MetadataSize          string `xml:"MetadataSize,attr,omitempty"`
    Deadline              string `xml:"deadline,attr,omitempty"`
    MoreInfo              string `xml:"MoreInfo,attr,omitempty"`
    Prompt                bool   `xml:"Prompt,attr,omitempty"`
}

type AppRequest Uses

type AppRequest struct {
    Ping        *PingRequest    `xml:"ping"`
    UpdateCheck *UpdateRequest  `xml:"updatecheck"`
    Events      []*EventRequest `xml:"event" json:",omitempty"`
    ID          string          `xml:"appid,attr,omitempty"`
    Client      string          `xml:"client,attr,omitempty"`
    InstallAge  string          `xml:"installage,attr,omitempty"`
    Lang        string          `xml:"lang,attr,omitempty"`
    NextVersion string          `xml:"nextversion,attr,omitempty"`
    Version     string          `xml:"version,attr,omitempty"`

    // update engine extensions
    Board     string `xml:"board,attr,omitempty"`
    DeltaOK   bool   `xml:"delta_okay,attr,omitempty"`
    FromTrack string `xml:"from_track,attr,omitempty"`
    Track     string `xml:"track,attr,omitempty"`

    // coreos update engine extensions
    AlephVersion string `xml:"alephversion,attr,omitempty"`
    BootID       string `xml:"bootid,attr,omitempty"`
    MachineID    string `xml:"machineid,attr,omitempty"`
    OEM          string `xml:"oem,attr,omitempty"`
    OEMVersion   string `xml:"oemversion,attr,omitempty"`
}

func (*AppRequest) AddEvent Uses

func (a *AppRequest) AddEvent() *EventRequest

func (*AppRequest) AddPing Uses

func (a *AppRequest) AddPing() *PingRequest

func (*AppRequest) AddUpdateCheck Uses

func (a *AppRequest) AddUpdateCheck() *UpdateRequest

type AppResponse Uses

type AppResponse struct {
    Ping        *PingResponse    `xml:"ping"`
    UpdateCheck *UpdateResponse  `xml:"updatecheck"`
    Events      []*EventResponse `xml:"event" json:",omitempty"`
    ID          string           `xml:"appid,attr,omitempty"`
    Status      AppStatus        `xml:"status,attr,omitempty"`
}

func (*AppResponse) AddEvent Uses

func (a *AppResponse) AddEvent() *EventResponse

func (*AppResponse) AddPing Uses

func (a *AppResponse) AddPing() *PingResponse

func (*AppResponse) AddUpdateCheck Uses

func (a *AppResponse) AddUpdateCheck(status UpdateStatus) *UpdateResponse

type AppStatus Uses

type AppStatus string
const (
    // Standard values
    AppOK         AppStatus = "ok"
    AppRestricted AppStatus = "restricted"
    AppUnknownID  AppStatus = "error-unknownApplication"
    AppInvalidID  AppStatus = "error-invalidAppId"

    // Extra error values
    AppInvalidVersion AppStatus = "error-invalidVersion"
    AppInternalError  AppStatus = "error-internal"
)

func (AppStatus) Error Uses

func (a AppStatus) Error() string

Make AppStatus easy to use as an error

type DayStart Uses

type DayStart struct {
    ElapsedSeconds string `xml:"elapsed_seconds,attr"`
}

type EventRequest Uses

type EventRequest struct {
    Type            EventType   `xml:"eventtype,attr"`
    Result          EventResult `xml:"eventresult,attr"`
    ErrorCode       int         `xml:"errorcode,attr,omitempty"`
    NextVersion     string      `xml:"nextversion,attr,omitempty"`
    PreviousVersion string      `xml:"previousversion,attr,omitempty"`
}

type EventResponse Uses

type EventResponse struct {
    Status string `xml:"status,attr"` // Always "ok".
}

type EventResult Uses

type EventResult int
const (
    EventResultError                 EventResult = 0
    EventResultSuccess               EventResult = 1
    EventResultSuccessReboot         EventResult = 2
    EventResultSuccessRestartBrowser EventResult = 3
    EventResultCancelled             EventResult = 4
    EventResultErrorInstallerMSI     EventResult = 5
    EventResultErrorInstallerOther   EventResult = 6
    EventResultNoUpdate              EventResult = 7
    EventResultInstallerSystem       EventResult = 8
    EventResultUpdateDeferred        EventResult = 9
    EventResultHandoffError          EventResult = 10
)

func (EventResult) String Uses

func (e EventResult) String() string

type EventType Uses

type EventType int
const (
    EventTypeUnknown                      EventType = 0
    EventTypeDownloadComplete             EventType = 1
    EventTypeInstallComplete              EventType = 2
    EventTypeUpdateComplete               EventType = 3
    EventTypeUninstall                    EventType = 4
    EventTypeDownloadStarted              EventType = 5
    EventTypeInstallStarted               EventType = 6
    EventTypeNewApplicationInstallStarted EventType = 9
    EventTypeSetupStarted                 EventType = 10
    EventTypeSetupFinished                EventType = 11
    EventTypeUpdateApplicationStarted     EventType = 12
    EventTypeUpdateDownloadStarted        EventType = 13
    EventTypeUpdateDownloadFinished       EventType = 14
    EventTypeUpdateInstallerStarted       EventType = 15
    EventTypeSetupUpdateBegin             EventType = 16
    EventTypeSetupUpdateComplete          EventType = 17
    EventTypeRegisterProductComplete      EventType = 20
    EventTypeOEMInstallFirstCheck         EventType = 30
    EventTypeAppSpecificCommandStarted    EventType = 40
    EventTypeAppSpecificCommandEnded      EventType = 41
    EventTypeSetupFailure                 EventType = 100
    EventTypeComServerFailure             EventType = 102
    EventTypeSetupUpdateFailure           EventType = 103
)

func (EventType) String Uses

func (e EventType) String() string

type Manifest Uses

type Manifest struct {
    Packages []*Package `xml:"packages>package"`
    Actions  []*Action  `xml:"actions>action"`
    Version  string     `xml:"version,attr"`
}

func (*Manifest) AddAction Uses

func (m *Manifest) AddAction(event string) *Action

func (*Manifest) AddPackage Uses

func (m *Manifest) AddPackage() *Package

func (*Manifest) AddPackageFromPath Uses

func (m *Manifest) AddPackageFromPath(path string) (*Package, error)

type OS Uses

type OS struct {
    Platform    string `xml:"platform,attr,omitempty"`
    Version     string `xml:"version,attr,omitempty"`
    ServicePack string `xml:"sp,attr,omitempty"`
    Arch        string `xml:"arch,attr,omitempty"`
}

type OmahaHandler Uses

type OmahaHandler struct {
    Updater
}

func (*OmahaHandler) ServeHTTP Uses

func (o *OmahaHandler) ServeHTTP(w http.ResponseWriter, httpReq *http.Request)

type Package Uses

type Package struct {
    Name     string `xml:"name,attr"`
    SHA1     string `xml:"hash,attr"`
    SHA256   string `xml:"hash_sha256,attr,omitempty"`
    Size     uint64 `xml:"size,attr"`
    Required bool   `xml:"required,attr"`
}

Package represents a single downloadable file.

func (*Package) FromPath Uses

func (p *Package) FromPath(name string) error

func (*Package) FromReader Uses

func (p *Package) FromReader(r io.Reader) error

func (*Package) Verify Uses

func (p *Package) Verify(dir string) error

func (*Package) VerifyReader Uses

func (p *Package) VerifyReader(r io.Reader) error

type PingRequest Uses

type PingRequest struct {
    Active               int  `xml:"active,attr,omitempty"`
    LastActiveReportDays *int `xml:"a,attr,omitempty"`
    LastReportDays       int  `xml:"r,attr,omitempty"`
}

type PingResponse Uses

type PingResponse struct {
    Status string `xml:"status,attr"` // Always "ok".
}

type Request Uses

type Request struct {
    XMLName       xml.Name      `xml:"request" json:"-"`
    OS            *OS           `xml:"os"`
    Apps          []*AppRequest `xml:"app"`
    Protocol      string        `xml:"protocol,attr"`
    InstallSource string        `xml:"installsource,attr,omitempty"`
    IsMachine     int           `xml:"ismachine,attr,omitempty"`
    RequestID     string        `xml:"requestid,attr,omitempty"`
    SessionID     string        `xml:"sessionid,attr,omitempty"`
    TestSource    string        `xml:"testsource,attr,omitempty"`
    UserID        string        `xml:"userid,attr,omitempty"`
    Version       string        `xml:"version,attr,omitempty"`

    // update engine extension, duplicates the version attribute.
    UpdaterVersion string `xml:"updaterversion,attr,omitempty"`
}

Request sent by the Omaha client

func NewRequest Uses

func NewRequest() *Request

Code:

request := NewRequest()
request.Version = ""
request.OS = &OS{
    Platform:    "Chrome OS",
    Version:     "Indy",
    ServicePack: "ForcedUpdate_x86_64",
}
app := request.AddApp("{27BD862E-8AE8-4886-A055-F7F1A6460627}", "1.0.0.0")
app.AddUpdateCheck()

event := app.AddEvent()
event.Type = EventTypeDownloadComplete
event.Result = EventResultError

if raw, err := xml.MarshalIndent(request, "", " "); err != nil {
    fmt.Println(err)
    return
} else {
    fmt.Printf("%s%s\n", xml.Header, raw)
}

Output:

<?xml version="1.0" encoding="UTF-8"?>
<request protocol="3.0">
 <os platform="Chrome OS" version="Indy" sp="ForcedUpdate_x86_64"></os>
 <app appid="{27BD862E-8AE8-4886-A055-F7F1A6460627}" version="1.0.0.0">
  <updatecheck></updatecheck>
  <event eventtype="1" eventresult="0"></event>
 </app>
</request>

func ParseRequest Uses

func ParseRequest(contentType string, body io.Reader) (*Request, error)

ParseRequest verifies and returns the parsed Request document. The MIME Content-Type header may be provided to sanity check its value; if blank it is assumed to be XML in UTF-8.

func (*Request) AddApp Uses

func (r *Request) AddApp(id, version string) *AppRequest

func (*Request) GetApp Uses

func (r *Request) GetApp(id string) *AppRequest

type Response Uses

type Response struct {
    XMLName  xml.Name       `xml:"response" json:"-"`
    DayStart DayStart       `xml:"daystart"`
    Apps     []*AppResponse `xml:"app"`
    Protocol string         `xml:"protocol,attr"`
    Server   string         `xml:"server,attr"`
}

Response sent by the Omaha server

func NewResponse Uses

func NewResponse() *Response

Code:

response := NewResponse()
app := response.AddApp("{52F1B9BC-D31A-4D86-9276-CBC256AADF9A}", "ok")
app.AddPing()
u := app.AddUpdateCheck(UpdateOK)
u.AddURL("http://localhost/updates")
m := u.AddManifest("9999.0.0")
k := m.AddPackage()
k.SHA1 = "+LXvjiaPkeYDLHoNKlf9qbJwvnk="
k.Name = "update.gz"
k.Size = 67546213
k.Required = true
a := m.AddAction("postinstall")
a.DisplayVersion = "9999.0.0"
a.SHA256 = "0VAlQW3RE99SGtSB5R4m08antAHO8XDoBMKDyxQT/Mg="
a.NeedsAdmin = false
a.IsDeltaPayload = true
a.DisablePayloadBackoff = true

if raw, err := xml.MarshalIndent(response, "", " "); err != nil {
    fmt.Println(err)
    return
} else {
    fmt.Printf("%s%s\n", xml.Header, raw)
}

Output:

<?xml version="1.0" encoding="UTF-8"?>
<response protocol="3.0" server="go-omaha">
 <daystart elapsed_seconds="0"></daystart>
 <app appid="{52F1B9BC-D31A-4D86-9276-CBC256AADF9A}" status="ok">
  <ping status="ok"></ping>
  <updatecheck status="ok">
   <urls>
    <url codebase="http://localhost/updates"></url>
   </urls>
   <manifest version="9999.0.0">
    <packages>
     <package name="update.gz" hash="+LXvjiaPkeYDLHoNKlf9qbJwvnk=" size="67546213" required="true"></package>
    </packages>
    <actions>
     <action event="postinstall" DisplayVersion="9999.0.0" sha256="0VAlQW3RE99SGtSB5R4m08antAHO8XDoBMKDyxQT/Mg=" IsDeltaPayload="true" DisablePayloadBackoff="true"></action>
    </actions>
   </manifest>
  </updatecheck>
 </app>
</response>

func ParseResponse Uses

func ParseResponse(contentType string, body io.Reader) (*Response, error)

ParseResponse verifies and returns the parsed Response document. The MIME Content-Type header may be provided to sanity check its value; if blank it is assumed to be XML in UTF-8.

func (*Response) AddApp Uses

func (r *Response) AddApp(id string, status AppStatus) *AppResponse

func (*Response) GetApp Uses

func (r *Response) GetApp(id string) *AppResponse

type Server Uses

type Server struct {
    Updater

    Mux *http.ServeMux
    // contains filtered or unexported fields
}

func NewServer Uses

func NewServer(addr string, updater Updater) (*Server, error)

func (*Server) Addr Uses

func (s *Server) Addr() net.Addr

func (*Server) Destroy Uses

func (s *Server) Destroy() error

func (*Server) Serve Uses

func (s *Server) Serve() error

type TrivialServer Uses

type TrivialServer struct {
    *Server
    // contains filtered or unexported fields
}

TrivialServer is an extremely basic Omaha server that ignores all incoming metadata, always responding with the same update response. The update is constructed by calling AddPackage one or more times.

func NewTrivialServer Uses

func NewTrivialServer(addr string) (*TrivialServer, error)

func (*TrivialServer) AddPackage Uses

func (ts *TrivialServer) AddPackage(file, name string) error

AddPackage adds a new file to the update response. file is the local filesystem path, name is the final URL component.

func (*TrivialServer) SetVersion Uses

func (ts *TrivialServer) SetVersion(version string)

SetVersion sets the manifest's version with the provided one.

type URL Uses

type URL struct {
    CodeBase string `xml:"codebase,attr"`
}

type Update Uses

type Update struct {
    XMLName         xml.Name `xml:"update" json:"-"`
    ID              string   `xml:"appid,attr"`
    PreviousVersion string   `xml:"previousversion,attr,omitempty"`
    URL             URL      `xml:"urls>url"`
    Manifest

    // The delta_okay request attribute is an update_engine extension.
    RespectDeltaOK bool `xml:"respect_delta_okay,attr,omitempty"`
}

Update is a manifest for a single omaha update response. It extends the standard Manifest protocol element with the application id and previous version which are used to match against the update request. A blank previous version indicates this update can be applied to any existing install. The application id may not be blank.

func (*Update) URLs Uses

func (u *Update) URLs(prefixes []string) []*URL

The URL attribute in Update is currently assumed to be a relative path which may be found on multiple mirrors. A server using this is expected to know the mirror prefix(s) it can give the client.

type UpdateRequest Uses

type UpdateRequest struct {
    TargetVersionPrefix string `xml:"targetversionprefix,attr,omitempty"`
}

type UpdateResponse Uses

type UpdateResponse struct {
    URLs     []*URL       `xml:"urls>url" json:",omitempty"`
    Manifest *Manifest    `xml:"manifest"`
    Status   UpdateStatus `xml:"status,attr,omitempty"`
}

func (*UpdateResponse) AddManifest Uses

func (u *UpdateResponse) AddManifest(version string) *Manifest

func (*UpdateResponse) AddURL Uses

func (u *UpdateResponse) AddURL(codebase string) *URL

type UpdateStatus Uses

type UpdateStatus string
const (
    NoUpdate                   UpdateStatus = "noupdate"
    UpdateOK                   UpdateStatus = "ok"
    UpdateOSNotSupported       UpdateStatus = "error-osnotsupported"
    UpdateUnsupportedProtocol  UpdateStatus = "error-unsupportedProtocol"
    UpdatePluginRestrictedHost UpdateStatus = "error-pluginRestrictedHost"
    UpdateHashError            UpdateStatus = "error-hash"
    UpdateInternalError        UpdateStatus = "error-internal"
)

func (UpdateStatus) Error Uses

func (u UpdateStatus) Error() string

Make UpdateStatus easy to use as an error

type Updater Uses

type Updater interface {
    CheckApp(req *Request, app *AppRequest) error
    CheckUpdate(req *Request, app *AppRequest) (*Update, error)
    Event(req *Request, app *AppRequest, event *EventRequest)
    Ping(req *Request, app *AppRequest)
}

Updater provides a common interface for any backend that can respond to update requests made to an Omaha server.

type UpdaterStub Uses

type UpdaterStub struct{}

func (UpdaterStub) CheckApp Uses

func (u UpdaterStub) CheckApp(req *Request, app *AppRequest) error

func (UpdaterStub) CheckUpdate Uses

func (u UpdaterStub) CheckUpdate(req *Request, app *AppRequest) (*Update, error)

func (UpdaterStub) Event Uses

func (u UpdaterStub) Event(req *Request, app *AppRequest, event *EventRequest)

func (UpdaterStub) Ping Uses

func (u UpdaterStub) Ping(req *Request, app *AppRequest)

Directories

PathSynopsis
clientPackage client provides a general purpose Omaha update client implementation.

Package omaha imports 17 packages (graph) and is imported by 23 packages. Updated 2017-08-07. Refresh now. Tools for package owners.