folder

Documentation

Index

• Constants
• Variables
• type CreateFolderCommand
• type DeleteFolderCommand
• type DescendantCounts
• type Folder
  • func NewFolder(title string, description string) *Folder
  • func (f *Folder) IsGeneral() bool
  • func (f *Folder) WithURL() *Folder
• type FolderStore
• type GetChildrenQuery
• type GetDescendantCountsQuery
• type GetFolderQuery
• type GetFoldersQuery
• type GetParentsQuery
• type HasAdminPermissionInDashboardsOrFoldersQuery
• type HasEditPermissionInFoldersQuery
• type MoveFolderCommand
• type RegistryService
• type Service
• type UpdateFolderCommand

Constants

const (
	GeneralFolderUID      = "general"
	RootFolderUID         = ""
	MaxNestedFolderDepth  = 4
	SharedWithMeFolderUID = "sharedwithme"
)

Variables

var ErrBadRequest = errutil.BadRequest("folder.bad-request")

var ErrCircularReference = errutil.BadRequest("folder.circular-reference", errutil.WithPublicMessage("Circular reference detected"))

var ErrConflict = errutil.Conflict("folder.conflict")

var ErrDatabaseError = errutil.Internal("folder.database-error")

var ErrFolderNotEmpty = errutil.BadRequest("folder.not-empty", errutil.WithPublicMessage("Folder cannot be deleted: folder is not empty"))

var ErrFolderNotFound = errutil.NotFound("folder.notFound")

var ErrInternal = errutil.Internal("folder.internal")

var ErrMaximumDepthReached = errutil.BadRequest("folder.maximum-depth-reached", errutil.WithPublicMessage("Maximum nested folder depth reached"))

var ErrTargetRegistrySrvConflict = errutil.Internal("folder.target-registry-srv-conflict")

var GeneralFolder = Folder{ID: 0, Title: "General"}

var RootFolder = &Folder{ID: 0, Title: "Root", UID: GeneralFolderUID, ParentUID: ""}

var SharedWithMeFolder = Folder{
	Title:       "Shared with me",
	Description: "Dashboards and folders shared with me",
	UID:         SharedWithMeFolderUID,
	ParentUID:   "",
	ID:          -1,
}

Types

type CreateFolderCommand

type CreateFolderCommand struct {
	UID         string `json:"uid"`
	OrgID       int64  `json:"-"`
	Title       string `json:"title"`
	Description string `json:"description"`
	ParentUID   string `json:"parentUid"`

	SignedInUser identity.Requester `json:"-"`
}

CreateFolderCommand captures the information required by the folder service to create a folder.

type DeleteFolderCommand

type DeleteFolderCommand struct {
	UID              string `json:"uid" xorm:"uid"`
	OrgID            int64  `json:"orgId" xorm:"org_id"`
	ForceDeleteRules bool   `json:"forceDeleteRules"`

	SignedInUser identity.Requester `json:"-"`
}

DeleteFolderCommand captures the information required by the folder service to delete a folder.

type DescendantCounts

type DescendantCounts map[string]int64

type Folder

type Folder struct {
	// Deprecated: use UID instead
	ID          int64  `xorm:"pk autoincr 'id'"`
	OrgID       int64  `xorm:"org_id"`
	UID         string `xorm:"uid"`
	ParentUID   string `xorm:"parent_uid"`
	Title       string
	Description string

	Created time.Time
	Updated time.Time

	// TODO: validate if this field is required/relevant to folders.
	// currently there is no such column
	Version      int
	URL          string
	UpdatedBy    int64
	CreatedBy    int64
	HasACL       bool
	Fullpath     string `xorm:"fullpath"`
	FullpathUIDs string `xorm:"fullpath_uids"`
}

func NewFolder

func NewFolder(title string, description string) *Folder

NewFolder tales a title and returns a Folder with the Created and Updated fields set to the current time.

func (*Folder) IsGeneral

func (f *Folder) IsGeneral() bool

func (*Folder) WithURL

func (f *Folder) WithURL() *Folder

type FolderStore

type FolderStore interface {
	// GetFolderByTitle retrieves a folder by its title
	// It expects a parentUID as last argument.
	// If parentUID is empty then the folder will be fetched from the root level
	// otherwise it will be fetched from the subfolder under the folder with the given UID.
	GetFolderByTitle(ctx context.Context, orgID int64, title string, parentUID *string) (*Folder, error)
	// GetFolderByUID retrieves a folder by its UID
	GetFolderByUID(ctx context.Context, orgID int64, uid string) (*Folder, error)
	// GetFolderByID retrieves a folder by its ID
	GetFolderByID(ctx context.Context, orgID int64, id int64) (*Folder, error)
	// GetFolders returns all folders for the given orgID and UIDs.
	GetFolders(ctx context.Context, orgID int64, uids []string) (map[string]*Folder, error)
}

FolderStore is a folder store.

type GetChildrenQuery

type GetChildrenQuery struct {
	UID   string
	OrgID int64
	Depth int64

	// Pagination options
	Limit int64
	Page  int64

	// Permission to filter by
	Permission dashboardaccess.PermissionType

	SignedInUser identity.Requester `json:"-"`

	// array of folder uids to filter by
	FolderUIDs []string `json:"-"`
}

