admin

package
v1.118.0-rc Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 20, 2024 License: AGPL-3.0 Imports: 22 Imported by: 0

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.

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

View Source 
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.

View Source 
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

View Source 
var Assets fs.FS = emptyfs.FS{}

Assets contains either the built admin/back-office/ui or it is nil.

View Source 
var ErrAuthorizer = errs.Class("authorizer")

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

View Source 
var ErrPlacementsAPI = errs.Class("admin placements api")
View Source 
var ErrProjectsAPI = errs.Class("admin projects api")
View Source 
var ErrSettingsAPI = errs.Class("admin settings api")
View Source 
var ErrUsersAPI = errs.Class("admin users api")
View Source 
var (
	// Error is the error class that wraps all the errors returned by this package.
	Error = errs.Class("satellite-admin")
)

Functions

This section is empty.

Types

type AccountFlags added in v1.96.2 

type AccountFlags struct {
	Create                 bool `json:"create"`
	Delete                 bool `json:"delete"`
	History                bool `json:"history"`
	List                   bool `json:"list"`
	Projects               bool `json:"projects"`
	Search                 bool `json:"search"`
	Suspend                bool `json:"suspend"`
	Unsuspend              bool `json:"unsuspend"`
	ResetMFA               bool `json:"resetMFA"`
	UpdateInfo             bool `json:"updateInfo"`
	UpdateLimits           bool `json:"updateLimits"`
	UpdatePlacement        bool `json:"updatePlacement"`
	UpdateStatus           bool `json:"updateStatus"`
	UpdateValueAttribution bool `json:"updateValueAttribution"`
	View                   bool `json:"view"`
}

AccountFlags are the feature flags related to user's accounts.

type Authorization added in v1.93.1 

type Authorization uint64

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

func (Authorization) Has added in v1.93.1 

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

Has returns true if auth has all the passed permissions.

type Authorizer added in v1.93.1 

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

Authorizer checks if a group has certain permissions.

func NewAuthorizer added in v1.93.1 

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 added in v1.93.1 

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

HasPermissions check if group has all perms.

func (*Authorizer) IsRejected added in v1.94.1 

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 BucketFlags added in v1.96.2 

type BucketFlags struct {
	Create                 bool `json:"create"`
	Delete                 bool `json:"delete"`
	History                bool `json:"history"`
	List                   bool `json:"list"`
	UpdateInfo             bool `json:"updateInfo"`
	UpdatePlacement        bool `json:"updatePlacement"`
	UpdateValueAttribution bool `json:"updateValueAttribution"`
	View                   bool `json:"view"`
}

BucketFlags are the feature flags related to buckets.

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 Defaults added in v1.96.2 

type Defaults struct {
	MaxBuckets int
	RateLimit  int
}

Defaults contains default values for limits which are not stored in the DB.

type FeatureFlags added in v1.96.2 

type FeatureFlags struct {
	Account         AccountFlags `json:"account"`
	Project         ProjectFlags `json:"project"`
	Bucket          BucketFlags  `json:"bucket"`
	Dashboard       bool         `json:"dashboard"`
	Operator        bool         `json:"operator"` // This is the information about the logged operator
	SignOut         bool         `json:"signOut"`
	SwitchSatellite bool         `json:"switchSatellite"`
}

FeatureFlags indicates what Admin service features are enabled or disabled. The features are usually disabled when they are not fully implemented.

type Permission added in v1.93.1 

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 added in v1.93.1 

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

PlacementInfo contains the ID and location of a placement rule.

type PlacementManagementHandler added in v1.93.1 

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

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

func NewPlacementManagement added in v1.93.1 

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

type PlacementManagementService added in v1.93.1 

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

type Project added in v1.96.2 

type Project struct {
	ID               uuid.UUID                 `json:"id"` // This is the public ID
	Name             string                    `json:"name"`
	Description      string                    `json:"description"`
	UserAgent        string                    `json:"userAgent"`
	Owner            User                      `json:"owner"`
	CreatedAt        time.Time                 `json:"createdAt"`
	DefaultPlacement storj.PlacementConstraint `json:"defaultPlacement"`

	// RateLimit is `nil` when satellite applies the configured default rate limit.
	RateLimit *int `json:"rateLimit"`
	// BurstLimit is `nil` when satellite applies the configured default burst limit.
	BurstLimit *int `json:"burstLimit"`
	// Maxbuckets is `nil` when satellite applies the configured default max buckets.
	MaxBuckets *int `json:"maxBuckets"`
	ProjectUsageLimits[*int64]
}

Project contains the information and configurations of a project.

type ProjectFlags added in v1.96.2 

type ProjectFlags struct {
	Create                 bool `json:"create"`
	Delete                 bool `json:"delete"`
	History                bool `json:"history"`
	List                   bool `json:"list"`
	UpdateInfo             bool `json:"updateInfo"`
	UpdateLimits           bool `json:"updateLimits"`
	UpdatePlacement        bool `json:"updatePlacement"`
	UpdateValueAttribution bool `json:"updateValueAttribution"`
	View                   bool `json:"view"`
	MemberList             bool `json:"memberList"`
	MemberAdd              bool `json:"memberAdd"`
	MemberRemove           bool `json:"memberRemove"`
}

