Documentation

Overview

    Package sumdb implements the HTTP protocols for serving or accessing a module checksum database.

    Index

    Constants

    This section is empty.

    Variables

    View Source
    var ErrGONOSUMDB = errors.New("skipped (listed in GONOSUMDB)")

      ErrGONOSUMDB is returned by Lookup for paths that match a pattern listed in the GONOSUMDB list (set by SetGONOSUMDB, usually from the environment variable).

      View Source
      var ErrSecurity = errors.New("security error: misbehaving server")

        ErrSecurity is returned by Client operations that invoke Client.SecurityError.

        View Source
        var ErrWriteConflict = errors.New("write conflict")

          ErrWriteConflict signals a write conflict during Client.WriteConfig.

          View Source
          var ServerPaths = []string{
          	"/lookup/",
          	"/latest",
          	"/tile/",
          }

            ServerPaths are the URL paths the Server can (and should) serve.

            Typically a server will do:

            srv := sumdb.NewServer(ops)
            for _, path := range sumdb.ServerPaths {
            	http.Handle(path, srv)
            }
            

            Functions

            This section is empty.

            Types

            type Client

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

              A Client is a client connection to a checksum database. All the methods are safe for simultaneous use by multiple goroutines.

              func NewClient

              func NewClient(ops ClientOps) *Client

                NewClient returns a new Client using the given Client.

                func (*Client) Lookup

                func (c *Client) Lookup(path, vers string) (lines []string, err error)

                  Lookup returns the go.sum lines for the given module path and version. The version may end in a /go.mod suffix, in which case Lookup returns the go.sum lines for the module's go.mod-only hash.

                  func (*Client) SetGONOSUMDB

                  func (c *Client) SetGONOSUMDB(list string)

                    SetGONOSUMDB sets the list of comma-separated GONOSUMDB patterns for the Client. For any module path matching one of the patterns, Lookup will return ErrGONOSUMDB. SetGONOSUMDB can be called at most once, and if so it must be called before the first call to Lookup.

                    func (*Client) SetTileHeight

                    func (c *Client) SetTileHeight(height int)

                      SetTileHeight sets the tile height for the Client. Any call to SetTileHeight must happen before the first call to Lookup. If SetTileHeight is not called, the Client defaults to tile height 8. SetTileHeight can be called at most once, and if so it must be called before the first call to Lookup.

                      type ClientOps

                      type ClientOps interface {
                      	// ReadRemote reads and returns the content served at the given path
                      	// on the remote database server. The path begins with "/lookup" or "/tile/",
                      	// and there is no need to parse the path in any way.
                      	// It is the implementation's responsibility to turn that path into a full URL
                      	// and make the HTTP request. ReadRemote should return an error for
                      	// any non-200 HTTP response status.
                      	ReadRemote(path string) ([]byte, error)
                      
                      	// ReadConfig reads and returns the content of the named configuration file.
                      	// There are only a fixed set of configuration files.
                      	//
                      	// "key" returns a file containing the verifier key for the server.
                      	//
                      	// serverName + "/latest" returns a file containing the latest known
                      	// signed tree from the server.
                      	// To signal that the client wishes to start with an "empty" signed tree,
                      	// ReadConfig can return a successful empty result (0 bytes of data).
                      	ReadConfig(file string) ([]byte, error)
                      
                      	// WriteConfig updates the content of the named configuration file,
                      	// changing it from the old []byte to the new []byte.
                      	// If the old []byte does not match the stored configuration,
                      	// WriteConfig must return ErrWriteConflict.
                      	// Otherwise, WriteConfig should atomically replace old with new.
                      	// The "key" configuration file is never written using WriteConfig.
                      	WriteConfig(file string, old, new []byte) error
                      
                      	// ReadCache reads and returns the content of the named cache file.
                      	// Any returned error will be treated as equivalent to the file not existing.
                      	// There can be arbitrarily many cache files, such as:
                      	//	serverName/lookup/pkg@version
                      	//	serverName/tile/8/1/x123/456
                      	ReadCache(file string) ([]byte, error)
                      
                      	// WriteCache writes the named cache file.
                      	WriteCache(file string, data []byte)
                      
                      	// Log prints the given log message (such as with log.Print)
                      	Log(msg string)
                      
                      	// SecurityError prints the given security error log message.
                      	// The Client returns ErrSecurity from any operation that invokes SecurityError,
                      	// but the return value is mainly for testing. In a real program,
                      	// SecurityError should typically print the message and call log.Fatal or os.Exit.
                      	SecurityError(msg string)
                      }

                        A ClientOps provides the external operations (file caching, HTTP fetches, and so on) needed by the Client. The methods must be safe for concurrent use by multiple goroutines.

                        type Server

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

                          A Server is the checksum database HTTP server, which implements http.Handler and should be invoked to serve the paths listed in ServerPaths.

                          func NewServer

                          func NewServer(ops ServerOps) *Server

                            NewServer returns a new Server using the given operations.

                            func (*Server) ServeHTTP

                            func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)

                            type ServerOps

                            type ServerOps interface {
                            	// Signed returns the signed hash of the latest tree.
                            	Signed(ctx context.Context) ([]byte, error)
                            
                            	// ReadRecords returns the content for the n records id through id+n-1.
                            	ReadRecords(ctx context.Context, id, n int64) ([][]byte, error)
                            
                            	// Lookup looks up a record for the given module,
                            	// returning the record ID.
                            	Lookup(ctx context.Context, m module.Version) (int64, error)
                            
                            	// ReadTileData reads the content of tile t.
                            	// It is only invoked for hash tiles (t.L ≥ 0).
                            	ReadTileData(ctx context.Context, t tlog.Tile) ([]byte, error)
                            }

                              A ServerOps provides the external operations (underlying database access and so on) needed by the Server.

                              type TestServer

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

                                A TestServer is an in-memory implementation of Server for testing.

                                func NewTestServer

                                func NewTestServer(signer string, gosum func(path, vers string) ([]byte, error)) *TestServer

                                  NewTestServer constructs a new TestServer that will sign its tree with the given signer key (see golang.org/x/mod/sumdb/note) and fetch new records as needed by calling gosum.

                                  func (*TestServer) Lookup

                                  func (s *TestServer) Lookup(ctx context.Context, m module.Version) (int64, error)

                                  func (*TestServer) ReadRecords

                                  func (s *TestServer) ReadRecords(ctx context.Context, id, n int64) ([][]byte, error)

                                  func (*TestServer) ReadTileData

                                  func (s *TestServer) ReadTileData(ctx context.Context, t tlog.Tile) ([]byte, error)

                                  func (*TestServer) Signed

                                  func (s *TestServer) Signed(ctx context.Context) ([]byte, error)

                                  Directories

                                  Path Synopsis
                                  Package dirhash defines hashes over directory trees.
                                  Package dirhash defines hashes over directory trees.
                                  Package note defines the notes signed by the Go module database server.
                                  Package note defines the notes signed by the Go module database server.
                                  Package storage defines storage interfaces for and a basic implementation of a checksum database.
                                  Package storage defines storage interfaces for and a basic implementation of a checksum database.
                                  Package tlog implements a tamper-evident log used in the Go module go.sum database server.
                                  Package tlog implements a tamper-evident log used in the Go module go.sum database server.