diff options
| -rw-r--r-- | client.go | 14 | ||||
| -rw-r--r-- | fs.go | 6 | ||||
| -rw-r--r-- | query.go | 3 | ||||
| -rw-r--r-- | request.go | 7 | ||||
| -rw-r--r-- | response.go | 4 | ||||
| -rw-r--r-- | server.go | 4 |
6 files changed, 17 insertions, 21 deletions
@@ -15,10 +15,10 @@ import ( // A Client is a Gemini client. Its zero value is a usable client. type Client struct { - // TrustCertificate is called to determine whether the client - // should trust the certificate provided by the server. - // If TrustCertificate is nil, the client will accept any certificate. - // If the returned error is not nil, the certificate will not be trusted + // TrustCertificate is called to determine whether the client should + // trust the certificate provided by the server. + // If TrustCertificate is nil or returns nil, the client will accept + // any certificate. Otherwise, the certificate will not be trusted // and the request will be aborted. // // See the tofu submodule for an implementation of trust on first use. @@ -36,8 +36,7 @@ type Client struct { // An error is returned if there was a Gemini protocol error. // A non-2x status code doesn't cause an error. // -// If the returned error is nil, the Response will contain a non-nil Body -// which the user is expected to close. +// If the returned error is nil, the user is expected to close the Response. // // For more control over requests, use NewRequest and Client.Do. func (c *Client) Get(ctx context.Context, url string) (*Response, error) { @@ -55,8 +54,7 @@ func (c *Client) Get(ctx context.Context, url string) (*Response, error) { // An error is returned if there was a Gemini protocol error. // A non-2x status code doesn't cause an error. // -// If the returned error is nil, the Response will contain a non-nil Body -// which the user is expected to close. +// If the returned error is nil, the user is expected to close the Response. // // Generally Get will be used instead of Do. func (c *Client) Do(ctx context.Context, req *Request) (*Response, error) { @@ -65,8 +65,8 @@ func serveContent(w ResponseWriter, name string, content io.Reader) { // // As a precaution, ServeFile will reject requests where r.URL.Path contains a // ".." path element; this protects against callers who might unsafely use -// filepath.Join on r.URL.Path without sanitizing it and then use that -// filepath.Join result as the name argument. +// path.Join on r.URL.Path without sanitizing it and then use that +// path.Join result as the name argument. // // As another special case, ServeFile redirects any request where r.URL.Path // ends in "/index.gmi" to the same path, without the final "index.gmi". To @@ -81,7 +81,7 @@ func ServeFile(w ResponseWriter, r *Request, fsys fs.FS, name string) { // serveFile. Reject the request under the assumption that happened // here and ".." may not be wanted. // Note that name might not contain "..", for example if code (still - // incorrectly) used filepath.Join(myDir, r.URL.Path). + // incorrectly) used path.Join(myDir, r.URL.Path). w.WriteHeader(StatusBadRequest, "invalid URL path") return } @@ -12,7 +12,8 @@ func QueryEscape(query string) string { return strings.ReplaceAll(url.PathEscape(query), "+", "%2B") } -// QueryUnescape is identical to url.PathUnescape. +// QueryUnescape unescapes a Gemini URL query. +// It is identical to url.PathUnescape. func QueryUnescape(query string) (string, error) { return url.PathUnescape(query) } @@ -10,11 +10,8 @@ import ( // A Request represents a Gemini request received by a server or to be sent // by a client. -// -// The field semantics differ slightly between client and server usage. type Request struct { - // URL specifies the URL being requested (for server - // requests) or the URL to access (for client requests). + // URL specifies the URL being requested. URL *url.URL // For client requests, Host optionally specifies the server to @@ -23,6 +20,7 @@ type Request struct { // For international domain names, Host may be in Punycode or // Unicode form. Use golang.org/x/net/idna to convert it to // either format if needed. + // This field is ignored by the Gemini server. Host string // For client requests, Certificate optionally specifies the @@ -34,7 +32,6 @@ type Request struct { } // NewRequest returns a new request. -// // The returned Request is suitable for use with Client.Do. // // Callers should be careful that the URL query is properly escaped. diff --git a/response.go b/response.go index d113a1b..d169e17 100644 --- a/response.go +++ b/response.go @@ -202,7 +202,7 @@ type responseWriter struct { bodyAllowed bool } -// NewResponseWriter returns a ResponseWriter that uses the provided io.Writer. +// NewResponseWriter returns a ResponseWriter that uses the provided io.WriteCloser. func NewResponseWriter(wc io.WriteCloser) ResponseWriter { return newResponseWriter(wc) } @@ -253,7 +253,7 @@ func (w *responseWriter) Flush() error { if !w.wroteHeader { w.WriteHeader(StatusTemporaryFailure, "Temporary failure") } - // Write errors from writeHeader will be returned here. + // Write errors from WriteHeader will be returned here. return w.b.Flush() } @@ -229,8 +229,8 @@ func (srv *Server) deleteListener(l *net.Listener) { } // Serve accepts incoming connections on the Listener l, creating a new -// service goroutine for each. The service goroutines reads the request and -// then calls the appropriate Handler to reply to them. If the provided +// service goroutine for each. The service goroutines read the requests and +// then call the appropriate Handler to reply to them. If the provided // context expires, Serve closes l and returns the context's error. // // Serve always closes l and returns a non-nil error. |