ProjectFlags are the feature flags related to projects.

type ProjectLimitsUpdate added in v1.96.2 

type ProjectLimitsUpdate struct {
	MaxBuckets     int   `json:"maxBuckets"`
	StorageLimit   int64 `json:"storageLimit"`
	BandwidthLimit int64 `json:"bandwidthLimit"`
	SegmentLimit   int64 `json:"segmentLimit"`
	RateLimit      int   `json:"rateLimit"`
	BurstLimit     int   `json:"burstLimit"`
}

ProjectLimitsUpdate contains all limit values to be updated.

type ProjectManagementHandler added in v1.96.2 

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

ProjectManagementHandler is an api handler that implements all ProjectManagement API endpoints functionality.

func NewProjectManagement added in v1.96.2 

func NewProjectManagement(log *zap.Logger, mon *monkit.Scope, service ProjectManagementService, router *mux.Router, auth *Authorizer) *ProjectManagementHandler

type ProjectManagementService added in v1.96.2 

type ProjectManagementService interface {
	GetProject(ctx context.Context, publicID uuid.UUID) (*Project, api.HTTPError)
	UpdateProjectLimits(ctx context.Context, publicID uuid.UUID, request ProjectLimitsUpdate) api.HTTPError
}

type ProjectUsageLimits added in v1.94.1 

type ProjectUsageLimits[T ~int64 | *int64] struct {
	BandwidthLimit T      `json:"bandwidthLimit"`
	BandwidthUsed  int64  `json:"bandwidthUsed"`
	StorageLimit   T      `json:"storageLimit"`
	StorageUsed    *int64 `json:"storageUsed"`
	SegmentLimit   T      `json:"segmentLimit"`
	SegmentUsed    *int64 `json:"segmentUsed"`
}

ProjectUsageLimits holds project usage limits and current usage. It uses generics for allowing to report the limits fields with nil values when they are read from the DB projects table.

StorageUsed 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 added in v1.94.1 

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

Service provides functionality for administrating satellites.

func NewService added in v1.94.1 

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

NewService creates a new satellite administration service.

func (*Service) GetPlacements added in v1.94.1 

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

GetPlacements returns IDs and locations of placement rules.

func (*Service) GetProject added in v1.96.2 

func (s *Service) GetProject(ctx context.Context, id uuid.UUID) (*Project, api.HTTPError)

GetProject gets the project info.

func (*Service) GetSettings added in v1.96.2 

func (s *Service) GetSettings(ctx context.Context) (*Settings, api.HTTPError)

GetSettings returns the service settings.

func (*Service) GetUserByEmail added in v1.94.1 

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

GetUserByEmail returns a verified user by its email address.

func (*Service) UpdateProjectLimits added in v1.96.2 

func (s *Service) UpdateProjectLimits(ctx context.Context, id uuid.UUID, req ProjectLimitsUpdate) api.HTTPError

UpdateProjectLimits updates the project's max buckets, storage, bandwidth, segment, rate, and burst limits.

type Settings added in v1.96.2 

type Settings struct {
	Admin SettingsAdmin `json:"admin"`
}

Settings contains relevant settings for the consumers of this service. It may contain settings of:

- this service.

- the server that exposes the service.

- related Storj services (e.g. Satellite).

type SettingsAdmin added in v1.96.2 

type SettingsAdmin struct {
	Features FeatureFlags `json:"features"`
}

SettingsAdmin are the settings of this service and the server that exposes it.

type SettingsHandler added in v1.96.2 

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

SettingsHandler is an api handler that implements all Settings API endpoints functionality.

func NewSettings added in v1.96.2 

func NewSettings(log *zap.Logger, mon *monkit.Scope, service SettingsService, router *mux.Router) *SettingsHandler

type SettingsService added in v1.96.2 

type SettingsService interface {
	GetSettings(ctx context.Context) (*Settings, api.HTTPError)
}

type User added in v1.94.1 

type User struct {
	ID       uuid.UUID `json:"id"`
	FullName string    `json:"fullName"`
	Email    string    `json:"email"`
}

User holds the user's information.

type UserAccount added in v1.96.2 

type UserAccount struct {
	User
	PaidTier         bool                      `json:"paidTier"`
	CreatedAt        time.Time                 `json:"createdAt"`
	Status           string                    `json:"status"`
	UserAgent        string                    `json:"userAgent"`
	DefaultPlacement storj.PlacementConstraint `json:"defaultPlacement"`
	Projects         []UserProject             `json:"projects"`
}

UserAccount holds information about a user's account.

type UserManagementHandler added in v1.94.1 

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

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

func NewUserManagement added in v1.94.1 

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

type UserManagementService added in v1.94.1 

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

type UserProject added in v1.96.2 

type UserProject struct {
	ID   uuid.UUID `json:"id"` // This is the public ID
	Name string    `json:"name"`
	ProjectUsageLimits[int64]
}

UserProject is project owned by a user with basic information, usage, and limits.

Source Files

View all Source files

Directories

Path Synopsis
Package main defines the satellite administration API through the API generator and generates source code of the API server handlers and clients and the documentation markdown document.
 Package main defines the satellite administration API through the API generator and generates source code of the API server handlers and clients and the documentation markdown document.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.