proxy

Documentation

Overview

Package proxy implements a wrapper that proxies an analysis request to a Kythe indexer that does not speak protocol buffers or RPCs.

Communication with the underlying indexer is via JSON over pipes, with messages from the proxy to the indexer on one side and replies on the other. Each JSON message is sent as a single complete line terminated by a newline (LF) character.

Communication between proxy and indexer is in lock-step; there is only one transaction active at a time in either direction and the indexer initiates all requests.

The protocol between indexer (X) and proxy (P) is:

X → P: {"req":"analysis"}<LF>
P → X: {"rsp":"ok","args":{"unit":<unit>,"rev":<revision>,"fds":<addr>}}<LF>
       {"rsp":"error","args":<error>}<LF>

X → P: {"req":"analysis_wire"}<LF>
P → X: {"rsp":"ok","args":{"unit":<unit_wire>,"rev":<revision>,"fds":<addr>}}<LF>
       {"rsp":"error","args":<error>}<LF>

X → P: {"req":"output","args":[<entry>...]}<LF>
P → X: {"rsp":"ok"}<LF>
       {"rsp":"error","args":<error>}<LF>

X → P: {"req":"output_wire","args":[<entry_wire>...]}<LF>
P → X: {"rsp":"ok"}<LF>
       {"rsp":"error","args":<error>}<LF>

X → P: {"req":"done","args":{"ok":true,"msg":<error>}}<LF>
P → X: {"rsp":"ok"}<LF>
       {"rsp":"error","args":<error>}<LF>

X → P: {"req":"file","args":{"path":<path>,"digest":<digest>}}<LF>
P → X: {"rsp":"ok","args":{"path":<path>,"digest":<digest>,"content":<bytes>}}<LF>
       {"rsp":"error","args":<error>}<LF>

Where:

<addr>       -- service address
<bytes>      -- BASE-64 encoded bytes (string)
<digest>     -- file content digest (string)
<entry>      -- JSON encoded kythe.proto.Entry message
<entry_wire> -- BASE-64 encoded kythe.proto.Entry message in wire format (string)
<error>      -- error diagnostic (string)
<path>       -- file path (string)
<revision>   -- revision marker (string)
<unit>       -- JSON encoded kythe.proto.CompilationUnit message
<unit_wire>  -- BASE-64 encoded kythe.proto.CompilationUnit message in wire format (string)
<LF>         -- line feed character (decimal code 10)

When rsp="error" in a reply, the args are an error string. The ordinary flow for the indexer is:

{"req":"analysis"}   -- to start a new analysis task
{"req":"output",...} -- to send outputs for the task
{"req":"file",...}   -- to fetch required input files.
    ... (as many times as needed) ...
{"req":"done",...}   -- to mark the analysis as complete
                        and to report success/failure

The proxy supports an extra /kythe/code/json fact. Its value will be interpreted as a JSON-encoded kythe.proto.common.MarkedSource message and will be rewritted to the equivalent wire-encoded /kythe/code fact.

In case of an indexing error, the indexer is free to terminate the analysis early and report {"req":"done","args":{"ok":false}} to the driver.

In case of an error writing output data, the driver will report an error in response to the "output" call. Once this happens, the analysis is abandoned as if the indexer had called "done". Subsequent calls to "output" or "done" will behave as if no analysis is in progress. The indexer is free at that point to start a new analysis.

Index

• type Handler
• type Proxy
  • func New(in io.Reader, out io.Writer) *Proxy
  • func (p *Proxy) Run(h Handler) error

Types

type Handler

type Handler interface {
	// Analysis fetches a new analysis request. It is an error if there is an
	// unfinished request already in flight.
	Analysis() (*apb.AnalysisRequest, error)

	// Output delivers output from an ongoing analysis.
	Output(...*spb.Entry) error

	// Done reports an ongoing analysis as complete, with the error indicating
	// success or failure.
	Done(error)

	// File requests the contents of a file given a path and/or digest, at
	// least one of which must be nonempty.
	File(path, digest string) ([]byte, error)
}

A Handler provides callbacks to handle requests issued by the indexer.

type Proxy

type Proxy struct {
	// contains filtered or unexported fields
}

A Proxy processes requests from an indexer subprocess on the other end of a pipe by dispatching them to a callback handler. The caller must invoke Run to start processing requests.

func New

func New(in io.Reader, out io.Writer) *Proxy

New returns a proxy that reads requests from in and writes responses to out. The caller must invoke Run to start processing requests.

func (*Proxy) Run

func (p *Proxy) Run(h Handler) error

Run blocks serving requests from the indexer until communication with the indexer reports an error. The resulting error is returned unless it is io.EOF, in which case Run returns nil.