Documentation
¶
Index ¶
- Constants
- Variables
- func IsGroupProjectLockConflict(err error) bool
- func IsValidDiscoverability(d int) bool
- func IsValidRole(r int) bool
- func ListActiveProjectMemberUIDs(ctxDB *dbr.Session, projectID string) ([]string, string, error)
- func ListProjectGroupRelationsByProjectIDs(ctx *config.Context, spaceID, uid string, projectIDs []string) (map[string][]ProjectGroupRelation, error)
- func LockGroupProjectAccessesTx(tx *dbr.Tx, actorUID string, projectIDs []string, expectedSpaceID string, ...) (map[string]GroupProjectAccess, error)
- func LockGroupProjectSpaceAccessTx(tx *dbr.Tx, actorUID, expectedSpaceID string, seatRefs map[string]int64) (bool, error)
- func PrepareGroupProjectSpaceSeatRefs(session *dbr.Session, spaceID string, uids []string) (map[string]int64, error)
- func RegisterProjectDisbandStep(name string, fn DisbandStep)
- func RegisterSidebarSectionProvisioner(fn SidebarSectionProvisioner)
- func RegisterSidebarSectionRemover(fn SidebarSectionRemover)
- func RetryGroupProjectLockConflict(fn func() error) error
- type AuditEntry
- type Capabilities
- type CollaborationRoleModel
- type CollaborationRoleResp
- type Config
- type DB
- type DisbandStep
- type GroupProjectAccess
- func AuthorizeGroupProjectReadTx(tx *dbr.Tx, actorUID, projectID, expectedSpaceID string) (GroupProjectAccess, error)
- func LockGroupProjectAccessTx(tx *dbr.Tx, actorUID, projectID, expectedSpaceID string, ...) (GroupProjectAccess, error)
- func LockGroupProjectCreateAccessTx(tx *dbr.Tx, actorUID, projectID, expectedSpaceID string, prepared []string, ...) (access GroupProjectAccess, expanded bool, err error)
- type MemberListResult
- type MemberModel
- type MemberReadPage
- type MemberResp
- type Model
- type Project
- type ProjectDisband
- type ProjectGroupRelation
- type ProvisioningConfig
- type RemovalJob
- type Resp
- type SidebarSectionProvisioner
- type SidebarSectionRemover
Constants ¶
const ( // TargetFleet is octo-fleet, whose container is a `workspace`. TargetFleet = "fleet" // TargetDrive is octo-drive, whose container is a shared `drive_space`. TargetDrive = "drive" )
Provisioning targets. Low-cardinality enum: these two strings reach the `target` column, a metric label and log lines, so they are constants rather than operator-supplied text.
const ( // ProvisionFleetSecretEnv is Fleet's per-target HMAC secret. ProvisionFleetSecretEnv = "OCTO_PROJECT_PROVISION_FLEET_SECRET" // DriveInternalTokenEnv is Drive's X-Internal-Token credential. DriveInternalTokenEnv = "OCTO_DRIVE_INTERNAL_TOKEN" )
Environment knobs for eager subsystem provisioning (brief D2, Shape S).
Exported where main.go needs the values: Fleet's HMAC secret and Drive's internal service token are fed into cardactiondispatch.Registry.ValidateNotifyTokenExclusions, which is the ONLY place that also sees the dynamic per-route notify tokens and callback secrets loaded from OCTO_CARD_ACTION_ROUTES. A single leaked value must never authorize both provisioning into a subsystem and minting a card action.
const ( // LifecycleEventProjectCreated announces a new project. The consumer provisions // its own record under the SAME id and the project is not usable until it // confirms — so this event is the only one whose failure is visible to the // person who triggered it. LifecycleEventProjectCreated = "project.created" // LifecycleEventMemberRevoked withdraws one member. This is the event whose loss // is a security failure rather than a stale display: until it lands, the // removed member can still execute on the consumer's side. LifecycleEventMemberRevoked = "project.member_revoked" // LifecycleEventArchived stops execution for the whole project. LifecycleEventArchived = "project.archived" // LifecycleEventRestored makes an archived project usable again. It does not // restore anything the revocations already tore down. LifecycleEventRestored = "project.restored" // LifecycleEventMetadataUpdated syncs the display copy of name and description. // The only event type whose loss is purely cosmetic. LifecycleEventMetadataUpdated = "project.metadata_updated" )
Event types. These strings are wire contract with the consumer, so they are spelled here once and never assembled from parts.
const ( // StatusDisbanded — the project has been disbanded. Read paths treat it // as nonexistent; project names are independent labels. StatusDisbanded = 0 // StatusNormal — active. StatusNormal = 1 )
Project status (octo_project.status).
const ( // MemberStatusRemoved — the seat is gone but the row stays for audit. MemberStatusRemoved = 0 // MemberStatusActive — an active seat. I1 constrains exactly these rows. MemberStatusActive = 1 )
Member status (octo_project_member.status). Rows are never deleted, so re-adding a member is a status flip rather than an INSERT that a unique index could reject.
const ( // RoleCommon — ordinary project member. RoleCommon = 0 // RoleAdmin — may edit the project and manage ordinary members. RoleAdmin = 1 // RoleOwner — may additionally disband and change roles. RoleOwner = 2 )
Member roles (octo_project_member.role). Ordered, and the ordering is load-bearing: the transitive-protection rules compare roles numerically.
const ( // DiscoverabilitySpaceListed — legacy display classification. DiscoverabilitySpaceListed = 0 // DiscoverabilityUnlisted — legacy display classification. DiscoverabilityUnlisted = 1 )
Discoverability (octo_project.discoverability).
Project discoverability is retained for storage compatibility; all Project reads still require an active Space identity and active Project membership.
const ( // JoinModeOpen — any Space member may join without an invite (P2). JoinModeOpen = 0 // JoinModeInviteOnly — admission is by invite or admin add. P0 default. JoinModeInviteOnly = 1 )
Join modes (octo_project.join_mode).
P0 has NO self-service join path — the invite surface is P2 — so the column exists with its DDL default and NOTHING above the storage layer reads or writes it. Same treatment as is_official: no model field, no request field, no response field. A client-visible join_mode with no enforcement point would let deployments persist join_mode=0 today and hand every such row open-join semantics the day the P2 path lands, with nobody re-consenting (yujiawei S-2, PR #841).
const ( CollaborationRoleSourceBuiltin = "builtin" CollaborationRoleSourceCustom = "custom" )
const ( // LifecycleEventSecretEnv is the HMAC secret for outbound lifecycle events. // // A shared secret rather than a bearer token, matching the provisioning // channel (pkg/octosign) rather than inventing a second scheme. Two reasons, // and the first is the one main.go's credential registry states: a bearer // token we SEND is a credential the peer could send back to us, while an HMAC // secret proves possession without ever crossing the wire. The second is that // the signature covers method, path, timestamp, event id and body, so it binds // the request; a bearer authenticates the caller and says nothing about what // was sent. // // Exported so main.go can include it in the cross-capability exclusion checks // without a second copy of the literal drifting out of sync. LifecycleEventSecretEnv = "OCTO_PROJECT_LIFECYCLE_EVENT_SECRET" )
Environment knobs. Every limit is read through this file so no handler carries a literal — the acceptance criterion is "each limit is read from config, not a literal", and a config struct built once per process is what makes that true for the quota checks as well as the worker cadence.
Variables ¶
var ( ErrGroupProjectInvalid = errors.New("project: group access request invalid") ErrGroupProjectNotFound = errors.New("project: group access project not found") ErrGroupProjectForbidden = errors.New("project: group access forbidden") ErrGroupProjectSpaceConflict = errors.New("project: group access space conflict") ErrGroupProjectDependency = errors.New("project: group access dependency unavailable") )
Errors returned by the group-facing Project authorization seam. The group module maps these to its own localized wire errors; callers must not infer a missing Project from a database failure.
var ErrMemberListNotFound = errors.New("project member list is not available in this scope")
ErrMemberListNotFound folds unavailable or incorrectly scoped Projects together.
Functions ¶
func IsGroupProjectLockConflict ¶ added in v1.19.0
IsGroupProjectLockConflict reports whether an error is one of the transient InnoDB lock conflicts covered by RetryGroupProjectLockConflict. It lets a best-effort sub-operation refuse to swallow a deadlock that already rolled back its containing transaction.
func IsValidDiscoverability ¶
IsValidDiscoverability reports whether d is a known discoverability value.
func IsValidRole ¶
IsValidRole reports whether r is an assignable role.
func ListActiveProjectMemberUIDs ¶ added in v1.19.0
ListActiveProjectMemberUIDs returns a non-locking snapshot for create preparation. It is advisory only; the create path must call LockGroupProjectCreateAccessTx before writing anything.
func ListProjectGroupRelationsByProjectIDs ¶ added in v1.19.0
func ListProjectGroupRelationsByProjectIDs( ctx *config.Context, spaceID, uid string, projectIDs []string, ) (map[string][]ProjectGroupRelation, error)
ListProjectGroupRelationsByProjectIDs is the batched relation-only projection used by the category sidebar. A requested Project without an active Project seat for uid receives an empty slice; pin preferences do not widen this gate.
func LockGroupProjectAccessesTx ¶ added in v1.19.0
func LockGroupProjectAccessesTx(tx *dbr.Tx, actorUID string, projectIDs []string, expectedSpaceID string, seatRefs map[string]int64) (map[string]GroupProjectAccess, error)
LockGroupProjectAccessesTx locks every candidate Space seat and user row before locking any Project row. It then locks each Project and the actor's Project seat in deterministic ID order.
prepared is used only by Project-backed group creation. Relation operations pass no candidates, so the actor is the sole candidate. seatRefs must have been prepared before the caller began its write transaction. The helper never starts, commits, or rolls back tx.
func LockGroupProjectSpaceAccessTx ¶ added in v1.19.0
func LockGroupProjectSpaceAccessTx(tx *dbr.Tx, actorUID, expectedSpaceID string, seatRefs map[string]int64) (bool, error)
LockGroupProjectSpaceAccessTx locks an actor's native Space access in the same seat -> Space -> user order used by Project-backed writes. It is used for an unbound relation, where there is no Project row to lock.
func PrepareGroupProjectSpaceSeatRefs ¶ added in v1.19.0
func PrepareGroupProjectSpaceSeatRefs(session *dbr.Session, spaceID string, uids []string) (map[string]int64, error)
PrepareGroupProjectSpaceSeatRefs resolves the requested Space-member identities before a write transaction begins. The returned primary keys are advisory only: every locking helper revalidates the id/Space/UID/status tuple under the transaction lock.
func RegisterProjectDisbandStep ¶ added in v1.19.0
func RegisterProjectDisbandStep(name string, fn DisbandStep)
RegisterProjectDisbandStep registers work to run when a project is disbanded.
func RegisterSidebarSectionProvisioner ¶ added in v1.19.0
func RegisterSidebarSectionProvisioner(fn SidebarSectionProvisioner)
func RegisterSidebarSectionRemover ¶ added in v1.19.0
func RegisterSidebarSectionRemover(fn SidebarSectionRemover)
func RetryGroupProjectLockConflict ¶ added in v1.19.0
RetryGroupProjectLockConflict reuses the Project module's bounded retry policy for group-facing write transactions. The callback must own one whole transaction attempt and must not include post-commit side effects.
Types ¶
type AuditEntry ¶
type AuditEntry struct {
Action string
ActorUID string
TargetUID string
ProjectID string
SpaceID string
Reason string
Extra []zap.Field
}
AuditEntry is one audit record.
A struct plus an injectable sink rather than a bare log call, because otherwise the acceptance criterion "each write path emits an audit entry carrying the actor, the target and the reason" is not checkable: the only way to assert on a zap line routed through octo-lib's TLog is to capture the process's logger, which every parallel test would then fight over. The seam is the same trick middleware.go uses for the cache-DEL failure branch.
type Capabilities ¶
type Capabilities struct {
CanUpdate bool `json:"can_update"`
CanDisband bool `json:"can_disband"`
CanManageMember bool `json:"can_manage_member"`
CanChangeRole bool `json:"can_change_role"`
CanLeave bool `json:"can_leave"`
CanViewMembers bool `json:"can_view_members"`
}
Capabilities is the server's verdict on what the caller may do with this project, so clients never derive permissions from a role number.
type CollaborationRoleModel ¶ added in v1.19.0
type CollaborationRoleModel struct {
RoleID string `db:"role_id"`
ProjectID string `db:"project_id"`
BuiltinKey string `db:"builtin_key"`
Name string `db:"name"`
NormalizedName string `db:"normalized_name"`
Source string `db:"source"`
CreatorUID string `db:"creator_uid"`
CreatedAt time.Time `db:"created_at"`
UpdatedAt time.Time `db:"updated_at"`
}
type CollaborationRoleResp ¶ added in v1.19.0
type Config ¶
type Config struct {
CreateEnabled bool
CollaborationRoleEnabled bool
// ReconcileEnabled gates the three scans that JOIN legacy Space tables in one
// block — see envReconcileEnabled for the list, for why it is separate from
// CreateEnabled, and for why its scope is narrow.
ReconcileEnabled bool
MaxPerSpace int
MaxPerCreator int
MaxMembers int
MaxPinned int
MaxDailyCreate int
MemberBatchMax int
CollaborationRoleMaxPerProject int
CollaborationRoleMaxPerMember int
DayBoundary *time.Location
ReconcileInterval time.Duration
ReconcileLimit int
MetricsInterval time.Duration
// Project lifecycle outbox.
LifecycleEventsEnabled bool
LifecycleEventURL string
LifecycleEventSecret string
LifecycleEventTimeout time.Duration
// LifecycleEventProblem is why the secret was dropped, when it was. Carried
// rather than logged at load, for the reason ProvisioningConfig.Problems is:
// loadConfig has no logger, and a config loader that logs is a config loader
// that cannot be tested without capturing the process-wide one.
LifecycleEventProblem error
// Provisioning is the eager subsystem-container configuration (brief D2).
// Zero value = inert: no outbox row is enqueued and no worker starts, which is
// the default until an operator names a target. See config_provisioning.go.
Provisioning ProvisioningConfig
}
Config is the resolved per-process configuration.
type DB ¶
type DB struct {
// contains filtered or unexported fields
}
DB is the modules/project data-access layer.
Two conventions this file follows deliberately, both because getting them wrong is silent:
**Explicit column lists on every write.** Not util.AttrToUnderscore. Two columns must never appear in an INSERT or UPDATE: `active_name` is a STORED generated column (MySQL rejects naming it with error 3105) and `is_official` has no P0 writer by design. A reflective column list derives from struct fields, so it would start writing either one the moment somebody adds the field — and `is_official` would then be written with a value that happens to equal the default, making the regression invisible. `member_epoch` and `collaboration_role_epoch` are likewise absent from the insert list: they take the DDL defaults, so their only writers are atomic `epoch = epoch + 1` statements, which makes monotonicity checkable by grep.
**dbr backtick asymmetry.** Update / InsertInto / DeleteFrom take the bare table name (dbr quotes it); From / Select need manual backticks. Getting it backwards yields error 1064 on a reserved word, and the reconcile scans join `space`, which IS reserved.
type DisbandStep ¶ added in v1.19.0
type DisbandStep func(ctx *config.Context, disband ProjectDisband) error
DisbandStep reverts whatever the registering module attached to the project.
type GroupProjectAccess ¶ added in v1.19.0
type GroupProjectAccess struct {
ProjectID string
SpaceID string
ActorUID string
ActorRole int
MemberUIDs []string
EligibleUIDs []string
SpaceMemberUIDs []string
}
GroupProjectAccess is the current, transactionally revalidated Project membership view consumed by group relation and Project-backed group create paths. MemberUIDs is populated only by LockGroupProjectCreateAccessTx. EligibleUIDs contains active user accounts among the create candidates; SpaceMemberUIDs contains active seats in the Project's Space. Both lists are populated only for Project-backed group creation so the Group service can apply native external-member semantics without opening another transaction.
func AuthorizeGroupProjectReadTx ¶ added in v1.19.0
func AuthorizeGroupProjectReadTx(tx *dbr.Tx, actorUID, projectID, expectedSpaceID string) (GroupProjectAccess, error)
AuthorizeGroupProjectReadTx revalidates an active Project member, active account, and the Project's current Space from a caller-owned repeatable-read transaction. It intentionally takes no locks: relation reads must not contend with relation writes.
func LockGroupProjectAccessTx ¶ added in v1.19.0
func LockGroupProjectAccessTx(tx *dbr.Tx, actorUID, projectID, expectedSpaceID string, seatRefs map[string]int64) (GroupProjectAccess, error)
LockGroupProjectAccessTx is the single-target convenience form used by callers that already know they have no source Project to lock.
func LockGroupProjectCreateAccessTx ¶ added in v1.19.0
func LockGroupProjectCreateAccessTx(tx *dbr.Tx, actorUID, projectID, expectedSpaceID string, prepared []string, seatRefs map[string]int64) (access GroupProjectAccess, expanded bool, err error)
LockGroupProjectCreateAccessTx obtains actor authorization and the current effective Project-member snapshot under one transaction. prepared is the advisory candidate set from the preparation phase; expanded reports whether a new Project member appeared after that phase and requires retrying.
type MemberListResult ¶ added in v1.24.0
type MemberListResult struct {
Members []*MemberResp
Total int64
}
MemberListResult exposes the existing wire projection, not internal database rows.
func ListProjectMembersInSpace ¶ added in v1.24.0
func ListProjectMembersInSpace(ctx context.Context, session *dbr.Session, spaceID, projectID string, page MemberReadPage) (*MemberListResult, error)
ListProjectMembersInSpace is a peer-authorized read service. Its caller must authorize the end user first. The active Space/Project checks, counted page, identities and roles share one bounded read-only snapshot. It creates no Project API instance, workers or runtime registrations.
type MemberModel ¶
type MemberModel struct {
ProjectID string `db:"project_id"`
UID string `db:"uid"`
SpaceID string `db:"space_id"`
Role int `db:"role"`
Status int `db:"status"`
// Removing is D4's seat-closing flag: 1 means the seat is being torn down
// while Status is still MemberStatusActive.
//
// Every authorization read treats Removing == 1 as a NON-member — the member
// list and middleware's role resolution use this clause. Status stays active
// until the removal worker finishes registered cleanup; native group membership
// is independent and is not mutated by this Project-side seat close.
Removing int `db:"removing"`
InviteUID string `db:"invite_uid"`
CreatedAt time.Time `db:"created_at"`
// JoinedAt is the start of the current active membership round. During the
// rolling expand window legacy writers may leave it NULL; every read projection
// uses COALESCE(joined_at, created_at) before scanning this time.Time field.
// New admissions initialize it with CreatedAt and re-admissions refresh it.
JoinedAt time.Time `db:"joined_at"`
UpdatedAt time.Time `db:"updated_at"`
}
MemberModel is an octo_project_member row.
type MemberReadPage ¶ added in v1.24.0
MemberReadPage is the bounded roster page accepted by the cross-module service.
func MemberReadPageParams ¶ added in v1.24.0
func MemberReadPageParams(query url.Values) MemberReadPage
MemberReadPageParams preserves the ordinary Project page/limit contract.
type MemberResp ¶
type MemberResp struct {
UID string `json:"uid"`
Name string `json:"name"`
Role int `json:"role"`
InviteUID string `json:"invite_uid"`
// Robot is 1 for an AI agent seat, 0 for a person (D16). Without it the
// roster cannot be rendered the way the directory renders it — agents
// nested under the person who owns them — and a client would have to guess
// from the uid shape.
Robot int `json:"robot"`
// OwnerUID is the agent's owner (robot.creator_uid); empty for a person and
// for an agent whose owner row is gone. It is the join key the client uses
// to nest an agent under its owner.
OwnerUID string `json:"owner_uid"`
CollaborationRoles []CollaborationRoleResp `json:"collaboration_roles"`
CreatedAt string `json:"created_at"`
JoinedAt string `json:"joined_at"`
}
MemberResp is one row of the project member roster.
type Model ¶
type Model struct {
ID int64 `db:"id"`
ProjectID string `db:"project_id"`
SpaceID string `db:"space_id"`
Name string `db:"name"`
Description string `db:"description"`
Logo string `db:"logo"`
Creator string `db:"creator"`
Discoverability int `db:"discoverability"`
MaxMembers int `db:"max_members"`
MemberEpoch int64 `db:"member_epoch"`
// CollaborationRoleEpoch orders statements about the project's collaboration-role
// catalog. Third counter on this row, same increment-only discipline (from #871).
CollaborationRoleEpoch int64 `db:"collaboration_role_epoch"`
// LifecycleVersion orders statements about the PROJECT — its name, its
// description, whether it is active. Deliberately separate from MemberEpoch,
// which orders statements about the ROSTER: one shared counter would make
// every rename invalidate every cached authorization decision downstream, and
// every membership change look like a lifecycle statement. They move at
// different rates for different reasons.
LifecycleVersion int64 `db:"lifecycle_version"`
Status int `db:"status"`
// ActivatedAt is the two-phase create latch: when the subsystem side
// confirmed this project has a container. NULL until it does, and the two
// peer-facing endpoints answer about a NULL row exactly as they answer about
// a project that does not exist.
//
// sql.NullTime rather than *time.Time, and the difference is not stylistic:
// dbr materializes a NULL column into a NON-NIL *time.Time at the zero time,
// so a pointer field would read as "activated in year zero" for every
// unconfirmed project and every `if m.ActivatedAt != nil` would be true. A
// test helper written the pointer way did exactly that before this comment
// existed. NullTime carries the NULL in a field of its own, outside the value
// domain — the same reason the epoch sentinel had to leave it.
ActivatedAt sql.NullTime `db:"activated_at"`
CreatedAt time.Time `db:"created_at"`
UpdatedAt time.Time `db:"updated_at"`
}
Model is an octo_project row.
Deliberately has NO ActiveName field. active_name is a STORED generated column, and MySQL rejects any INSERT/UPDATE that names it with error 3105. The DAO uses explicit column lists rather than util.AttrToUnderscore, so this is belt and braces rather than the only guard — but a struct field would make the failure reachable again the moment someone reaches for the reflective helper.
It likewise has no IsOfficial field: no P0 code path writes that column, and leaving it out of the model is what makes that checkable rather than aspirational.
type Project ¶
Project is the modules/project API.
func New ¶
New builds the Project API and registers the Space-removal cascade step.
The cascade is registered here, at construction, rather than in Route(): the very first thing createProject does is write an owner seat, so octo_project_member has active rows from the moment this module is loaded, and I1's reverse direction has to already exist by then.
func (*Project) CleanupSpaceMemberProjects ¶
func (p *Project) CleanupSpaceMemberProjects(ctx *config.Context, removal spacemod.MemberRemoval) error
cleanupSpaceMemberProjects closes every project seat a removed Space member still holds in that Space.
This is the ASYNCHRONOUS half of invariant I1, and it is asynchronous because the machinery is — not by choice. The work is enqueued in the Space-removal transaction but executed by a poller with a lease, exponential backoff and a terminal abandoned state. Between the Space removal committing and this step running, octo_project_member rows exist with status=1 and no active Space seat. That window is tolerated because the Space gate already denies access at commit: the seat grants nothing on its own, and the epoch moved synchronously.
The step closes Project seats ONLY. Native group membership is an independent fact — Space revocation still removes the member from the Space's groups through its own cascade, and closing a Project seat neither removes nor restores any group row.
Contract compliance (modules/space/member_removal.go:56-64):
- Idempotent. The status filter means a rerun finds no active row, affects zero rows, and therefore does NOT bump member_epoch a second time.
- Decides "nothing to do" itself and returns nil rather than erroring.
- Assumes nothing about the other registered steps.
- Self-limiting on failure. It shares the job with the group and conversation steps, and a step that keeps erroring keeps the whole job being re-claimed, burning lease cycles and crowding healthy removals out of each batch. So the only thing that returns an error here is a real database failure; everything else resolves to nil.
The membership predicate is CheckMembershipForCleanup, NOT CheckMembership, and the difference is load-bearing: they differ on exactly one axis — in a BANNED Space (status=2) the member still holds their seat, so cleanup must skip. A step written against CheckMembership would deactivate every project membership in a Space the moment it was banned, and un-banning would not restore them. CleanupSpaceMemberProjects is the registered step body, exported so the external test package can restore the real step after injecting a failing one (the registry is latest-wins, and a no-op left behind would silently disable the cascade for the rest of the test binary's run - yujiawei Q9, PR #841 round 1).
func (*Project) Route ¶
Route mounts the Project endpoints.
Two groups, and the middleware order within each is load-bearing:
- AuthMiddleware FIRST, then SharedUIDRateLimiter. Mounted the other way round the limiter cannot read the uid and silently fails open, i.e. the route looks rate-limited and is not. A "429 under load" test would pass either way, which is why the ordering is asserted structurally in api_i18n_test.go instead.
- then the Space/Project resolver, which is what actually confines the request to a tenant. pkg/space's SpaceMiddleware is NOT usable here: it reads only the `space_id` query parameter and the X-Space-ID header and PASSES when neither is present, so a path-parameter route mounted under it would be unguarded.
P0 mounts no unauthenticated route, so StrictIPRateLimitMiddleware has no place here; it arrives with the anonymous invite-preview endpoint (P2).
These routes are deliberately NOT contributed to any pkg/authtree tree — see the note added to that package's census.
type ProjectDisband ¶ added in v1.19.0
type ProjectDisband struct {
ProjectID string
SpaceID string
// ByCascade is true when automation disbanded the project, rather than a
// human choosing to. The current Space-removal cascade preserves the Owner
// row and does not use this branch.
ByCascade bool
}
ProjectDisband describes a project being disbanded, whether by a human request or by a future automated lifecycle worker.
type ProjectGroupRelation ¶ added in v1.19.0
type ProjectGroupRelation struct {
GroupNo string `json:"group_no" db:"group_no"`
Name string `json:"name" db:"name"`
ProjectID string `json:"project_id" db:"project_id"`
LinkedBy *string `json:"linked_by" db:"project_linked_by"`
Pinned bool `json:"pinned" db:"pinned"`
}
ProjectGroupRelation is the relation-only projection used by GET /v1/projects/:project_id/groups. It deliberately carries no native membership, ACL, or chat fields.
type ProvisioningConfig ¶ added in v1.19.0
type ProvisioningConfig struct {
// Targets is the enabled, VALIDATED set. A target named in
// OCTO_PROJECT_PROVISION_TARGETS but misconfigured is absent from here — see
// loadProvisioningConfig for why that is a dropped target plus a loud gauge
// rather than a refusal to boot.
Targets []provisionTarget
// Misconfigured holds the names of targets that were asked for and rejected,
// so the gauge can publish them and the reason is not log-only.
Misconfigured []string
// Problems carries one error per rejected target, for New() to log at
// construction. Kept on the struct rather than returned separately so
// loadConfig keeps its single-value signature; nothing reads it after boot.
Problems []error
Interval time.Duration
Timeout time.Duration
MaxAttempts uint32
BatchSize int
// ReclaimTargets is the set of target names whose reclaim consumer the operator has
// declared live, and it is the ONLY set whose disband_pending rows the purge may
// delete. See envProvision*ReclaimConsumerLive — with no consumer polling, purging a
// disband_pending row makes its container permanently un-reclaimable.
//
// Deliberately NOT a subset of Targets: enablement governs what we create, this governs
// what we may forget, and a target disabled after use still has containers to reclaim.
ReclaimTargets []string
// RequeueProjectID is the project whose abandoned rows are re-driven at boot, or
// empty. See envProvisionRequeueProjectID for why this is boot-time and why a
// leftover value is safe.
RequeueProjectID string
}
ProvisioningConfig is the resolved per-process provisioning configuration. It holds credentials. Nothing in this package logs or serializes it, and nothing should start: a %+v of this struct in a log line would publish either Fleet's HMAC secret or Drive's internal token. The provisioning worker logs target NAMES only.
func (ProvisioningConfig) Enabled ¶ added in v1.19.0
func (c ProvisioningConfig) Enabled() bool
Enabled reports whether any target is live. When false, createProjectOnce enqueues nothing and the worker does not start.
NOT completely inert, and the exception is deliberate rather than an oversight: markProvisioningDisbandPendingTx runs UNCONDITIONALLY on the disband path. Gating that on Enabled() would mean a target that was enabled, produced rows, and was later disabled stops marking its containers reclaimable — a real leak, with no local record that anything was left behind.
This comment is what a future reader consults immediately before "tidying up" by adding that gate, so it says so here rather than only in the runbook.
func (ProvisioningConfig) TargetByName ¶ added in v1.19.0
func (c ProvisioningConfig) TargetByName(name string) (provisionTarget, bool)
TargetByName returns the resolved target, or false when it is not enabled.
type RemovalJob ¶ added in v1.19.0
type RemovalJob struct {
ID int64 `db:"id"`
ProjectID string `db:"project_id"`
UID string `db:"uid"`
SpaceID string `db:"space_id"`
OperatorUID string `db:"operator_uid"`
Reason string `db:"reason"`
Status int `db:"status"`
Attempts int `db:"attempts"`
CreatedAt time.Time `db:"created_at"`
}
RemovalJob is one unit of project-side cleanup.
type Resp ¶
type Resp struct {
ProjectID string `json:"project_id"`
SpaceID string `json:"space_id"`
Name string `json:"name"`
Description string `json:"description"`
Logo string `json:"logo"`
Creator string `json:"creator"`
Discoverability int `json:"discoverability"`
MaxMembers int `json:"max_members"`
// MemberCount is EVERY active seat, humans and agents together — the same
// meaning it had before D16, and the same meaning `member_count` carries in
// modules/opanalytics. The split lives in the two fields below.
//
// D16 first shipped this as "humans only", on the argument that a project with
// one person and two of their agents rendering as "3 人" is a sentence no user
// reads as true. That argument is right about what a client should DISPLAY and
// wrong about which field should change: the display fix is for the client to
// render HumanMemberCount. Redefining member_count bought the same outcome at
// the price of one server meaning two things by one name —
// modules/opanalytics' channel list already ships member_count as the total,
// beside human_member_count and agent_member_count, to the same client teams.
//
// Restored while it is still free, and the reason is checkable from the tags
// rather than from a claim about GA. v1.18.0 (2026-09-07) already ships this
// field from countActiveMembers -- the TOTAL. The humans-only redefinition
// landed in 566e625, which `git tag --contains` places on no release. So this
// restores the meaning that IS released and retires the one that never was: a
// v1.18.0 client sees no change at all, and only a client built against two
// days of unreleased main renames a field.
//
// The earlier version of this comment said the module "has never been GA, so
// nothing had shipped against either meaning". That was wrong -- v1.18.0
// carries 42 files under modules/project -- and it was the weaker argument
// besides. PR #868's fifth review, which checked the tags instead of taking
// the sentence. This is the sentence a future wire change will cite, so it
// needs to rest on something measurable.
//
// The quota (MaxMembers) bounds this number, agents included — an agent reads
// the project's messages, so it costs a seat.
MemberCount int `json:"member_count"`
// HumanMemberCount counts human members only. This is what a roster header
// should render.
HumanMemberCount int `json:"human_member_count"`
// AgentMemberCount counts active AI agent seats.
//
// Named for opanalytics' field rather than the shorter `agent_count`, which is
// already taken on the wire by the Space directory, where it means "how many
// agents this OWNER has" — a different question with the same short name.
AgentMemberCount int `json:"agent_member_count"`
MemberEpoch int64 `json:"member_epoch"`
CollaborationRoleEpoch int64 `json:"collaboration_role_epoch"`
Status int `json:"status"`
// Pinned is the CALLER's own pin, not a property of the project: the same
// project reads true for one user and false for the next. It is on the list
// AND the detail route, because a field present on one and absent on the other
// makes the two disagree about the same project.
Pinned bool `json:"pinned"`
// MyRole is the caller's project role, or -1 when the caller is not a member
// (a Space admin reading a project they have not joined).
MyRole int `json:"my_role"`
Capabilities Capabilities `json:"capabilities"`
CreatedAt string `json:"created_at"`
UpdatedAt string `json:"updated_at"`
}
Resp is the Project payload returned by list and detail.
MemberEpoch ships here and nowhere else in P0 (D3): first-party clients get it next to my_role and the capability bits, but no machine-to-machine endpoint exposes it. This repo has already built "an endpoint and waited for a consumer" twice, and the eventual subsystem channel is verify?include=context, not a new route.
Capabilities are emitted as explicit booleans rather than left for the client to derive from MyRole. A client that computes permissions from a role number re-implements the server's permission matrix, and the two drift the first time the matrix changes.
type SidebarSectionProvisioner ¶ added in v1.19.0
SidebarSectionProvisioner creates one user's personal Project section after a Project seat or personal pin commits. category registers the implementation so project stays independent of category and no import cycle is introduced.
type SidebarSectionRemover ¶ added in v1.19.0
SidebarSectionRemover hides one user's personal Project section after an explicit unpin. Keeping this separate from provisioning makes the two user intents visible at call sites and avoids teaching project about category's storage table.
Source Files
¶
- 1module.go
- activation.go
- api.go
- api_bot_read.go
- api_collaboration_role.go
- api_group.go
- api_i18n.go
- api_member.go
- api_member_candidates.go
- api_read.go
- api_setting.go
- audit.go
- cascade_registry.go
- collaboration_role_maintenance.go
- config.go
- config_provisioning.go
- db.go
- db_agent.go
- db_collaboration_role.go
- db_group.go
- db_group_pin.go
- db_lifecycle_event.go
- db_member_candidates.go
- db_provisioning.go
- db_read.go
- db_removal.go
- db_user_setting.go
- group_access.go
- lifecycle_client.go
- lifecycle_event.go
- lifecycle_event_worker.go
- metrics.go
- metrics_collect.go
- metrics_provisioning.go
- middleware.go
- model.go
- model_member_candidates.go
- model_read.go
- projectid.go
- provisioning.go
- provisioning_worker.go
- reconcile.go
- reconcile_p1.go
- removal_worker.go
- service.go
- service_agent.go
- service_collaboration_role.go
- service_group_pin.go
- service_member_candidates.go
- service_member_list.go
- service_read.go
- sidebar_section_registry.go
- space_member_removal.go
- utcread.go