misfin_client

Documentation

Index

• Constants
• Variables
• func CleanStatus(status int) int
• func GetPunycodeURL(u string) (string, error)
• func IsStatusValid(status int) bool
• func SimplifyStatus(status int) int
• func StatusInRange(status int) bool
• func StatusText(code int) string
• type Client
  • func (c *Client) SendWithCert(rawURL string, certPEM, keyPEM []byte, message string) (*Response, error)
  • func (c *Client) SendWithHostAndCert(host, rawURL string, certPEM, keyPEM []byte, message string) (*Response, error)
• type Error
  • func (e Error) Error() string
  • func (e Error) Unwrap() error
• type ProxyFunc
• type Response
  • func SendWithCert(url string, certPEM, keyPEM []byte, message string) (*Response, error)
  • func SendWithCert_MisfinB(url string, certPEM, keyPEM []byte, message string) (*Response, error)
  • func SendWithHostAndCert(host, url string, certPEM, keyPEM []byte, message string) (*Response, error)
  • func SendWithHostAndCert_MisfinB(host, url string, certPEM, keyPEM []byte, message string) (*Response, error)
  • func (r *Response) SetReadTimeout(d time.Duration) error

Constants

const (
	// Reserved, must not be send by a Misfin server
	StatusInput = 10

	// Message has been delivered
	StatusSuccess = 20

	StatusRedirect          = 30
	StatusRedirectTemporary = 30
	StatusRedirectPermanent = 31

	StatusTemporaryFailure = 40
	StatusUnavailable      = 41
	StatusCGIError         = 42
	StatusProxyError       = 43
	StatusSlowDown         = 44
	StatusMailboxFull      = 45

	StatusPermanentFailure = 50
	// Mailbox does not exist. Mailserver won't accept your message.
	StatusNotFound = 51
	// Mailbox once existed, but doesn't anymore.
	StatusGone = 52
	// The mailserver doesn't serve mail for the hostname you provided.
	StatusDomainNotServiced   = 53
	StatusProxyRequestRefused = 53
	StatusBadRequest          = 59

	// Mailserver doesn't accept anonymous mail.
	StatusClientCertificateRequired = 60
	// Certificate was validated, but you are now allowed to send mail to that mailbox.
	StatusCertificateNotAuthorised = 61
	StatusCertificateNotValid      = 62
	// "YOU'RE A LIAR" - Certificate matches an identity the mailserver recognizes, but the fingerprint has changed, so it is rejecting your message.
	StatusCertificateChanged = 63
	// The mailserver needs you to complete a task to confirm that you are a legitimate sender. Not usually used.
	StatusCertificateProveIt = 64
)

Gemini status codes as defined in the Gemini spec Appendix 1.

Variables

var DefaultClient = &Client{ConnectTimeout: 15 * time.Second, MisfinB: false}

var DefaultClient_MisfinB = &Client{ConnectTimeout: 15 * time.Second, MisfinB: true}

var MetaMaxLength int = URLMaxLength - 3

var URLMaxLength int = 2048

Functions

func CleanStatus

func CleanStatus(status int) int

CleanStatus returns the status code as is, unless it's invalid but still in range Then it returns the status code with the second digit zeroed. So 51 returns 51, but 22 returns 20.

This corresponds with the spec:

A client SHOULD deal with undefined status codes
between '10' and '69' per the default action of the initial digit.

func GetPunycodeURL

func GetPunycodeURL(u string) (string, error)

GetPunycodeURL takes a full URL that potentially has Unicode in the domain name, and returns a URL with the domain punycoded.

func IsStatusValid

func IsStatusValid(status int) bool

IsStatusValid checks whether an int status is covered by the spec. Note that:

A client SHOULD deal with undefined status codes
between '10' and '69' per the default action of the initial digit.

func SimplifyStatus

func SimplifyStatus(status int) int

SimplifyStatus simplify the response status by ommiting the detailed second digit of the status code.

func StatusInRange

func StatusInRange(status int) bool

StatusInRange returns true if the status has a valid first digit. This means it can be handled even if it's not defined by the spec, because it has a known category

func StatusText

func StatusText(code int) string

StatusText returns a text for the Gemini status code. It returns the empty string if the code is unknown.

Types

type Client

