From ae6e7537aa4bd0c76fc27c266ade4b02c6696b20 Mon Sep 17 00:00:00 2001 From: Jonathan Hall Date: Mon, 12 Aug 2024 13:35:17 +0200 Subject: [PATCH] chore: minor documentation updates, mostly (#73) - Add some hyperlinks - Spelling and grammar corrections --- auth.go | 8 ++++---- cache.go | 7 +------ command.go | 4 ++-- conn.go | 4 ++-- error.go | 2 +- options.go | 27 ++++++++++++++------------- row.go | 19 +++++++++++++------ ssl.go | 2 +- wire.go | 2 +- writer.go | 10 +++++++--- 10 files changed, 46 insertions(+), 39 deletions(-) diff --git a/auth.go b/auth.go index e6a9a2f..e761717 100644 --- a/auth.go +++ b/auth.go @@ -22,7 +22,7 @@ const ( authClearTextPassword authType = 3 ) -// AuthStrategy represents a authentication strategy used to authenticate a user +// AuthStrategy represents an authentication strategy used to authenticate a user. type AuthStrategy func(ctx context.Context, writer *buffer.Writer, reader *buffer.Reader) (_ context.Context, err error) // handleAuth handles the client authentication for the given connection. @@ -44,7 +44,7 @@ func (srv *Server) handleAuth(ctx context.Context, reader *buffer.Reader, writer // ClearTextPassword announces to the client to authenticate by sending a // clear text password and validates if the provided username and password (received // inside the client parameters) are valid. If the provided credentials are invalid -// or any unexpected error occures is an error returned and should the connection be closed. +// or any unexpected error occurs, an error returned and the connection should be closed. func ClearTextPassword(validate func(ctx context.Context, username, password string) (context.Context, bool, error)) AuthStrategy { return func(ctx context.Context, writer *buffer.Writer, reader *buffer.Reader) (_ context.Context, err error) { err = writeAuthType(writer, authClearTextPassword) @@ -88,13 +88,13 @@ func writeAuthType(writer *buffer.Writer, status authType) error { return writer.End() } -// IsSuperUser checks whether the given connection context is a super user +// IsSuperUser checks whether the given connection context is a super user. func IsSuperUser(ctx context.Context) bool { return false } // AuthenticatedUsername returns the username of the authenticated user of the -// given connection context +// given connection context. func AuthenticatedUsername(ctx context.Context) string { parameters := ClientParameters(ctx) return parameters[ParamUsername] diff --git a/cache.go b/cache.go index 91f6d3a..a0f7afa 100644 --- a/cache.go +++ b/cache.go @@ -121,10 +121,5 @@ func (cache *DefaultPortalCache) Execute(ctx context.Context, name string, write return nil } - err = portal.statement.fn(ctx, NewDataWriter(ctx, portal.statement.columns, portal.formats, writer), portal.parameters) - if err != nil { - return err - } - - return err + return portal.statement.fn(ctx, NewDataWriter(ctx, portal.statement.columns, portal.formats, writer), portal.parameters) } diff --git a/command.go b/command.go index 625f81f..2353d72 100644 --- a/command.go +++ b/command.go @@ -17,7 +17,7 @@ import ( ) // NewErrUnimplementedMessageType is called whenever a unimplemented message -// type is send. This error indicates to the client that the send message cannot +// type is sent. This error indicates to the client that the sent message cannot // be processed at this moment in time. func NewErrUnimplementedMessageType(t types.ClientMessage) error { err := fmt.Errorf("unimplemented client message type: %d", t) @@ -45,7 +45,7 @@ func NewErrMultipleCommandsStatements() error { return psqlerr.WithSeverity(psqlerr.WithCode(err, codes.Syntax), psqlerr.LevelError) } -// consumeCommands consumes incoming commands send over the Postgres wire connection. +// consumeCommands consumes incoming commands sent over the Postgres wire connection. // Commands consumed from the connection are returned through a go channel. // Responses for the given message type are written back to the client. // This method keeps consuming messages until the client issues a close message diff --git a/conn.go b/conn.go index f3b7c85..1044a6a 100644 --- a/conn.go +++ b/conn.go @@ -31,11 +31,11 @@ func TypeMap(ctx context.Context) *pgtype.Map { } // Parameters represents a parameters collection of parameter status keys and -// their values +// their values. type Parameters map[ParameterStatus]string // ParameterStatus represents a metadata key that could be defined inside a server/client -// metadata definition +// metadata definition. type ParameterStatus string // At present there is a hard-wired set of parameters for which ParameterStatus diff --git a/error.go b/error.go index 71d6374..72a8363 100644 --- a/error.go +++ b/error.go @@ -24,7 +24,7 @@ const ( errFieldConstraintName errFieldType = 'n' ) -// ErrorCode writes a error message as response to a command with the given +// ErrorCode writes an error message as response to a command with the given // severity and error message. A ready for query message is written back to the // client once the error has been written indicating the end of a command cycle. // https://www.postgresql.org/docs/current/static/protocol-error-fields.html diff --git a/options.go b/options.go index 29b6b9b..d14c206 100644 --- a/options.go +++ b/options.go @@ -4,11 +4,10 @@ import ( "context" "crypto/tls" "crypto/x509" + "log/slog" "regexp" "strconv" - "log/slog" - "github.com/jackc/pgx/v5/pgtype" "github.com/jeroenrinzema/psql-wire/pkg/buffer" "github.com/lib/pq/oid" @@ -25,9 +24,10 @@ type PreparedStatementFn func(ctx context.Context, writer DataWriter, parameters // Prepared is a small wrapper function returning a list of prepared statements. // More then one prepared statement could be returned within the simple query -// protocol. An error is returned when more then one prepared statement is -// returned in the extended query protocol. -// https://www.postgresql.org/docs/15/protocol-flow.html#PROTOCOL-FLOW-MULTI-STATEMENT +// protocol. An error is returned when more than one prepared statement is +// returned in the [extended query protocol]. +// +// [extended query protocol]: https://www.postgresql.org/docs/15/protocol-flow.html#PROTOCOL-FLOW-MULTI-STATEMENT func Prepared(stmts ...*PreparedStatement) PreparedStatements { return stmts } @@ -103,7 +103,7 @@ type CloseFn func(ctx context.Context) error type OptionFn func(*Server) error // Statements sets the statement cache used to cache statements for later use. By -// default is the DefaultStatementCache used to cache prepared statements. +// default [DefaultStatementCache] is used. func Statements(cache StatementCache) OptionFn { return func(srv *Server) error { srv.Statements = cache @@ -112,7 +112,7 @@ func Statements(cache StatementCache) OptionFn { } // Portals sets the portals cache used to cache statements for later use. By -// default is the DefaultPortalCache used to evaluate portals. +// default [DefaultPortalCache] is used. func Portals(cache PortalCache) OptionFn { return func(srv *Server) error { srv.Portals = cache @@ -191,7 +191,7 @@ func GlobalParameters(params Parameters) OptionFn { } } -// Logger sets the given zap logger as the default logger for the given server. +// Logger sets the given [slog.Logger] as the logger for the given server. func Logger(logger *slog.Logger) OptionFn { return func(srv *Server) error { srv.logger = logger @@ -209,8 +209,8 @@ func Version(version string) OptionFn { } // ExtendTypes provides the ability to extend the underlying connection types. -// Types registered inside the given pgtype.ConnInfo are registered to all -// incoming connections. +// Types registered inside the given [github.com/jackc/pgx/v5/pgtype.Map] are +// registered to all incoming connections. func ExtendTypes(fn func(*pgtype.Map)) OptionFn { return func(srv *Server) error { fn(srv.types) @@ -246,11 +246,12 @@ func Session(fn SessionHandler) OptionFn { // QueryParameters represents a regex which could be used to identify and lookup // parameters defined inside a given query. Parameters could be defined as -// positional parameters and un-positional parameters. -// https://www.postgresql.org/docs/15/sql-expressions.html#SQL-EXPRESSIONS-PARAMETERS-POSITIONAL +// [positional parameters] and non-positional parameters. +// +// [positional parameters]: https://www.postgresql.org/docs/15/sql-expressions.html#SQL-EXPRESSIONS-PARAMETERS-POSITIONAL var QueryParameters = regexp.MustCompile(`\$(\d+)|\?`) -// ParseParameters attempts ot parse the parameters in the given string and +// ParseParameters attempts to parse the parameters in the given string and // returns the expected parameters. This is necessary for the query protocol // where the parameter types are expected to be defined in the extended query protocol. func ParseParameters(query string) []oid.Oid { diff --git a/row.go b/row.go index af42853..8a80daf 100644 --- a/row.go +++ b/row.go @@ -10,14 +10,16 @@ import ( "github.com/lib/pq/oid" ) -// Columns represent a collection of columns +// Columns represent a collection of columns. type Columns []Column -// Define writes the table RowDescription headers for the given table and the +// Define writes the table [RowDescription] headers for the given table and the // containing columns. The headers have to be written before any data rows could // be send back to the client. The given columns are encoded using the given // format codes. Columns could be encoded as Text or Binary. If you provide a // single format code, it will be applied to all columns. +// +// [RowDescription]: https://www.postgresql.org/docs/current/protocol-message-formats.html#PROTOCOL-MESSAGE-FORMATS-ROWDESCRIPTION func (columns Columns) Define(ctx context.Context, writer *buffer.Writer, formats []FormatCode) error { if len(columns) == 0 { return nil @@ -73,9 +75,10 @@ func (columns Columns) Write(ctx context.Context, formats []FormatCode, writer * return writer.End() } -// Column represents a table column and its attributes such as name, type and +// Column represents a table column and its [attributes] such as name, type and // encode formatter. -// https://www.postgresql.org/docs/8.3/catalog-pg-attribute.html +// +// [attributes]: https://www.postgresql.org/docs/8.3/catalog-pg-attribute.html type Column struct { Table int32 // table id ID int32 // column identifier @@ -88,8 +91,10 @@ type Column struct { } // Define writes the column header values to the given writer. -// This method is used to define a column inside RowDescription message defining +// This method is used to define a column inside [RowDescription] message defining // the column type, width, and name. +// +// [RowDescription]: https://www.postgresql.org/docs/current/protocol-message-formats.html#PROTOCOL-MESSAGE-FORMATS-ROWDESCRIPTION func (column Column) Define(ctx context.Context, writer *buffer.Writer, format FormatCode) { writer.AddString(column.Name) writer.AddNullTerminate() @@ -116,7 +121,9 @@ func (column Column) Define(ctx context.Context, writer *buffer.Writer, format F // Write encodes the given source value using the column type definition and connection // info. The encoded byte buffer is added to the given write buffer. This method -// Is used to encode values and return them inside a DataRow message. +// Is used to encode values and return them inside a [DataRow] message. +// +// [DataRow]: https://www.postgresql.org/docs/current/protocol-message-formats.html#PROTOCOL-MESSAGE-FORMATS-DATAROW func (column Column) Write(ctx context.Context, writer *buffer.Writer, format FormatCode, src any) (err error) { if ctx.Err() != nil { return ctx.Err() diff --git a/ssl.go b/ssl.go index 49c4427..e53de49 100644 --- a/ssl.go +++ b/ssl.go @@ -1,6 +1,6 @@ package wire -// sslIdentifier represents a the bytes identifying whether the given connection +// sslIdentifier represents the bytes identifying whether the given connection // supports SSL. type sslIdentifier []byte diff --git a/wire.go b/wire.go index 474b038..198e456 100644 --- a/wire.go +++ b/wire.go @@ -119,7 +119,7 @@ func (srv *Server) Serve(listener net.Listener) error { ctx := context.Background() err = srv.serve(ctx, conn) if err != nil { - srv.logger.Error("an unexpected error got returned while serving a client connectio", "err", err) + srv.logger.Error("an unexpected error got returned while serving a client connection", "err", err) } }() } diff --git a/writer.go b/writer.go index 7d35897..870234e 100644 --- a/writer.go +++ b/writer.go @@ -21,20 +21,24 @@ type DataWriter interface { // Written returns the number of rows written to the client. Written() uint64 - // Empty announces to the client a empty response and that no data rows should + // Empty announces to the client an empty response and that no data rows should // be expected. Empty() error // Complete announces to the client that the command has been completed and // no further data should be expected. + // + // See [CommandComplete] for the expected format for different queries. + // + // [CommandComplete]: https://www.postgresql.org/docs/current/protocol-message-formats.html#PROTOCOL-MESSAGE-FORMATS-COMMANDCOMPLETE Complete(description string) error } -// ErrDataWritten is thrown when an empty result is attempted to be send to the +// ErrDataWritten is returned when an empty result is attempted to be sent to the // client while data has already been written. var ErrDataWritten = errors.New("data has already been written") -// ErrClosedWriter is thrown when the data writer has been closed +// ErrClosedWriter is returned when the data writer has been closed. var ErrClosedWriter = errors.New("closed writer") // NewDataWriter constructs a new data writer using the given context and