FlowyLabs/llink
1
0
Fork 0
Code Issues 71 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

refactor: agentic comment cleanup

Browse Source
This commit is contained in:
talksik
2026-05-18 10:52:37 -07:00
parent 6f476fe773
commit 4421b8e832
45 changed files with 269 additions and 545 deletions
Download Patch File Download Diff File Expand all files Collapse all files
go/internal/particle/models.go
+4 -23
View File
@@ -6,7 +6,6 @@ import (
"time"
)
// ParticleType represents the type of particle
type ParticleType string
const (
@@ -20,7 +19,6 @@ const (
// TypeThink ParticleType = "think"
)
// VisibilityMode represents how access to a particle is determined
type VisibilityMode string
const (
@@ -32,7 +30,6 @@ const (
var ErrInvalidParticleType = errors.New("invalid particle type")
var ErrInvalidVisibilityMode = errors.New("invalid visibility mode")
// ParseParticleType parses a string into a ParticleType
func ParseParticleType(s string) (ParticleType, error) {
switch s {
case string(TypeStream):
@@ -54,7 +51,6 @@ func ParseParticleType(s string) (ParticleType, error) {
}
}
// ParseVisibilityMode parses a string into a VisibilityMode
func ParseVisibilityMode(s string) (VisibilityMode, error) {
switch s {
case "", string(VisibilityNetworkAll):
@@ -68,7 +64,6 @@ func ParseVisibilityMode(s string) (VisibilityMode, error) {
}
}
// Stream status values
type StreamStatus string
const (
@@ -76,7 +71,6 @@ const (
StreamStatusClosed StreamStatus = "closed"
)
// Particle represents a content particle in the system
type Particle struct {
ID string
Type ParticleType
@@ -89,7 +83,6 @@ type Particle struct {
CreatedAt time.Time
}
// CreateInput represents the input for creating a new particle
type CreateInput struct {
Type ParticleType
NetworkID string
@@ -99,18 +92,15 @@ type CreateInput struct {
Visibility VisibilityMode
}
// ListFilter represents filtering options for listing particles
type ListFilter struct {
Types []ParticleType
}
// Cursor represents a pagination cursor for bidirectional pagination
type Cursor struct {
Position string // particle ID or timestamp
Direction string // "before" or "after"
}
// ParticleList represents a paginated list of particles
type ParticleList struct {
Particles []*Particle
HasMore bool
@@ -118,57 +108,48 @@ type ParticleList struct {
PrevCursor *Cursor
}
// StreamData represents the data stored for stream particles
type StreamData struct {
Name string `json:"name"`
Status string `json:"status"` // "open" or "closed"
Description *string `json:"description"`
}
// FolderData represents the data stored for folder particles
type FolderData struct {
Name string `json:"name"`
Color *string `json:"color"`
}
// MediaData represents the data stored for media particles
type MediaData struct {
ObjectID string `json:"object_id"` // reference to storage object
ObjectID string `json:"object_id"`
MimeType string `json:"mime_type"`
DurationMs int `json:"duration_ms"`
// Caption *string `json:"caption"`
}
// FileData represents the data stored for file particles
type FileData struct {
ObjectID string `json:"object_id"` // reference to storage object
ObjectID string `json:"object_id"`
Filename string `json:"filename"`
MimeType string `json:"mime_type"`
Size int64 `json:"size"` // in bytes
Size int64 `json:"size"` // bytes
}
// TextData represents the data stored for text particles
type TextData struct {
Content string `json:"content"`
}
// QuestData represents the data stored for quest particles
type QuestData struct {
Title string `json:"title"`
Description string `json:"description"`
Done bool `json:"done"`
Status *string `json:"status"`
AssignedTo *string `json:"assigned_to,omitempty"` // email
DueDate *string `json:"due_date,omitempty"` // ISO date string
DueDate *string `json:"due_date,omitempty"` // ISO date
}
// PaperData represents the data stored for paper particles
type PaperData struct {
Title string `json:"title"`
Content string `json:"content"` // markdown
}
// AckInfo represents an acknowledgment record
type AckInfo struct {
Email string
AckedAt time.Time
go/internal/particle/networkmembershipchecker.go
-1
View File
@@ -5,6 +5,5 @@ import "context"
//go:generate go tool mockgen -source ./networkmembershipchecker.go -destination ./mocks/networkmembershipchecker.go
type NetworkMembershipChecker interface {
// IsMember returns true if the humanId is a member of the network.
IsMember(ctx context.Context, networkID, humanId string) (bool, error)
}
go/internal/particle/repository.go
+1 -1
View File
@@ -40,7 +40,7 @@ type repository interface {
getMembers(ctx context.Context, particleID string) ([]string, error)
getMembersMap(ctx context.Context, particleIDs []string) (map[string][]string, error)
// getAncestorChain returns the particle and all its ancestors (for access checks)
// getAncestorChain returns the particle followed by its ancestors, in order.
getAncestorChain(ctx context.Context, particleID string) ([]*Particle, error)
isMemberOf(ctx context.Context, particleID, email string) (bool, error)
go/internal/particle/service.go
+39 -82
View File
@@ -13,45 +13,46 @@ import (
const defaultPageSize = 50
// NOTE: this service is deprecated as we use firestore for particle data
// Deprecated: particle data now lives in Firestore. The Postgres-backed
// service is retained only for legacy paths.
type Service interface {
// Create creates a new particle. Caller must be a network member (verified by handler).
// Returns ErrInvalidType, ErrInvalidData, ErrMembersRequired, ErrInvalidParent, ErrAccessDenied, or ErrCapacityExceeded.
// Create returns ErrInvalidType, ErrInvalidData, ErrMembersRequired,
// ErrInvalidParent, ErrAccessDenied, or ErrCapacityExceeded. Network
// membership is verified by the handler.
Create(ctx context.Context, input CreateInput, requesterEmail string) (*Particle, error)
// GetByID returns ErrNotFound or ErrAccessDenied.
GetByID(ctx context.Context, id, requesterEmail string) (*Particle, error)
// Update updates the particle's data. Returns ErrNotFound, ErrAccessDenied, or ErrInvalidData.
// Update returns ErrNotFound, ErrAccessDenied, or ErrInvalidData.
Update(ctx context.Context, id string, data json.RawMessage, requesterEmail string) (*Particle, error)
// Delete returns ErrNotFound or ErrAccessDenied.
Delete(ctx context.Context, id, requesterEmail string) error
// List returns particles in a network. Use parentID=nil for root particles.
// Returns ErrNotFound or ErrAccessDenied if parentID is specified and inaccessible.
// List uses parentID=nil for root particles. Returns ErrNotFound or
// ErrAccessDenied when parentID is given but inaccessible.
List(ctx context.Context, networkID string, parentID *string, requesterEmail string, filter ListFilter, cursor *Cursor, limit int) (*ParticleList, error)
// OpenStream opens a closed stream. Returns ErrNotFound, ErrAccessDenied, ErrNotAStream, ErrStreamAlreadyOpen, or ErrCapacityExceeded.
// OpenStream returns ErrNotFound, ErrAccessDenied, ErrNotAStream,
// ErrStreamAlreadyOpen, or ErrCapacityExceeded.
OpenStream(ctx context.Context, id, requesterEmail string) error
// CloseStream closes an open stream. Returns ErrNotFound, ErrAccessDenied, ErrNotAStream, or ErrStreamAlreadyClosed.
// CloseStream returns ErrNotFound, ErrAccessDenied, ErrNotAStream, or
// ErrStreamAlreadyClosed.
CloseStream(ctx context.Context, id, requesterEmail string) error
// SetVisibility changes the particle's visibility mode. Returns ErrNotFound, ErrAccessDenied, or ErrAccessExpansion.
// SetVisibility returns ErrNotFound, ErrAccessDenied, or ErrAccessExpansion.
SetVisibility(ctx context.Context, id string, mode VisibilityMode, requesterEmail string) error
// AddMembers adds members to a custom visibility particle. Returns ErrNotFound or ErrAccessDenied.
// AddMembers / RemoveMembers operate on custom-visibility streams only.
// Both return ErrNotFound or ErrAccessDenied.
AddMembers(ctx context.Context, id string, emails []string, requesterEmail string) error
// RemoveMembers removes members from a custom visibility particle. Returns ErrNotFound or ErrAccessDenied.
RemoveMembers(ctx context.Context, id string, emails []string, requesterEmail string) error
// Seen tracking (private)
// Seen tracking is private per human; Ack is public and permanent.
MarkSeen(ctx context.Context, id, requesterEmail string) error
MarkSeenBatch(ctx context.Context, ids []string, requesterEmail string) error
// Ack tracking (public, permanent)
Ack(ctx context.Context, id, requesterEmail string) error
// Unseen counts for stream list view
GetUnseenCounts(ctx context.Context, networkID string, streamIDs []string, requesterEmail string) (map[string]int, error)
// Bulk lookups for handler enrichment
// Bulk lookups for batch hydration.
GetSeenMap(ctx context.Context, particleIDs []string, requesterEmail string) (map[string]bool, error)
GetAcksMap(ctx context.Context, particleIDs []string) (map[string][]AckInfo, error)
GetMembersMap(ctx context.Context, particleIDs []string) (map[string][]string, error)
@@ -69,10 +70,9 @@ func NewService(pool *pgxpool.Pool, networkReader NetworkMembershipChecker) Serv
}
}
// checkAccess verifies that the email has access to the particle based on visibility.
// Assumes the caller is already verified as a network member (handler responsibility).
// Walks up the ancestor chain only when visibility is inherited, stopping at the first
// network_all or custom node.
// Walks the ancestor chain when visibility is inherited, stopping at the
// first network_all or custom node. Assumes network membership is already
// verified by the handler.
func (s *serviceImpl) checkAccess(ctx context.Context, particleID, email string) (bool, error) {
ancestors, err := s.repo.getAncestorChain(ctx, particleID)
if err != nil {
@@ -83,13 +83,12 @@ func (s *serviceImpl) checkAccess(ctx context.Context, particleID, email string)
return false, errNotFound
}
// Build lookup map by ID
byID := make(map[string]*Particle, len(ancestors))
for _, p := range ancestors {
byID[p.ID] = p
}
// Start from the target particle (first in chain) and walk up on inherited
// ancestors[0] is the target; walk up only on inherited.
current := ancestors[0]
for {
switch current.Visibility {
@@ -99,7 +98,7 @@ func (s *serviceImpl) checkAccess(ctx context.Context, particleID, email string)
return s.repo.isMemberOf(ctx, current.ID, email)
case VisibilityInherited:
if current.ParentID == nil {
// inherited at root is invalid state, deny access
// inherited-at-root is invalid; deny.
return false, nil
}
parent, ok := byID[*current.ParentID]
@@ -119,30 +118,24 @@ func (s *serviceImpl) Create(ctx context.Context, input CreateInput, requesterEm
return nil, err
}
// Validate particle type
if !isValidParticleType(input.Type) {
return nil, ErrInvalidType
}
// Validate data matches type requirements
if err := validateParticleData(input.Type, input.Data); err != nil {
return nil, err
}
// MVP visibility rules:
// - Child particles (have parent) → always inherited
// - Root particles (no parent) → cannot be inherited, default network_all
// MVP visibility: children always inherit; roots cannot inherit and
// default to network_all. Streams/folders are root-only.
if input.ParentID != nil {
// Children always inherit from parent
input.Visibility = VisibilityInherited
input.Members = nil // no members on inherited particles
input.Members = nil
// Reject streams and folders as children (MVP: streams are root-level only)
if input.Type == TypeStream || input.Type == TypeFolder {
return nil, ErrInvalidParent
}
} else {
// Root particles cannot be inherited
if input.Visibility == VisibilityInherited {
return nil, ErrInheritedAtRoot
}
@@ -151,7 +144,6 @@ func (s *serviceImpl) Create(ctx context.Context, input CreateInput, requesterEm
}
}
// Custom visibility requires at least one member and must be a stream
var customMembers []string
if input.Visibility == VisibilityCustom {
if input.Type != TypeStream {
@@ -161,7 +153,7 @@ func (s *serviceImpl) Create(ctx context.Context, input CreateInput, requesterEm
return nil, ErrMembersRequired
}
// Validate every supplied member against the network checker before touching the DB.
// Validate every member upfront so DB writes are all-or-nothing.
customMembers = make([]string, 0, len(input.Members)+1)
customMembers = append(customMembers, requesterEmail)
seen := map[string]bool{requesterEmail: true}
@@ -186,8 +178,7 @@ func (s *serviceImpl) Create(ctx context.Context, input CreateInput, requesterEm
}
}
// Network membership is verified by handler - we only check particle visibility
// If parent specified, check parent access (visibility-based)
// Network membership is verified by the handler; only particle visibility is checked here.
if input.ParentID != nil {
hasAccess, err := s.checkAccess(ctx, *input.ParentID, requesterEmail)
if err != nil {
@@ -201,7 +192,6 @@ func (s *serviceImpl) Create(ctx context.Context, input CreateInput, requesterEm
}
}
// Build the particle
p := &Particle{
Type: input.Type,
NetworkID: input.NetworkID,
@@ -215,9 +205,8 @@ func (s *serviceImpl) Create(ctx context.Context, input CreateInput, requesterEm
p.Data = json.RawMessage("{}")
}
// For streams, set initial status to open and check capacity
// New streams default to open.
if input.Type == TypeStream {
// Set status to open in the data JSON
data, err := setStreamStatus(p.Data, string(StreamStatusOpen))
if err != nil {
return nil, err
@@ -225,13 +214,11 @@ func (s *serviceImpl) Create(ctx context.Context, input CreateInput, requesterEm
p.Data = data
}
// Create the particle
created, err := s.repo.create(ctx, p)
if err != nil {
return nil, err
}
// Add the pre-validated member list for custom visibility.
if len(customMembers) > 0 {
if err := s.repo.addMembers(ctx, created.ID, customMembers); err != nil {
return nil, err
@@ -247,7 +234,6 @@ func (s *serviceImpl) GetByID(ctx context.Context, id, requesterEmail string) (*
return nil, err
}
// Check access
hasAccess, err := s.checkAccess(ctx, id, requesterEmail)
if err != nil {
if errors.Is(err, errNotFound) {
@@ -275,7 +261,6 @@ func (s *serviceImpl) Update(ctx context.Context, id string, data json.RawMessag
return nil, err
}
// Check access
hasAccess, err := s.checkAccess(ctx, id, requesterEmail)
if err != nil {
if errors.Is(err, errNotFound) {
@@ -287,7 +272,6 @@ func (s *serviceImpl) Update(ctx context.Context, id string, data json.RawMessag
return nil, ErrAccessDenied
}
// Get the particle to validate data against its type
p, err := s.repo.getByID(ctx, id)
if err != nil {
if errors.Is(err, errNotFound) {
@@ -296,7 +280,6 @@ func (s *serviceImpl) Update(ctx context.Context, id string, data json.RawMessag
return nil, err
}
// Validate data matches type requirements
if err := validateParticleData(p.Type, data); err != nil {
return nil, err
}
@@ -318,7 +301,6 @@ func (s *serviceImpl) Delete(ctx context.Context, id, requesterEmail string) err
return err
}
// Check access
hasAccess, err := s.checkAccess(ctx, id, requesterEmail)
if err != nil {
if errors.Is(err, errNotFound) {
@@ -330,7 +312,6 @@ func (s *serviceImpl) Delete(ctx context.Context, id, requesterEmail string) err
return ErrAccessDenied
}
// Get the particle to check if it's an open stream
_, err = s.repo.getByID(ctx, id)
if err != nil {
if errors.Is(err, errNotFound) {
@@ -352,8 +333,7 @@ func (s *serviceImpl) List(ctx context.Context, networkID string, parentID *stri
return nil, err
}
// Network membership is verified by handler - we only check particle visibility
// If parentID specified, check access to parent (visibility-based)
// Network membership is verified by the handler; only particle visibility is checked here.
if parentID != nil {
hasAccess, err := s.checkAccess(ctx, *parentID, requesterEmail)
if err != nil {
@@ -367,8 +347,7 @@ func (s *serviceImpl) List(ctx context.Context, networkID string, parentID *stri
}
}
// Fetch one extra to determine if there are more
// Access filtering is done in the query itself (network_all OR user is member)
// Fetch limit+1 to detect a next page; visibility filtering lives in the query.
if limit == 0 {
limit = defaultPageSize
}
@@ -415,7 +394,6 @@ func (s *serviceImpl) OpenStream(ctx context.Context, id, requesterEmail string)
return err
}
// Check access
hasAccess, err := s.checkAccess(ctx, id, requesterEmail)
if err != nil {
if errors.Is(err, errNotFound) {
@@ -427,7 +405,6 @@ func (s *serviceImpl) OpenStream(ctx context.Context, id, requesterEmail string)
return ErrAccessDenied
}
// Get the particle
p, err := s.repo.getByID(ctx, id)
if err != nil {
if errors.Is(err, errNotFound) {
@@ -444,7 +421,6 @@ func (s *serviceImpl) OpenStream(ctx context.Context, id, requesterEmail string)
return ErrStreamAlreadyOpen
}
// Update stream status in data
newData, err := setStreamStatus(p.Data, string(StreamStatusOpen))
if err != nil {
return err
@@ -467,7 +443,6 @@ func (s *serviceImpl) CloseStream(ctx context.Context, id, requesterEmail string
return err
}
// Check access
hasAccess, err := s.checkAccess(ctx, id, requesterEmail)
if err != nil {
if errors.Is(err, errNotFound) {
@@ -479,7 +454,6 @@ func (s *serviceImpl) CloseStream(ctx context.Context, id, requesterEmail string
return ErrAccessDenied
}
// Get the particle
p, err := s.repo.getByID(ctx, id)
if err != nil {
if errors.Is(err, errNotFound) {
@@ -496,7 +470,6 @@ func (s *serviceImpl) CloseStream(ctx context.Context, id, requesterEmail string
return ErrStreamAlreadyClosed
}
// Update stream status in data
newData, err := setStreamStatus(p.Data, string(StreamStatusClosed))
if err != nil {
return err
@@ -519,7 +492,6 @@ func (s *serviceImpl) SetVisibility(ctx context.Context, id string, mode Visibil
return err
}
// Check access
hasAccess, err := s.checkAccess(ctx, id, requesterEmail)
if err != nil {
if errors.Is(err, errNotFound) {
@@ -531,7 +503,6 @@ func (s *serviceImpl) SetVisibility(ctx context.Context, id string, mode Visibil
return ErrAccessDenied
}
// Get the particle to check constraints
p, err := s.repo.getByID(ctx, id)
if err != nil {
if errors.Is(err, errNotFound) {
@@ -540,12 +511,11 @@ func (s *serviceImpl) SetVisibility(ctx context.Context, id string, mode Visibil
return err
}
// Root particles cannot be inherited
if mode == VisibilityInherited && p.ParentID == nil {
return ErrInheritedAtRoot
}
// If expanding to network_all, check that parent's effective visibility allows it
// Expanding to network_all is rejected if any ancestor restricts to custom.
if mode == VisibilityNetworkAll && p.ParentID != nil {
parentVis, err := s.getEffectiveVisibility(ctx, *p.ParentID)
if err != nil {
@@ -563,7 +533,7 @@ func (s *serviceImpl) SetVisibility(ctx context.Context, id string, mode Visibil
return err
}
// getEffectiveVisibility walks up the inherited chain to find the concrete visibility mode.
// Walks up the inherited chain to the concrete visibility node.
func (s *serviceImpl) getEffectiveVisibility(ctx context.Context, particleID string) (VisibilityMode, error) {
ancestors, err := s.repo.getAncestorChain(ctx, particleID)
if err != nil {
@@ -600,7 +570,6 @@ func (s *serviceImpl) AddMembers(ctx context.Context, id string, emails []string
return err
}
// Check access
hasAccess, err := s.checkAccess(ctx, id, requesterEmail)
if err != nil {
if errors.Is(err, errNotFound) {
@@ -612,7 +581,6 @@ func (s *serviceImpl) AddMembers(ctx context.Context, id string, emails []string
return ErrAccessDenied
}
// Get the particle to check type and parent access
p, err := s.repo.getByID(ctx, id)
if err != nil {
if errors.Is(err, errNotFound) {
@@ -621,14 +589,11 @@ func (s *serviceImpl) AddMembers(ctx context.Context, id string, emails []string
return err
}
// Only streams can have members
if p.Type != TypeStream {
return ErrNotAContainer
}
// Validate and normalize emails, checking network membership upfront.
// Strict: a normalize failure, checker error, or non-member aborts the
// whole operation before any rows are written.
// Validate every email upfront so any failure aborts before DB writes.
normalizedEmails := make([]string, 0, len(emails))
seen := make(map[string]bool, len(emails))
for _, email := range emails {
@@ -664,7 +629,6 @@ func (s *serviceImpl) RemoveMembers(ctx context.Context, id string, emails []str
return err
}
// Check access
hasAccess, err := s.checkAccess(ctx, id, requesterEmail)
if err != nil {
if errors.Is(err, errNotFound) {
@@ -676,7 +640,6 @@ func (s *serviceImpl) RemoveMembers(ctx context.Context, id string, emails []str
return ErrAccessDenied
}
// Get the particle to check type
p, err := s.repo.getByID(ctx, id)
if err != nil {
if errors.Is(err, errNotFound) {
@@ -685,7 +648,6 @@ func (s *serviceImpl) RemoveMembers(ctx context.Context, id string, emails []str
return err
}
// Only streams can have members
if p.Type != TypeStream {
return ErrNotAContainer
}
@@ -712,7 +674,6 @@ func (s *serviceImpl) MarkSeen(ctx context.Context, id, requesterEmail string) e
return err
}
// Check access
hasAccess, err := s.checkAccess(ctx, id, requesterEmail)
if err != nil {
if errors.Is(err, errNotFound) {
@@ -733,17 +694,17 @@ func (s *serviceImpl) MarkSeenBatch(ctx context.Context, ids []string, requester
return err
}
// Check access for each particle and mark seen
// Silently skip particles that are missing or inaccessible.
for _, id := range ids {
hasAccess, err := s.checkAccess(ctx, id, requesterEmail)
if err != nil {
if errors.Is(err, errNotFound) {
continue // Skip non-existent particles
continue
}
return err
}
if !hasAccess {
continue // Skip inaccessible particles
continue
}
if err := s.repo.markSeen(ctx, id, requesterEmail); err != nil {
@@ -760,7 +721,6 @@ func (s *serviceImpl) Ack(ctx context.Context, id, requesterEmail string) error
return err
}
// Check access
hasAccess, err := s.checkAccess(ctx, id, requesterEmail)
if err != nil {
if errors.Is(err, errNotFound) {
@@ -772,7 +732,7 @@ func (s *serviceImpl) Ack(ctx context.Context, id, requesterEmail string) error
return ErrAccessDenied
}
// Ack also marks as seen
// Ack implies seen.
if err := s.repo.markSeen(ctx, id, requesterEmail); err != nil {
return err
}
@@ -815,7 +775,6 @@ func isValidParticleType(t ParticleType) bool {
}
}
// getStreamStatus extracts the status from a stream particle's data
func getStreamStatus(data json.RawMessage) string {
var d StreamData
if err := json.Unmarshal(data, &d); err != nil {
@@ -824,7 +783,6 @@ func getStreamStatus(data json.RawMessage) string {
return d.Status
}
// setStreamStatus updates the status in a stream particle's data
func setStreamStatus(data json.RawMessage, status string) (json.RawMessage, error) {
var d StreamData
if err := json.Unmarshal(data, &d); err != nil {
@@ -834,10 +792,9 @@ func setStreamStatus(data json.RawMessage, status string) (json.RawMessage, erro
return json.Marshal(d)
}
// validateParticleData validates that the data field contains valid JSON
// and has required fields for the given particle type.
// Returns ErrInvalidData if data is not valid JSON or is missing required
// fields for pType. Empty/null data is allowed and treated as {}.
func validateParticleData(pType ParticleType, data json.RawMessage) error {
// Empty or null data is allowed - will default to {}
if len(data) == 0 || string(data) == "null" || string(data) == "{}" {
return nil
}