type Client struct {
	// NoTimeCheck allows connections with expired or future certs if set to true.
	NoTimeCheck bool

	// NoHostnameCheck allows connections when the cert doesn't match the
	// requested hostname or IP.
	NoHostnameCheck bool

	// Insecure disables all TLS-based checks, use with caution.
	// It overrides all the variables above.
	Insecure bool

	// AllowOutOfRangeStatuses means the client won't raise an error if a status
	// that is out of range is returned.
	// Use CleanStatus() to handle statuses that are in range but not specified in
	// the spec.
	AllowOutOfRangeStatuses bool

	// ConnectTimeout is equivalent to the Timeout field in net.Dialer.
	// It's the max amount of time allowed for the initial connection/handshake.
	// The timeout of the DefaultClient is 15 seconds.
	//
	// If ReadTimeout is not set, then this value is also used to time out on getting
	// the header after the connection is made.
	ConnectTimeout time.Duration

	// ReadTimeout is the max amount of time reading to a server can take.
	// This should not be set if you want to support streams.
	// It is equivalent to net.Conn.SetDeadline, see that func for more documentation.
	//
	// For example, if this is set to 30 seconds, then no more reading from the connection
	// can happen 30 seconds after the initial handshake.
	ReadTimeout time.Duration

	// Turn on to use Misfin(B) format.
	MisfinB bool

	// Proxy is a function that returns an existing connection. The TLS client
	// will use this as the underlying transport, instead of making a direct TCP
	// connection.
	//
	// go-gemini requires setting a dialer on the underlying connection, to impose
	// a timeout on making the initial connection. This dialer is provided as an
	// argument to the proxy function.
	//
	// The other argument provided is the address being connected to. For example
	// "example.com:1958".
	//
	// Any errors returned will prevent a connection from occurring.
	//
	// This is not "gemini proxying", aka the proxying functionality built in to
	// the Gemini protocol. This is for proxying requests over TOR, or SOCKS5, etc.
	//
	//     func(dialer *net.Dialer, address string) (net.Conn, error)
	//
	Proxy ProxyFunc
}

func (*Client) SendWithCert

func (c *Client) SendWithCert(rawURL string, certPEM, keyPEM []byte, message string) (*Response, error)

SendWithCert sends a message to a misfin server with the given URL. It takes the bytes of a PEM encoded block for a client certificate and its key.

It assumes port 1958 if no port is specified.

func (*Client) SendWithHostAndCert

func (c *Client) SendWithHostAndCert(host, rawURL string, certPEM, keyPEM []byte, message string) (*Response, error)

Sends a message to a misfin server at the given host, with the given URL. This can be used for misfin proxying, where the URL host and actual server don't match. It assumes the host is using port 1958 if no port number is provided.

type Error

type Error struct {
	Err    error
	Status int
}

func (Error) Error

func (e Error) Error() string

func (Error) Unwrap

func (e Error) Unwrap() error

type ProxyFunc

type ProxyFunc func(dialer *net.Dialer, address string) (net.Conn, error)

ProxyFunc. See Client documentation

type Response

type Response struct {
	Status int
	Meta   string
	Cert   *x509.Certificate
	// contains filtered or unexported fields
}

Response represents the response from a Gemini server.

func SendWithCert

func SendWithCert(url string, certPEM, keyPEM []byte, message string) (*Response, error)

SendWithCert sends a message to a misfin server with the given URL. It takes the bytes of a PEM encoded block for a client certificate and its key.

It assumes port 1958 if no port is specified.

func SendWithCert_MisfinB

func SendWithCert_MisfinB(url string, certPEM, keyPEM []byte, message string) (*Response, error)

SendWithCert sends a message to a misfin server, using the old Misfin(B) protocol, with the given URL. It takes the bytes of a PEM encoded block for a client certificate and its key.

It assumes port 1958 if no port is specified.

func SendWithHostAndCert

func SendWithHostAndCert(host, url string, certPEM, keyPEM []byte, message string) (*Response, error)

Sends a message to a misfin server at the given host, with the given URL. This can be used for misfin proxying, where the URL host and actual server don't match. It assumes the host is using port 1958 if no port number is provided.

func SendWithHostAndCert_MisfinB

func SendWithHostAndCert_MisfinB(host, url string, certPEM, keyPEM []byte, message string) (*Response, error)

Sends a message to a misfin server, using the old Misfin(B) protocol, at the given host, with the given URL. This can be used for misfin proxying, where the URL host and actual server don't match. It assumes the host is using port 1958 if no port number is provided.

func (*Response) SetReadTimeout

func (r *Response) SetReadTimeout(d time.Duration) error

SetReadTimeout changes the read timeout after the connection has been made. You can set it to 0 or less to disable the timeout. Otherwise, the duration is relative to the time the function was called.