admin

README

API

Guidelines

Errors

When an endpoint returns an error must always return the appropriated HTTP status codes with a body, except that the HTTP specification indicates that the HTTP status code must not have a body.

The body is an object following fields:

{
	error: string
}

error field is message which provides a description of the error.

Endpoints that return lists

Some of the endpoints that return a list of items require one of this functionalities. We need to define request parameters and response parameters (for the ones that needs it), so all the endpoints that require these features are consistent across the API.

Pagination

We must offer pagination, but we have to consider the performance penalty of using LIMIT and OFFSET, hence we should try to have model that we can use the keyset pagination.

The endpoint:

• Accepts three optional query parameters: cursor, direction and limit.

  The server sends the list of items starting from the first record when it doesn't receive any cursor.

  The server applies a default limit when it doesn't receive the direction and limit parameters.

  The server responds with HTTP status code 422 if cursor, direction, or limit have invalid values.

  cursor is an opaque value that the server sends (see next bullet). dierection indicates what list of items to retrieve from the cursor, it only accepts two values next and previous. limit is the maximum number of requested items.

• Sends a response body in an object with the following fields:

{
	data: any[],           // This is an array of the the type
				           // corresponding to the endpoint.
    pagination: {
        cursor: string,      // Opaque value.
        total: number,       // Integer.
        previous: boolean,   // Indicates that there is a previous page of results.
        next: boolean,       // Indicates that there is a next page of results.
    }
}

Clients must send cursor when it wants to get the next page of results with the same sort and search parameters used in the previous requests, otherwise the server responds with an HTTP status code 422 because cursor only applies to exactly the same query.

cursor value is opaque for the clients; the server knows how to interpret it to know if the request contains the correct order and search to return results from the designed cursor.

The trade-off of using a ketyset pagination for having less performance impact on querying the database is that the pagination doesn't support to ask for an arbitrary page, only the next or the previous can be requested.

Sorting

We must allow to sort the items by different fields and order (ascendant and descendant).

The endpoints accepts one optional query parameter: sort-by. The server applies a default order when it doesn't receive the sort-by parameter.

sort-by is a comma-separated list of tuples <field-name>:<asc|des>, for example sort-by=surname:asc,age:des. Fields' names cannot contain colons and the order of the fields establish the how to sort the items, in the previous example, the server sorts the items by surname and after by age.

Search

We must allow to search items by different fields. When multiple fields are used a logical AND is used between the values.

The endpoint accepts one optional query parameter: filter. The server doesn't apply any filter if it doesn't receive the filter parameter.

filter is a comma-separated list of tuples <field-name>:<value>, for example filter=company:storj,name:john. Field's names cannot contain colons, the order of the fields is irrelevant because a logical AND is applied for all of them.

Documentation

Overview

See LICENSE for copying information. performing satellite administration tasks.

NOTE this is work in progress and will eventually replace the current satellite administration server implemented in the parent package, hence this package name is the same than its parent because it will simplify the replace once it's ready.

Index

• Constants
• Variables
• type Authorization
  • func (auth Authorization) Has(perms ...Permission) bool
• type Authorizer
  • func NewAuthorizer(log *zap.Logger, ...) *Authorizer
  • func (auth *Authorizer) HasPermissions(group string, perms ...Permission) bool
  • func (auth *Authorizer) IsRejected(w http.ResponseWriter, r *http.Request, perms ...Permission) bool
• type Config
• type Permission
• type PlacementInfo
• type PlacementManagementHandler
  • func NewPlacementManagement(log *zap.Logger, mon *monkit.Scope, service PlacementManagementService, ...) *PlacementManagementHandler
• type PlacementManagementService
• type ProjectUsageLimits
• type Server
  • func NewServer(log *zap.Logger, listener net.Listener, service *Service, root *mux.Router, ...) *Server
  • func (server *Server) Close() error
  • func (server *Server) Run(ctx context.Context) error
• type Service
  • func NewService(log *zap.Logger, consoleDB console.DB, ...) *Service
  • func (s *Service) GetPlacements(ctx context.Context) ([]PlacementInfo, api.HTTPError)
  • func (s *Service) GetUserByEmail(ctx context.Context, email string) (*User, api.HTTPError)
• type User
• type UserManagementHandler
  • func NewUserManagement(log *zap.Logger, mon *monkit.Scope, service UserManagementService, ...) *UserManagementHandler
• type UserManagementService

Constants