type GetDescendantCountsQuery

type GetDescendantCountsQuery struct {
	UID   *string
	OrgID int64

	SignedInUser identity.Requester `json:"-"`
}

GetDescendantCountsQuery captures the information required by the folder service to return the count of descendants (direct and indirect) in a folder.

type GetFolderQuery

type GetFolderQuery struct {
	UID *string
	// Deprecated: use FolderUID instead
	ID           *int64
	Title        *string
	ParentUID    *string
	OrgID        int64
	WithFullpath bool

	SignedInUser identity.Requester `json:"-"`
}

GetFolderQuery is used for all folder Get requests. Only one of UID, ID, or Title should be set; if multiple fields are set by the caller the dashboard service will select the field with the most specificity, in order: ID, UID, Title.

type GetFoldersQuery

type GetFoldersQuery struct {
	OrgID            int64
	UIDs             []string
	WithFullpath     bool
	WithFullpathUIDs bool
	BatchSize        uint64

	// OrderByTitle is used to sort the folders by title
	// Set to true when ordering is meaningful (used for listing folders)
	// otherwise better to keep it false since ordering can have a performance impact
	OrderByTitle bool
	SignedInUser identity.Requester `json:"-"`
}

type GetParentsQuery

type GetParentsQuery struct {
	UID   string `xorm:"uid"`
	OrgID int64  `xorm:"org_id"`
}

GetParentsQuery captures the information required by the folder service to return a list of all parent folders of a given folder.

type HasAdminPermissionInDashboardsOrFoldersQuery

type HasAdminPermissionInDashboardsOrFoldersQuery struct {
	SignedInUser identity.Requester
}

type HasEditPermissionInFoldersQuery

type HasEditPermissionInFoldersQuery struct {
	SignedInUser identity.Requester
}

type MoveFolderCommand

type MoveFolderCommand struct {
	UID          string `json:"-"`
	NewParentUID string `json:"parentUid"`
	OrgID        int64  `json:"-"`

	SignedInUser identity.Requester `json:"-"`
}

MoveFolderCommand captures the information required by the folder service to move a folder.

type RegistryService

type RegistryService interface {
	DeleteInFolders(ctx context.Context, orgID int64, folderUIDs []string, user identity.Requester) error
	CountInFolders(ctx context.Context, orgID int64, folderUIDs []string, user identity.Requester) (int64, error)
	Kind() string
}

type Service

type Service interface {
	// GetChildren returns an array containing all child folders.
	GetChildren(ctx context.Context, q *GetChildrenQuery) ([]*Folder, error)
	// GetParents returns an array containing add parent folders if nested folders are enabled
	// otherwise it returns an empty array
	GetParents(ctx context.Context, q GetParentsQuery) ([]*Folder, error)
	Create(ctx context.Context, cmd *CreateFolderCommand) (*Folder, error)

	// GetFolder takes a GetFolderCommand and returns a folder matching the
	// request. One of UID, ID or Title must be included. If multiple values
	// are included in the request, Grafana will select one in order of
	// specificity (UID, ID, Title).
	// When fetching a folder by Title, callers can optionally define a ParentUID.
	// If ParentUID is not set then the folder will be fetched from the root level.
	// If WithFullpath is true it computes also the full path of a folder.
	Get(ctx context.Context, q *GetFolderQuery) (*Folder, error)

	// Update is used to update a folder's UID, Title and Description. To change
	// a folder's parent folder, use Move.
	Update(ctx context.Context, cmd *UpdateFolderCommand) (*Folder, error)
	Delete(ctx context.Context, cmd *DeleteFolderCommand) error
	// Move changes a folder's parent folder to the requested new parent.
	Move(ctx context.Context, cmd *MoveFolderCommand) (*Folder, error)
	RegisterService(service RegistryService) error
	// GetFolders returns org folders that are accessible by the signed in user by their UIDs.
	// If WithFullpath is true it computes also the full path of a folder.
	// The full path is a string that contains the titles of all parent folders separated by a slash.
	// If a folder contains a slash in its title, it is escaped with a backslash.
	// If FullpathUIDs is true it computes a string that contains the UIDs of all parent folders separated by slash.
	GetFolders(ctx context.Context, q GetFoldersQuery) ([]*Folder, error)
	GetDescendantCounts(ctx context.Context, q *GetDescendantCountsQuery) (DescendantCounts, error)
}

type UpdateFolderCommand

type UpdateFolderCommand struct {
	UID   string `json:"-"`
	OrgID int64  `json:"-"`
	// NewTitle it's an optional parameter used for overriding the existing folder title
	NewTitle *string `json:"title"` // keep same json tag with the legacy command for not breaking the existing APIs
	// NewDescription it's an optional parameter used for overriding the existing folder description
	NewDescription *string `json:"description"` // keep same json tag with the legacy command for not breaking the existing APIs
	NewParentUID   *string `json:"-"`

	// Version only used by the legacy folder implementation
	Version int `json:"version"`
	// Overwrite only used by the legacy folder implementation
	Overwrite bool `json:"overwrite"`

	SignedInUser identity.Requester `json:"-"`
}

UpdateFolderCommand captures the information required by the folder service to update a folder. Use Move to update a folder's parent folder.