Documentation ¶
Overview ¶
Package uds provides a server and client for Unix Domain Sockets. This provides a lot of convenience around the "net" package for handling all the file setup and detecting closed connections. It also provides the ability to authenticate connections.
The package currently only works for Linux/Darwin, as those are the systems I use.
This package takes the stance that Read() and Write() calls by default should infinitely block unless the socket is closed. This eases development.
We also handle write only connections where Write() calls may not detect a closed connection. This can be done setting the WriteOnly option.
This package is fairly straight forward in that you can uses server.Conn objects and Client objects as io.ReadWriteClose objects. We also provide higher level clients that handle chunk data, a chunk data RPC client/server, json streams, json RPC client/server, ..
Unix/Linux Note:
Socket paths may have a length limit that is different than the normal filesystem. On OSX, you can receive "bind: invalid argument" when the name is too long. On Linux there seems to be an 108 character limit for socket path names. On OSX it is 104 character limit. https://github.com/golang/go/issues/6895 . I have set this as the default limit for all clients so I don't have to figure out the limit on every type of system and interpret non-sensical errors.
Index ¶
- type Client
- func (c *Client) Close() error
- func (c *Client) Read(b []byte) (int, error)
- func (c *Client) ReadByte() (byte, error)
- func (c *Client) ReadDeadline(t time.Time)
- func (c *Client) ReadTimeout(timeout time.Duration)
- func (c *Client) UnixConn() *net.UnixConn
- func (c *Client) Write(b []byte) (int, error)
- func (c *Client) WriteDeadline(t time.Time)
- func (c *Client) WriteOnly()
- func (c *Client) WriteTimeout(timeout time.Duration)
- type Conn
- func (c *Conn) Close() error
- func (c *Conn) Read(b []byte) (int, error)
- func (c *Conn) ReadByte() (byte, error)
- func (c *Conn) ReadDeadline(t time.Time)
- func (c *Conn) ReadTimeout(timeout time.Duration)
- func (c *Conn) UnixConn() *net.UnixConn
- func (c *Conn) Write(b []byte) (int, error)
- func (c *Conn) WriteDeadline(t time.Time)
- func (c *Conn) WriteOnly()
- func (c *Conn) WriteTimeout(timeout time.Duration)
- type Cred
- type ID
- type Server
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client provides a UDS client for connecting to a UDS server.
func NewClient ¶
NewClient creates a new UDS client to the socket at socketAddr that must have the uid and gid specified. fileModes provides a list of acceptable file modes that the socket can be in (suggest 0770, 1770). If not specified, 0770 and 1770 are used.
func (*Client) Read ¶
Read implements io.Reader.Read(). This will block until it has read into the buffer. This differs from native behavior which times out. If you want to have read timeouts, use ReadDeadline()/ReadTimeout() to change. This must be done before every Read() call.
func (*Client) ReadDeadline ¶
ReadDeadline caused the next Read() call to timeout at t. Must be used before every Read() call that you want to have a timeout.
func (*Client) ReadTimeout ¶
ReadTimeout caused the next Read() call to timeout at time.Now().Add(timeout). Must be used before every Read() call that you want to have a timeout.
func (*Client) UnixConn ¶
UnixConn will return the underlying UnixConn object. You can use this to use its underlying methods or change buffering. Note that SetReadDeadline/SetWriteDeadline/SetDeadline do not work, use one of Client's methods instead.
func (*Client) Write ¶
Write implements io.Reader.Writer(). This will block until it has written the buffer. This differs from native behavior which times out. If you want to have write timeouts, use WriteDeadeline()/WriteTimeout() to change. This must be done before every Write() call.
func (*Client) WriteDeadline ¶
WriteDeadline caused the next Write() call to timeout at t. Must be used before every Write() call that you want to have a timeout.
func (*Client) WriteOnly ¶
func (c *Client) WriteOnly()
WriteOnly let's the Client know that it will only be used for writing. This will cause a *special* read to happen on all writes to make sure the connection isn't closed, as writes are not guaranteed to error on a UDS. If doing reads, this isn't required. If this is set and you read fro the Conn the read will panic.
func (*Client) WriteTimeout ¶
WriteTimeout caused the next Write() call to timeout at time.Now().Add(timeout). Must be used before every Write() call that you want to have a timeout.
type Conn ¶
type Conn struct { Cred Cred // contains filtered or unexported fields }
Conn represents a UDS connection from a client. Must take a pointer if this will be copied after being received.
func (*Conn) Read ¶
Read implements io.Reader.Read(). This has an inifite read timeout. If you want to have a timeout, call ReadDeadline() or ReadTimeout() before calling. You must do this for every Read() call.
func (*Conn) ReadDeadline ¶
ReadDeadline caused the next Read() call to timeout at t. Must be used before every Read() call that you want to have a timeout.
func (*Conn) ReadTimeout ¶
ReadTimeout caused the next Read() call to timeout at time.Now().Add(timeout). Must be used before every Read() call that you want to have a timeout.
func (*Conn) UnixConn ¶
UnixConn will return the underlying UnixConn object. You can use this to use its underlying methods or change buffering. Note that .SetReadDeadline()/.SetWriteDeadline()/.SetDeadline() will not do anything. Use ReadTimeout()/ReadDeadline()/WriteTimeout()/WriteDeadline() defined on Conn.
func (*Conn) Write ¶
Write implements io.Writer.Write(). This has an inifite write timeout. If you want to have a timeout, call WriteDeadline() or WriteTimeout() before calling. You must do this for every Write() call.
func (*Conn) WriteDeadline ¶
WriteDeadline caused the next Write() call to timeout at t. Must be used before every Write() call that you want to have a timeout.
func (*Conn) WriteOnly ¶
func (c *Conn) WriteOnly()
WriteOnly let's the Conn know that this Conn will only be used for writing. This will cause a *special* read to happen on all writes to make sure the connection isn't closed, as writes are not guaranteed to error on a UDS. If doing reads, this isn't required. If this is set and you read from the Conn, Read() will panic.
func (*Conn) WriteTimeout ¶
WriteTimeout caused the next Write() call to timeout at time.Now().Add(timeout). Must be used before every Write() call that you want to have a timeout.
type Cred ¶
type Cred struct { // PID is the process id of the process. PID ID // UID is the user id of the process. UID ID // GID is the group id of the process. GID ID }
Cred provides the credentials of the local process contacting the server.
type ID ¶
type ID int
ID represents a numeric ID. Go in various libraries stores IDs such as Uid or Gid as strings. However in other more OS specific libraries, it might be int or int32. This simply unifies that so it is easier to translate for whatever need you have. The string representation is probably a compatibility feature to allow an OS that doesn't use numeric IDs to work. However I am not interested in supporting those in this package.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server provides a Unix Domain Socket server that clients can connect on.
func NewServer ¶
NewServer creates a new UDS server that creates and listens to the file at socketPath. uid and gid are the uid and gid that file will be set to and fileMode is the file mode it will inherit. If sockerAddr exists this will attempt to delete it. Suggest fileMode of 0770.
func (*Server) Closed ¶
Closed returns a channel that returns an error when the connection to the server is closed. This can be because you have called Close(), the socket had a read error or the socket file was removed. An io.EOF error will not be returned (as this is normal operation). Normally this is used to block and return the final status of the server.
Directories ¶
Path | Synopsis |
---|---|
example
|
|
highlevel
|
|
chunk
Package chunk provides a high level chunking client.
|
Package chunk provides a high level chunking client. |
chunk/rpc
Package rpc provides an RPC service for non-specific []byte in and []byte out data.
|
Package rpc provides an RPC service for non-specific []byte in and []byte out data. |
json/rpc
Package rpc provides a json RPC service.
|
Package rpc provides a json RPC service. |
json/stream
Package json provides a client that can be used on a *uds.Client or *uds.Conn to send streaming JSON values.
|
Package json provides a client that can be used on a *uds.Client or *uds.Conn to send streaming JSON values. |
proto/rpc
Package rpc provides a proto RPC service.
|
Package rpc provides a proto RPC service. |
proto/stream
Package stream provides a client that can be used on a *uds.Client or *uds.Conn to send streaming binary proto values.
|
Package stream provides a client that can be used on a *uds.Client or *uds.Conn to send streaming binary proto values. |