Documentation
¶
Overview ¶
Package workspace manages workspaces, memberships, and invitations.
Index ¶
- Constants
- Variables
- type CreationDeniedError
- type CreationPolicy
- type DefaultAdopter
- type InvitationPreview
- type KeyShredder
- type MiddlewareSeeder
- type NetworkEnsurer
- type Orgs
- type PendingInvitation
- type Service
- func (s *Service) Accept(rawToken string, userID uint) (*models.Workspace, error)
- func (s *Service) AcceptByID(invitationID, userID uint) (*models.Workspace, error)
- func (s *Service) AssignCustomRole(workspaceID uint, actor models.WorkspaceRole, userID, customRoleID uint, ...) error
- func (s *Service) CanCreate(userID uint) error
- func (s *Service) CanJoinAnother(userID uint) error
- func (s *Service) CanOwnAnother(userID uint) error
- func (s *Service) Create(ownerID uint, displayName, handle, description string) (*models.Workspace, error)
- func (s *Service) CreateForOwner(ownerID uint, displayName, handle string) (*models.Workspace, error)
- func (s *Service) CreationPolicy(userID uint) CreationPolicy
- func (s *Service) Delete(id uint) error
- func (s *Service) EnsureSystem(ownerID uint) (*models.Workspace, error)
- func (s *Service) Get(id uint) (*models.Workspace, error)
- func (s *Service) Invite(workspaceID uint, actor models.WorkspaceRole, inviterID uint, email string, ...) (string, *models.WorkspaceInvitation, error)
- func (s *Service) ListForUser(userID uint) ([]models.WorkspaceWithRole, error)
- func (s *Service) ListInvitations(workspaceID uint) ([]models.WorkspaceInvitation, error)
- func (s *Service) ListInvitationsForEmail(email string) ([]PendingInvitation, error)
- func (s *Service) ListMembers(workspaceID uint) ([]models.WorkspaceMember, error)
- func (s *Service) PendingInvitationByToken(rawToken string) (*models.WorkspaceInvitation, error)
- func (s *Service) PreviewInvitation(rawToken string) (*InvitationPreview, error)
- func (s *Service) RegisterFromInvitation(rawToken string, user *models.User) (*models.Workspace, error)
- func (s *Service) RemoveMember(workspaceID uint, actor models.WorkspaceRole, userID uint) error
- func (s *Service) SetCreationPolicy(platformMode func() string)
- func (s *Service) SetDefaultAdopter(a DefaultAdopter)
- func (s *Service) SetKeyShredder(k KeyShredder)
- func (s *Service) SetLimits(globalLimit func() int, overrideEntitled func() bool)
- func (s *Service) SetMembershipLimits(globalLimit func() int, overrideEntitled func() bool)
- func (s *Service) SetMiddlewareSeeder(m MiddlewareSeeder)
- func (s *Service) SetName(ws *models.Workspace, newName string) error
- func (s *Service) SetOrgLimitsEntitled(entitled func() bool)
- func (s *Service) SetOrgs(o Orgs)
- func (s *Service) SetPlans(plans *repositories.PlanRepository)
- func (s *Service) SetQuota(q *quota.Service)
- func (s *Service) Update(ws *models.Workspace) error
- func (s *Service) UpdateMemberRole(workspaceID uint, actor models.WorkspaceRole, userID uint, ...) error
Constants ¶
const ( CreationSourceAdmin = "admin" CreationSourceUser = "user" CreationSourceOrganization = "organization" CreationSourcePlatform = "platform" )
Sources of a creation decision, reported by CreationPolicy.
const InvitationTTL = 7 * 24 * time.Hour
InvitationTTL is how long an invitation remains valid.
const SystemActor = models.WorkspaceRoleOwner
const SystemName = "system"
SystemName is the handle of the built-in platform system workspace. It is a reserved handle (see the slug package), claimable only by EnsureSystem.
Variables ¶
var ( ErrNameTaken = errors.New("workspace name already taken") ErrNameInvalid = errors.New("name must contain only lowercase letters, digits and hyphens") ErrNameReserved = errors.New("that workspace name is reserved") ErrSystemNameLocked = errors.New("the system workspace name cannot be changed") ErrLastOwner = errors.New("cannot remove or demote the last owner") ErrAlreadyMember = errors.New("user is already a member") ErrInvitePending = errors.New("a pending invitation for this email already exists") ErrInvalidInvite = errors.New("invalid or expired invitation") ErrInvalidRole = errors.New("invalid role") ErrServiceAccountOwner = errors.New("a service account cannot own a workspace") ErrSystemProtected = errors.New("the platform system workspace cannot be deleted") ErrOutranked = errors.New("cannot modify a member whose role outranks yours") ErrRoleAboveSelf = errors.New("cannot grant a role more privileged than your own") ErrWorkspaceLimitReached = errors.New("workspace limit reached for this user") ErrOrgWorkspaceLimitReached = errors.New("this organization has reached its workspace limit") ErrMembershipLimitReached = errors.New("workspace membership limit reached for this user") )
var ErrWorkspaceCreationNotAllowed = errors.New("you are not allowed to create workspaces")
ErrWorkspaceCreationNotAllowed matches every CreationDeniedError.
Functions ¶
This section is empty.
Types ¶
type CreationDeniedError ¶ added in v1.10.17
type CreationDeniedError struct{ Mode string }
CreationDeniedError is returned when the creation policy refuses a user. Mode is the rule that applied, or empty when a per-user override denied it.
func (*CreationDeniedError) Code ¶ added in v1.10.17
func (e *CreationDeniedError) Code() string
Code is the stable API error code.
func (*CreationDeniedError) Error ¶ added in v1.10.17
func (e *CreationDeniedError) Error() string
func (*CreationDeniedError) Is ¶ added in v1.10.17
func (e *CreationDeniedError) Is(target error) bool
type CreationPolicy ¶ added in v1.10.17
type CreationPolicy struct {
Allowed bool `json:"allowed"`
// Mode is the workspace creation mode that applied; empty when Source is admin or user.
Mode string `json:"mode,omitempty"`
Source string `json:"source"`
}
CreationPolicy is whether a user may create a workspace, and which rule decided it.
type DefaultAdopter ¶ added in v1.9.4
type DefaultAdopter interface {
AdoptFirstWorkspace(userID, workspaceID uint)
}
DefaultAdopter claims a user's first workspace as their landing workspace. Satisfied by usersettings.Service; injected after construction and nil-safe.
type InvitationPreview ¶ added in v1.10.17
type InvitationPreview struct {
WorkspaceName string `json:"workspace_name"`
InvitedByName string `json:"invited_by_name"`
Role models.WorkspaceRole `json:"role"`
Email string `json:"email"`
ExpiresAt time.Time `json:"expires_at"`
AccountExists bool `json:"account_exists"`
// OrganizationID is the realm the workspace belongs to; 0 for the default one.
OrganizationID uint `json:"-"`
}
InvitationPreview is what the holder of an invitation token may see before accepting it.
type KeyShredder ¶
KeyShredder permanently deletes a workspace's encryption keys (crypto-shred on delete). Implemented by the keyring service; injected, nil-safe.
type MiddlewareSeeder ¶ added in v1.5.0
MiddlewareSeeder creates a new workspace's default policy set. Implemented by the middleware service; injected, nil-safe, and best-effort (a seed failure never fails workspace creation).
type NetworkEnsurer ¶
type NetworkEnsurer interface {
EnsureDefault(ctx context.Context, workspaceID uint) (*models.Network, error)
}
NetworkEnsurer creates a workspace's default Docker network. Implemented by the network service; an interface keeps workspace decoupled from it.
type Orgs ¶ added in v1.10.4
type Orgs interface {
HomeOrganization(u *models.User) uint
CapReached(orgID uint) bool
Get(orgID uint) (*models.Organization, error)
}
Orgs resolves a user's home organization and that organization's caps. Satisfied by the organization service.
type PendingInvitation ¶
type PendingInvitation struct {
ID uint `json:"id"`
WorkspaceID uint `json:"workspace_id"`
WorkspaceName string `json:"workspace_name"`
Role models.WorkspaceRole `json:"role"`
InvitedByName string `json:"invited_by_name"`
ExpiresAt time.Time `json:"expires_at"`
CreatedAt time.Time `json:"created_at"`
}
PendingInvitation is an invitation enriched with the context the invited user needs to act on it — they are not yet a member and can't read the workspace.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
func NewService ¶
func NewService(repo *repositories.WorkspaceRepository, users *repositories.UserRepository, nets NetworkEnsurer) *Service
func (*Service) AcceptByID ¶
AcceptByID consumes an invitation by id, provided it is addressed to the user's own email. Used by the in-app pending-invitations list, where the raw token (delivered by email) is not available.
func (*Service) AssignCustomRole ¶ added in v1.10.9
func (s *Service) AssignCustomRole(workspaceID uint, actor models.WorkspaceRole, userID, customRoleID uint, baseRole models.WorkspaceRole) error
AssignCustomRole puts a member on a custom role whose rank is baseRole, under the same rank, last-owner and ownership-limit rules as a built-in role change.
func (*Service) CanCreate ¶ added in v1.10.17
CanCreate returns a CreationDeniedError when the creation policy refuses userID. Service accounts are left to canOwnAnother, which refuses them with a clearer error.
func (*Service) CanJoinAnother ¶
CanJoinAnother returns ErrMembershipLimitReached when userID is already at their effective membership limit. Public so auto-join paths such as SSO and SCIM can gate before adding a member. A no-op when limits are unwired or unlimited, and it fails open on a count error.
func (*Service) CanOwnAnother ¶ added in v1.10.21
canOwnAnother returns ErrWorkspaceLimitReached when userID is already at their effective workspace-ownership limit. No-op when limits are unwired or the effective limit is unlimited. Fails open on a count error (mirrors checkMemberCapacity), so a transient DB hiccup never blocks legitimate work. CanOwnAnother reports whether userID may become owner of one more workspace (the per-user ownership limit and the service-account rule). Exported for SSO group sync.
func (*Service) Create ¶
func (s *Service) Create(ownerID uint, displayName, handle, description string) (*models.Workspace, error)
Create makes a new workspace owned by ownerID. displayName is the free-text label; handle is the desired unique name — the URL and docker handle — derived from displayName when blank. The handle is always made unique and non-reserved by suffixing, so creation never fails on a collision.
func (*Service) CreateForOwner ¶ added in v1.10.21
func (s *Service) CreateForOwner(ownerID uint, displayName, handle string) (*models.Workspace, error)
CreateForOwner is a platform admin's create on a user's behalf. It skips the self-service creation policy and ownership limits, and takes the handle exactly: a taken or invalid handle is an error, never suffixed, so a caller that retries after a lost answer can recognise its own workspace.
func (*Service) CreationPolicy ¶ added in v1.10.17
func (s *Service) CreationPolicy(userID uint) CreationPolicy
CreationPolicy resolves whether userID may create a workspace: platform admins always may, then the Enterprise per-user override, the home organization's mode, and the platform mode.
func (*Service) Delete ¶
Delete removes a workspace, refusing to delete the built-in system workspace.
func (*Service) EnsureSystem ¶
EnsureSystem creates the built-in platform system workspace if it does not yet exist, owned by ownerID. It is privileged, so host-port bindings auto-approve, and flagged System so it cannot be deleted. Idempotent: it returns the existing workspace when already present.
func (*Service) Invite ¶
func (s *Service) Invite(workspaceID uint, actor models.WorkspaceRole, inviterID uint, email string, role models.WorkspaceRole) (string, *models.WorkspaceInvitation, error)
Invite creates a pending invitation and returns the raw token to deliver.
func (*Service) ListForUser ¶
func (s *Service) ListForUser(userID uint) ([]models.WorkspaceWithRole, error)
func (*Service) ListInvitations ¶
func (s *Service) ListInvitations(workspaceID uint) ([]models.WorkspaceInvitation, error)
func (*Service) ListInvitationsForEmail ¶
func (s *Service) ListInvitationsForEmail(email string) ([]PendingInvitation, error)
ListInvitationsForEmail returns the pending invitations addressed to an email, enriched with the workspace name and inviter for display.
func (*Service) ListMembers ¶
func (s *Service) ListMembers(workspaceID uint) ([]models.WorkspaceMember, error)
func (*Service) PendingInvitationByToken ¶ added in v1.10.17
func (s *Service) PendingInvitationByToken(rawToken string) (*models.WorkspaceInvitation, error)
PendingInvitationByToken returns the invitation for a raw token while it can still be accepted.
func (*Service) PreviewInvitation ¶ added in v1.10.17
func (s *Service) PreviewInvitation(rawToken string) (*InvitationPreview, error)
PreviewInvitation describes a pending invitation to the holder of its token.
func (*Service) RegisterFromInvitation ¶ added in v1.10.17
func (s *Service) RegisterFromInvitation(rawToken string, user *models.User) (*models.Workspace, error)
RegisterFromInvitation creates user from a pending invitation and joins them to its workspace in one step. The account takes the invited email, the workspace's organization and the invitation signup source. Every refusal that would reveal whether the address is registered is ErrInvalidInvite.
func (*Service) RemoveMember ¶
RemoveMember removes a member, refusing to remove the last owner or a member who outranks the caller.
func (*Service) SetCreationPolicy ¶ added in v1.10.17
SetCreationPolicy wires the platform workspace creation mode. The per-user override follows the same Enterprise entitlement as the per-user workspace limit (see SetLimits), and the organization mode the organizations entitlement. Nil-safe: unwired, anyone may create.
func (*Service) SetDefaultAdopter ¶ added in v1.9.4
func (s *Service) SetDefaultAdopter(a DefaultAdopter)
SetDefaultAdopter wires the first-workspace landing adoption (nil-safe).
func (*Service) SetKeyShredder ¶
func (s *Service) SetKeyShredder(k KeyShredder)
SetKeyShredder wires crypto-shred of a workspace's keys on delete (nil-safe).
func (*Service) SetLimits ¶
SetLimits wires per-user workspace-count enforcement. globalLimit returns the platform-wide max_workspaces_per_user default (-1 means unlimited, 0 none); overrideEntitled reports whether the Enterprise per-user override is licensed. An organization's own cap takes precedence over the platform value — see effectiveWorkspaceLimit. Nil-safe: unset means ownership is uncapped.
func (*Service) SetMembershipLimits ¶
SetMembershipLimits wires per-user membership-count enforcement — the join counterpart of SetLimits. globalLimit returns the max_workspace_memberships_per_user default (-1 unlimited, 0 none); overrideEntitled reports whether the Enterprise per-user override is licensed. Nil-safe.
func (*Service) SetMiddlewareSeeder ¶ added in v1.5.0
func (s *Service) SetMiddlewareSeeder(m MiddlewareSeeder)
SetMiddlewareSeeder wires the default-policy seeder used at workspace creation.
func (*Service) SetName ¶
SetName validates and applies a new handle to ws in memory; the caller persists via Update. The value is normalized to canonical form and must be valid, non-reserved and unique, and the system workspace's name is immutable. Unlike Create it does not auto-suffix, so a rename onto a taken handle is an error.
func (*Service) SetOrgLimitsEntitled ¶ added in v1.10.5
SetOrgLimitsEntitled wires the licence check for organization-scoped limits. Without the entitlement an org's stored caps are ignored and the platform defaults decide, because an unlicensed operator cannot edit those caps — enforcing a value they cannot change would strand them. Nil-safe: unset means org limits never apply.
func (*Service) SetOrgs ¶ added in v1.10.4
SetOrgs wires organization ownership of workspaces (nil-safe; without it a workspace is created with no organization, which resolves to the default one).
func (*Service) SetPlans ¶
func (s *Service) SetPlans(plans *repositories.PlanRepository)
SetPlans wires the plan repository so EnsureSystem can pin the platform system workspace to the Unlimited plan. Optional: when unset, the system workspace falls back to the default plan.
func (*Service) SetQuota ¶
SetQuota wires the quota service so member invitations/acceptances are gated by the workspace's effective max-members limit. Optional: when unset (or with enforcement disabled), membership is uncapped.
func (*Service) UpdateMemberRole ¶
func (s *Service) UpdateMemberRole(workspaceID uint, actor models.WorkspaceRole, userID uint, role models.WorkspaceRole) error