server

Documentation

Index

• Constants
• func FindLatestBasedirsDB(dir, suffix string) (string, error)
• func FindLatestDgutDirs(dir, suffix string) ([]string, error)
• func GetGroupAreas(c *gas.ClientCLI) (map[string][]string, error)
• type DirSummary
  • func GetWhereDataIs(c *gas.ClientCLI, dir, groups, users, types, splits string) ([]byte, []*DirSummary, error)
• type Server
  • func New(logWriter io.Writer) *Server
  • func (s *Server) AddGroupAreas(areas map[string][]string)
  • func (s *Server) AddTreePage() error
  • func (s *Server) EnableBasedirDBReloading(watchPath, dir, suffix string, pollFrequency time.Duration) error
  • func (s *Server) EnableDGUTDBReloading(watchPath, dir, suffix string, pollFrequency time.Duration) error
  • func (s *Server) LoadBasedirsDB(dbPath, ownersPath string) error
  • func (s *Server) LoadDGUTDBs(paths ...string) error
  • func (s *Server) WhiteListGroups(wcb WhiteListCallback)
• type TreeElement
• type WhiteListCallback

Constants

const (

	// EndPointWhere is the endpoint for making where queries if authorization
	// isn't implemented.
	EndPointWhere = gas.EndPointREST + wherePath

	// EndPointAuthWhere is the endpoint for making where queries if
	// authorization is implemented.
	EndPointAuthWhere = gas.EndPointAuth + wherePath

	// EndPointAuthGroupAreas is the endpoint for making queries on what the
	// group areas are, which is available if authorization is implemented.
	EndPointAuthGroupAreas = gas.EndPointAuth + groupAreasPaths

	// EndPointBasedir* are the endpoints for making base directory related
	// queries if authorization isn't implemented.
	EndPointBasedirUsageGroup  = gas.EndPointREST + basedirsGroupUsagePath
	EndPointBasedirUsageUser   = gas.EndPointREST + basedirsUserUsagePath
	EndPointBasedirSubdirGroup = gas.EndPointREST + basedirsGroupSubdirPath
	EndPointBasedirSubdirUser  = gas.EndPointREST + basedirsUserSubdirPath
	EndPointBasedirHistory     = gas.EndPointREST + basedirsHistoryPath

	// EndPointAuthBasedir* are the endpoints for making base directory related
	// queries if authorization is implemented.
	EndPointAuthBasedirUsageGroup  = gas.EndPointAuth + basedirsGroupUsagePath
	EndPointAuthBasedirUsageUser   = gas.EndPointAuth + basedirsUserUsagePath
	EndPointAuthBasedirSubdirGroup = gas.EndPointAuth + basedirsGroupSubdirPath
	EndPointAuthBasedirSubdirUser  = gas.EndPointAuth + basedirsUserSubdirPath
	EndPointAuthBasedirHistory     = gas.EndPointAuth + basedirsHistoryPath

	// TreePath is the path to the static tree website.
	TreePath = "/tree"

	// EndPointAuthTree is the endpoint for making treemap queries when
	// authorization is implemented.
	EndPointAuthTree = gas.EndPointAuth + TreePath
)

const ErrBadBasedirsQuery = gas.Error("bad query; check id and basedir")

const ErrBadQuery = gas.Error("bad query; check dir, group, user and type")

Functions

func FindLatestBasedirsDB

func FindLatestBasedirsDB(dir, suffix string) (string, error)

FindLatestBasedirsDB finds the latest file in dir that has the given suffix.

func FindLatestDgutDirs

func FindLatestDgutDirs(dir, suffix string) ([]string, error)

FindLatestDgutDirs finds the latest subdirectory of dir that has the given suffix, then returns that result's child directories.

func GetGroupAreas

func GetGroupAreas(c *gas.ClientCLI) (map[string][]string, error)

GetGroupAreas is a client call to a Server that queries its configured group area information. The returned map has area keys and group slices.

Types

type DirSummary

type DirSummary struct {
	Dir       string
	Count     uint64
	Size      uint64
	Atime     time.Time
	Mtime     time.Time
	Users     []string
	Groups    []string
	FileTypes []string
}

DirSummary holds nested file count, size and atime information on a directory. It also holds which users and groups own files nested under the directory, and their file types. It differs from dgut.DirSummary in having string names for users, groups and types, instead of ids.

func GetWhereDataIs

func GetWhereDataIs(c *gas.ClientCLI, dir, groups, users, types, splits string) ([]byte, []*DirSummary, error)

GetWhereDataIs is a client call to a Server listening at the given domain:port url that queries where data is and returns the raw response body (JSON string), and that body converted in to a slice of *DirSummary.

Provide a non-blank path to a certificate to force us to trust that certificate, eg. if the server was started with a self-signed certificate.

You must first Login() to get a JWT that you must supply here.

The other parameters correspond to arguments that dgut.Tree.Where() takes.

type Server