const (
	RoleAdmin = Authorization(
		PermAccountView | PermAccountChangeEmail | PermAccountDisableMFA | PermAccountChangeLimits |
			PermAccountSetDataPlacement | PermAccountRemoveDataPlacement | PermAccountSetUserAgent |
			PermAccountSuspendTemporary | PermAccountReActivateTemporary | PermAccountSuspendPermanently |
			PermAccountReActivatePermanently | PermAccountDeleteNoData | PermAccountDeleteWithData |
			PermProjectView | PermProjectSetLimits | PermProjectSetDataPlacement |
			PermProjectRemoveDataPlacement | PermProjectSetUserAgent | PermProjectSendInvitation |
			PermBucketView | PermBucketSetDataPlacement | PermBucketRemoveDataPlacement |
			PermBucketSetUserAgent,
	)
	RoleViewer          = Authorization(PermAccountView | PermProjectView | PermBucketView)
	RoleCustomerSupport = Authorization(
		PermAccountView | PermAccountChangeEmail | PermAccountDisableMFA | PermAccountChangeLimits |
			PermAccountSetDataPlacement | PermAccountRemoveDataPlacement | PermAccountSetUserAgent |
			PermAccountSuspendTemporary | PermAccountReActivateTemporary | PermAccountDeleteNoData |
			PermProjectView | PermProjectSetLimits | PermProjectSetDataPlacement |
			PermProjectRemoveDataPlacement | PermProjectSetUserAgent | PermProjectSendInvitation |
			PermBucketView | PermBucketSetDataPlacement | PermBucketRemoveDataPlacement |
			PermBucketSetUserAgent,
	)
	RoleFinanceManager = Authorization(
		PermAccountView | PermAccountSuspendTemporary | PermAccountReActivateTemporary |
			PermAccountSuspendPermanently | PermAccountReActivatePermanently | PermAccountDeleteNoData |
			PermAccountDeleteWithData | PermProjectView | PermBucketView,
	)
)

These constants are the list of roles that users can have and the service uses to match permissions to perform operations.

const PathPrefix = "/back-office/"

PathPrefix is the path that will be prefixed to the router passed to the NewServer constructor. This is temporary until this server will replace the storj.io/storj/satellite/admin/server.go.

Variables

var ErrAuthorizer = errs.Class("authorizer")

ErrAuthorizer is the error class that wraps all the errors returned by the authorization.

var ErrPlacementsAPI = errs.Class("admin placements api")

var ErrUsersAPI = errs.Class("admin users api")

var (
	// Error is the error class that wraps all the errors returned by this package.
	Error = errs.Class("satellite-admin")
)

Types

type Authorization

type Authorization uint64

Authorization specifies the permissions that user role has and validates if it has certain permissions.

func (Authorization) Has

func (auth Authorization) Has(perms ...Permission) bool

Has returns true if auth has all the passed permissions.

type Authorizer

type Authorizer struct {
	// contains filtered or unexported fields
}

Authorizer checks if a group has certain permissions.

func NewAuthorizer

func NewAuthorizer(
	log *zap.Logger,
	adminGroups, viewerGroups, customerSupportGroups, financeManagerGroups []string,
) *Authorizer

NewAuthorizer creates an Authorizer with the list of groups that are assigned to each different role. log is the parent logger where it will attach a prefix to identify messages coming from it.

In the case that a group is assigned to more than one role, it will get the less permissive role.

func (*Authorizer) HasPermissions

func (auth *Authorizer) HasPermissions(group string, perms ...Permission) bool

HasPermissions check if group has all perms.

func (*Authorizer) IsRejected

func (auth *Authorizer) IsRejected(w http.ResponseWriter, r *http.Request, perms ...Permission) bool

IsRejected verifies that r is from a user who belongs to a group that has all perms and returns false, otherwise responds with http.StatusUnauthorized using storj.io/storj/private.api.ServeError and returns true.

This method is convenient to inject it to the handlers generated by the API generator through a customized handler.

type Config

type Config struct {
	StaticDir string `` /* 181-byte string literal not displayed */

	UserGroupsRoleAdmin           []string `help:"the list of groups whose users has the administration role"   releaseDefault:"" devDefault:""`
	UserGroupsRoleViewer          []string `help:"the list of groups whose users has the viewer role"           releaseDefault:"" devDefault:""`
	UserGroupsRoleCustomerSupport []string `help:"the list of groups whose users has the customer support role" releaseDefault:"" devDefault:""`
	UserGroupsRoleFinanceManager  []string `help:"the list of groups whose users has the finance manager role"  releaseDefault:"" devDefault:""`
}

Config defines configuration for the satellite administration server.

type Permission

type Permission uint64

Permission represents a permissions to perform an operation.

