admin

package
v1.94.2 Latest Latest
Warning

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

Go to latest
Published: Dec 27, 2023 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 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 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 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 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 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 ProjectUsageLimits added in v1.94.1

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 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 *overlay.PlacementDefinitions,
) *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) GetUserByEmail added in v1.94.1

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

GetUserByEmail returns a verified user by its email address.

type User added in v1.94.1

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 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) (*User, api.HTTPError)
}

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