type Server struct {
	gas.Server
	// contains filtered or unexported fields
}

Server is used to start a web server that provides a REST API to the dgut package's database, and a website that displays the information nicely.

func New

func New(logWriter io.Writer) *Server

New creates a Server which can serve a REST API and website.

It logs to the given io.Writer, which could for example be syslog using the log/syslog pkg with syslog.new(syslog.LOG_INFO, "tag").

func (*Server) AddGroupAreas

func (s *Server) AddGroupAreas(areas map[string][]string)

AddGroupAreas takes a map of area keys and group slice values. Clients will then receive this map on TreeElements in the "areas" field.

If EnableAuth() has been called, also creates the /auth/group-areas endpoint that returns the given value.

func (*Server) AddTreePage

func (s *Server) AddTreePage() error

AddTreePage adds the /tree static web page to the server, along with the /rest/v1/auth/tree endpoint. It only works if EnableAuth() has been called first.

func (*Server) EnableBasedirDBReloading

func (s *Server) EnableBasedirDBReloading(watchPath, dir, suffix string, pollFrequency time.Duration) error

EnableBasedirDBReloading will wait for changes to the file at watchPath, then:

1. close any previously loaded basedirs database file
2. find the latest file in the given directory with the given suffix
3. set the basedirs.db directory path to that and load it
4. delete the old basedirs.db file

It will only return an error if trying to watch watchPath immediately fails. Other errors (eg. reloading or deleting files) will be logged.

func (*Server) EnableDGUTDBReloading

func (s *Server) EnableDGUTDBReloading(watchPath, dir, suffix string, pollFrequency time.Duration) error

EnableDGUTDBReloading will wait for changes to the file at watchPath, then:

1. close any previously loaded dgut database files
2. find the latest sub-directory in the given directory with the given suffix
3. set the dgut.db directory paths to children of 2) and load those
4. delete the old dgut.db directory paths to save space, and their parent dir if now empty
5. update the server's data-creation date to the mtime of the watchPath file

It will also do 5) immediately on calling this method.

It will only return an error if trying to watch watchPath immediately fails. Other errors (eg. reloading or deleting files) will be logged.

func (*Server) LoadBasedirsDB

func (s *Server) LoadBasedirsDB(dbPath, ownersPath string) error

LoadBasedirsDB loads the given basedirs.db file (as produced by basedirs.CreateDatabase()) and makes use of the given owners file (a gid,owner csv) and adds the following GET endpoints to the REST API:

/rest/v1/basedirs/usage/groups /rest/v1/basedirs/usage/users /rest/v1/basedirs/subdirs/group /rest/v1/basedirs/subdirs/user /rest/v1/basedirs/history

If you call EnableAuth() first, then these endpoints will be secured and be available at /rest/v1/auth/basedirs/*.

The subdir endpoints require id (gid or uid) and basedir parameters. The history endpoint requires a gid and basedir (can be basedir, actually a mountpoint) parameter.

func (*Server) LoadDGUTDBs

func (s *Server) LoadDGUTDBs(paths ...string) error

LoadDGUTDBs loads the given dgut.db directories (as produced by one or more invocations of dgut.DB.Store()) and adds the /rest/v1/where GET endpoint to the REST API. If you call EnableAuth() first, then this endpoint will be secured and be available at /rest/v1/auth/where.

The where endpoint can take the dir, splits, groups, users and types parameters, which correspond to arguments that dgut.Tree.Where() takes.

func (*Server) WhiteListGroups

func (s *Server) WhiteListGroups(wcb WhiteListCallback)

WhiteListGroups sets the given callback on the server, which will now be used to check if any of the groups that a user belongs to have been whitelisted, giving that user unrestricted access to know about all groups.

Do NOT call this more than once or after the server has started responding to client queries.

type TreeElement

type TreeElement struct {
	Name        string              `json:"name"`
	Path        string              `json:"path"`
	Count       uint64              `json:"count"`
	Size        uint64              `json:"size"`
	Atime       string              `json:"atime"`
	Mtime       string              `json:"mtime"`
	Users       []string            `json:"users"`
	Groups      []string            `json:"groups"`
	FileTypes   []string            `json:"filetypes"`
	HasChildren bool                `json:"has_children"`
	Children    []*TreeElement      `json:"children,omitempty"`
	TimeStamp   string              `json:"timestamp"`
	Areas       map[string][]string `json:"areas"`
	NoAuth      bool                `json:"noauth"`
}

TreeElement holds tree.DirInfo type information in a form suited to passing to the treemap web interface. It also includes the server's dataTimeStamp so interfaces can report on how long ago the data forming the tree was captured.

type WhiteListCallback

type WhiteListCallback func(gid string) bool

WhiteListCallback is passed to WhiteListGroups() and is used by the server to determine if a given unix group ID is special, indicating that users belonging to it have permission to view information about all other unix groups. If it's a special group, return true; otherwise false.