const (
	PermAccountView Permission = 1 << iota
	PermAccountChangeEmail
	PermAccountDisableMFA
	PermAccountChangeLimits
	PermAccountSetDataPlacement
	PermAccountRemoveDataPlacement
	PermAccountSetUserAgent
	PermAccountSuspendTemporary
	PermAccountReActivateTemporary
	PermAccountSuspendPermanently
	PermAccountReActivatePermanently
	PermAccountDeleteNoData
	PermAccountDeleteWithData
	PermProjectView
	PermProjectSetLimits
	PermProjectSetDataPlacement
	PermProjectRemoveDataPlacement
	PermProjectSetUserAgent
	PermProjectSendInvitation
	PermBucketView
	PermBucketSetDataPlacement
	PermBucketRemoveDataPlacement
	PermBucketSetUserAgent
)

These constants are the list of permissions that the service uses for authorizing users to perform operations.

type PlacementInfo

type PlacementInfo struct {
	ID       storj.PlacementConstraint `json:"id"`
	Location string                    `json:"location"`
}

PlacementInfo contains the ID and location of a placement rule.

type PlacementManagementHandler

type PlacementManagementHandler struct {
	// contains filtered or unexported fields
}

PlacementManagementHandler is an api handler that implements all PlacementManagement API endpoints functionality.

func NewPlacementManagement

func NewPlacementManagement(log *zap.Logger, mon *monkit.Scope, service PlacementManagementService, router *mux.Router) *PlacementManagementHandler

type PlacementManagementService

type PlacementManagementService interface {
	GetPlacements(ctx context.Context) ([]PlacementInfo, api.HTTPError)
}

type ProjectUsageLimits

type ProjectUsageLimits struct {
	ID             uuid.UUID `json:"id"` // This is the public ID
	Name           string    `json:"name"`
	StorageLimit   int64     `json:"storageLimit"`
	StorageUsed    *int64    `json:"storageUsed"`
	BandwidthLimit int64     `json:"bandwidthLimit"`
	BandwidthUsed  int64     `json:"bandwidthUsed"`
	SegmentLimit   int64     `json:"segmentLimit"`
	SegmentUsed    *int64    `json:"segmentUsed"`
}

ProjectUsageLimits holds project usage limits and current usage. StorageUsed, BandwidthUsed, and SegmentUsed are nil if there was an error connecting to the Redis live accounting cache.

type Server

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

Server serves the API endpoints and the web application to allow preforming satellite administration tasks.

func NewServer

func NewServer(
	log *zap.Logger,
	listener net.Listener,
	service *Service,
	root *mux.Router,
	config Config,
) *Server

NewServer creates a satellite administration server instance with the provided dependencies and configurations.

When listener is nil, Server.Run is a noop.

func (*Server) Close

func (server *Server) Close() error

Close closes server and underlying listener.

func (*Server) Run

func (server *Server) Run(ctx context.Context) error

Run starts the administration HTTP server using the provided listener. If listener is nil, it does nothing and return nil.

type Service

type Service struct {
	// contains filtered or unexported fields
}

Service provides functionality for administrating satellites.

func NewService

func NewService(
	log *zap.Logger,
	consoleDB console.DB,
	accountingDB accounting.ProjectAccounting,
	accounting *accounting.Service,
	placement nodeselection.PlacementDefinitions,
) *Service

NewService creates a new satellite administration service.

func (*Service) GetPlacements

func (s *Service) GetPlacements(ctx context.Context) ([]PlacementInfo, api.HTTPError)

GetPlacements returns IDs and locations of placement rules.

func (*Service) GetUserByEmail

func (s *Service) GetUserByEmail(ctx context.Context, email string) (*User, api.HTTPError)

GetUserByEmail returns a verified user by its email address.

type User

type User struct {
	ID                 uuid.UUID                 `json:"id"`
	FullName           string                    `json:"fullName"`
	Email              string                    `json:"email"`
	PaidTier           bool                      `json:"paidTier"`
	CreatedAt          time.Time                 `json:"createdAt"`
	Status             string                    `json:"status"`
	UserAgent          string                    `json:"userAgent"`
	DefaultPlacement   storj.PlacementConstraint `json:"defaultPlacement"`
	ProjectUsageLimits []ProjectUsageLimits      `json:"projectUsageLimits"`
}

User holds information about a user account.

type UserManagementHandler

type UserManagementHandler struct {
	// contains filtered or unexported fields
}

UserManagementHandler is an api handler that implements all UserManagement API endpoints functionality.

func NewUserManagement

func NewUserManagement(log *zap.Logger, mon *monkit.Scope, service UserManagementService, router *mux.Router, auth *Authorizer) *UserManagementHandler

type UserManagementService

type UserManagementService interface {
	GetUserByEmail(ctx context.Context, email string) (*User, api.HTTPError)
}