README
¶
TCP-FS: An Easy way for Go Programs to Share an FS on a Network
This library provides a basic client and server interface for sharing an
io/fs.FS instance over TCP connections. It may be useful if the following
applies to you:
-
You have a Go program with access to a filesystem using the
io/fs.FSinterface. -
You have a second Go program that would like to access the same
FS, but is on a different machine. -
The two machines can reach each other over the network.
Basically, this library implements the io/fs.FS interface over a TCP
connection. The server can serve any appropriate filesystem (including its own
tcp_fs client instances), and the client can provide the served filesystem to
any Go library requiring a FS.
The server supports parallel connections to any number of clients.
NOTE ABOUT SECURITY
This project currently offers practically no security! It was written for fun, and used only to share data between private systems on an internal network.
Usage
To run the server:
import (
"fmt"
"github.com/yalue/tcp_fs"
"net"
"os"
)
func main() {
// Serve files from a "./content" directory. (This can be replaced by
// anything implementing io/fs.FS.)
fs := os.DirFS("./content")
// Serve on port 8000
settings := &tcp_fs.ServerSettings {
FS: fs,
Address: &net.TCPAddr{
Port: 8000,
},
}
server, err := tcp_fs.NewServer(settings)
if err != nil {
fmt.Printf("Error starting the server: %s\n", err)
return
}
// Run until an error occurs, or until some routine calls server.Shutdown()
err = server.Serve()
if err != nil {
fmt.Printf("The server exited with an error: %s\n", err)
}
}
To run the client:
import (
"fmt"
"github.com/yalue/tcp_fs"
)
func main() {
// Connect to the server, running on port 8000. Replace myhost.example.com
// with the server's actual address.
settings := &tcp_fs.ClientSettings {
Address: "myhost.example.com:8000",
}
fs, err := tcp_fs.ConnectToServer(settings)
if err != nil {
fmt.Printf("Error connecting to server: %s\n", err)
return
}
// Now, fs can be used anywhere an io/fs.FS is needed, and provides the
// same content as the "./content" directory on the server.
}
Documentation
¶
Overview ¶
The tcp_fs package provides a simple library for serving an arbitrary io/fs.FS interface over a TCP connection.
Usage:
// ON THE SERVER:
// This fs can be anything that supports the fs.FS interface, including
// other instances of tcp_fs.TcpFS.
fs := os.DirFS("./content")
settings := &tcp_fs.ServerSettings {
FS: fs,
Address: &net.TCPAddr{
// ...
},
// ...
}
server, _ := tcp_fs.NewServer(settings)
server.Serve()
// ON THE CLIENT:
settings := &tcp_fs.ClientSettings {
Address: "server.whatever.com:<port>",
// ...
}
fs, _ := tcp_fs.ConnectToServer(settings)
// Now, fs can be used anywhere an io/fs.FS is needed, and provides the
// same content as the fs on the server.
Index ¶
- type ClientSettings
- type ServerSettings
- type TCPFSClient
- type TCPFSFile
- func (f *TCPFSFile) Close() error
- func (f *TCPFSFile) Info() (fs.FileInfo, error)
- func (f *TCPFSFile) IsDir() bool
- func (f *TCPFSFile) ModTime() time.Time
- func (f *TCPFSFile) Mode() fs.FileMode
- func (f *TCPFSFile) Name() string
- func (f *TCPFSFile) Read(dst []byte) (int, error)
- func (f *TCPFSFile) ReadDir(n int) ([]fs.DirEntry, error)
- func (f *TCPFSFile) Size() int64
- func (f *TCPFSFile) Stat() (fs.FileInfo, error)
- func (f *TCPFSFile) Sys() interface{}
- func (f *TCPFSFile) Type() fs.FileMode
- type TCPFSServer
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ClientSettings ¶
type ClientSettings struct {
// The server's address, including its port. Follows the same format as the
// address string passed to net.Dial(...).
Address string
}
Required settings when establishing a connection to a server.
type ServerSettings ¶
type ServerSettings struct {
// The actual FS to serve.
FS fs.FS
// The address on which to serve. Follows the same rules as net.ListenTCP.
Address *net.TCPAddr
// A logger to which the server will write messages about ongoing activity.
// If nil, then no log info will be written.
Logger *log.Logger
}
Contains the settings used when setting up a tcp_fs server.
type TCPFSClient ¶
type TCPFSClient struct {
// contains filtered or unexported fields
}
Holds the state for a tcp_fs client instance. Implements the io/fs.FS interface.
func ConnectToServer ¶
func ConnectToServer(settings *ClientSettings) (*TCPFSClient, error)
Connects to the server specified in the settings. The returned client satisfies the FS interface. The caller should call the Close() function to end the connection when the FS is no longer needed.
func (*TCPFSClient) Close ¶
func (c *TCPFSClient) Close()
Closes the connection. It is an error to use the client after calling this.
type TCPFSFile ¶
type TCPFSFile struct {
// contains filtered or unexported fields
}
Holds the state for a single file from a tcp_fs client. Implements the fs.File, fs.DirEntry, fs.FileInfo, and fs.ReadDirFile interfaces.
type TCPFSServer ¶
type TCPFSServer struct {
// contains filtered or unexported fields
}
Holds the state of an instance of a tcp_fs server.
func NewServer ¶
func NewServer(settings *ServerSettings) (*TCPFSServer, error)
Creates a new TCPFSServer instance, but doesn't start running it yet.
func (*TCPFSServer) Serve ¶
func (s *TCPFSServer) Serve() error
Starts running the TCP server. Will not return unless an error occurs or s.Shutdown() is called. It is an error to call Serve() more than once on the same TCPFSServer instance.
func (*TCPFSServer) Shutdown ¶
func (s *TCPFSServer) Shutdown() error
Stops the TCPFSServer, and signals any client connections to end when possible.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
This defines a simple executable for serving content over HTTP from a remote tcp_fs instance.
|
This defines a simple executable for serving content over HTTP from a remote tcp_fs instance. |
|
This defines a simple executable for serving a directory using the tcp_fs library.
|
This defines a simple executable for serving a directory using the tcp_fs library. |