Skip to main content

files

import "github.com/Ask-Atlas/AskAtlas/api/internal/files"

Package files contains the business logic, models, and data access layer for managing uploaded files.

Index​

Constants​

const (
    SortFieldUpdatedAt SortField = "updated_at"
    SortFieldCreatedAt SortField = "created_at"
    SortFieldName      SortField = "name"
    SortFieldSize      SortField = "size"
    SortFieldStatus    SortField = "status"
    SortFieldMimeType  SortField = "mime_type"

    SortDirAsc  SortDir = "asc"
    SortDirDesc SortDir = "desc"

    ScopeOwned      FileScope = "owned"
    ScopeCourse     FileScope = "course"
    ScopeStudyGuide FileScope = "study_guide"
    ScopeAccessible FileScope = "accessible"
)

func EncodeCursor​

func EncodeCursor(c Cursor) (string, error)

EncodeCursor serializes a Cursor struct into a base64-encoded string token.

type CreateFileParams​

CreateFileParams contains the validated inputs for creating a new file reference.

type CreateFileParams struct {
    UserID   uuid.UUID
    Name     string
    MimeType string
    Size     int64
}

type CreateFileResult​

CreateFileResult holds the created file record and the presigned upload URL.

type CreateFileResult struct {
    File      File
    UploadURL string
}

type CreateGrantParams​

CreateGrantParams holds the validated inputs for creating a file grant.

type CreateGrantParams struct {
    FileID      uuid.UUID
    OwnerID     uuid.UUID
    GranteeType string
    GranteeID   uuid.UUID
    Permission  string
}

type Cursor​

Cursor is the opaque pagination token. Only the field matching the active SortField is populated; all others are nil.

type Cursor struct {
    ID        uuid.UUID  `json:"id"`
    UpdatedAt *time.Time `json:"updated_at,omitempty"`
    CreatedAt *time.Time `json:"created_at,omitempty"`
    NameLower *string    `json:"name_lower,omitempty"`
    Size      *int64     `json:"size,omitempty"`
    Status    *string    `json:"status,omitempty"`
    MimeType  *string    `json:"mime_type,omitempty"`
}

func DecodeCursor​

func DecodeCursor(s string) (Cursor, error)

DecodeCursor parses a base64-encoded string token back into a Cursor struct.

type DeleteFileParams​

DeleteFileParams holds the inputs required to initiate file deletion.

type DeleteFileParams struct {
    FileID  uuid.UUID
    OwnerID uuid.UUID
}

type File​

File represents an uploaded file managed by the system.

type File struct {
    ID           uuid.UUID
    UserID       uuid.UUID
    Name         string
    Size         int64
    MimeType     string
    Status       string
    CreatedAt    time.Time
    UpdatedAt    time.Time
    FavoritedAt  *time.Time
    LastViewedAt *time.Time
}

type FileScope​

FileScope represents the visibility bounds of a file query.

type FileScope string

type GetFileParams​

GetFileParams contains the required inputs for fetching a single file.

type GetFileParams struct {
    ViewerID      uuid.UUID
    FileID        uuid.UUID
    CourseIDs     []uuid.UUID
    StudyGuideIDs []uuid.UUID
}

type Grant​

Grant represents a permission granted on a file to a specific grantee.

type Grant struct {
    ID          uuid.UUID
    FileID      uuid.UUID
    GranteeType string
    GranteeID   uuid.UUID
    Permission  string
    GrantedBy   uuid.UUID
    CreatedAt   time.Time
}

type ListFilesParams​

ListFilesParams is the fully validated input to Service.ListFiles.

type ListFilesParams struct {
    ViewerID      uuid.UUID
    OwnerID       uuid.UUID
    CourseIDs     []uuid.UUID
    StudyGuideIDs []uuid.UUID
    Scope         FileScope

    Status      *string
    MimeType    *string
    MinSize     *int64
    MaxSize     *int64
    CreatedFrom *time.Time
    CreatedTo   *time.Time
    UpdatedFrom *time.Time
    UpdatedTo   *time.Time
    Q           *string

    SortField SortField
    SortDir   SortDir
    PageLimit int
    Cursor    *Cursor
}

type QStashPublisher​

QStashPublisher is the interface the service uses to publish async jobs. Allows the concrete qstashclient.Client to be swapped for a test double.

type QStashPublisher interface {
    PublishDeleteFile(ctx context.Context, msg qstashclient.DeleteFileMessage) (string, error)
}

type Repository​

Repository defines the data-access interface required by the files Service.

type Repository interface {
    InTx(ctx context.Context, fn func(Repository) error) error

    InsertFile(ctx context.Context, arg db.InsertFileParams) (db.File, error)
    UpdateFileStatus(ctx context.Context, arg db.UpdateFileStatusParams) error
    GetFileIfViewable(ctx context.Context, arg db.GetFileIfViewableParams) (db.File, error)
    GetFileByOwner(ctx context.Context, arg db.GetFileByOwnerParams) (db.GetFileByOwnerRow, error)
    SoftDeleteFile(ctx context.Context, arg db.SoftDeleteFileParams) (int64, error)
    SetFileDeletionJobID(ctx context.Context, arg db.SetFileDeletionJobIDParams) error
    MarkFileDeleted(ctx context.Context, fileID pgtype.UUID) error
    UpdateFile(ctx context.Context, arg db.UpdateFileParams) (db.UpdateFileRow, error)

    UpsertFileGrant(ctx context.Context, arg db.UpsertFileGrantParams) (db.FileGrant, error)
    RevokeFileGrant(ctx context.Context, arg db.RevokeFileGrantParams) error

    ListOwnedFilesUpdatedDesc(ctx context.Context, arg db.ListOwnedFilesUpdatedDescParams) ([]db.ListOwnedFilesUpdatedDescRow, error)
    ListOwnedFilesUpdatedAsc(ctx context.Context, arg db.ListOwnedFilesUpdatedAscParams) ([]db.ListOwnedFilesUpdatedAscRow, error)
    ListOwnedFilesCreatedDesc(ctx context.Context, arg db.ListOwnedFilesCreatedDescParams) ([]db.ListOwnedFilesCreatedDescRow, error)
    ListOwnedFilesCreatedAsc(ctx context.Context, arg db.ListOwnedFilesCreatedAscParams) ([]db.ListOwnedFilesCreatedAscRow, error)
    ListOwnedFilesNameAsc(ctx context.Context, arg db.ListOwnedFilesNameAscParams) ([]db.ListOwnedFilesNameAscRow, error)
    ListOwnedFilesNameDesc(ctx context.Context, arg db.ListOwnedFilesNameDescParams) ([]db.ListOwnedFilesNameDescRow, error)
    ListOwnedFilesSizeAsc(ctx context.Context, arg db.ListOwnedFilesSizeAscParams) ([]db.ListOwnedFilesSizeAscRow, error)
    ListOwnedFilesSizeDesc(ctx context.Context, arg db.ListOwnedFilesSizeDescParams) ([]db.ListOwnedFilesSizeDescRow, error)
    ListOwnedFilesStatusAsc(ctx context.Context, arg db.ListOwnedFilesStatusAscParams) ([]db.ListOwnedFilesStatusAscRow, error)
    ListOwnedFilesStatusDesc(ctx context.Context, arg db.ListOwnedFilesStatusDescParams) ([]db.ListOwnedFilesStatusDescRow, error)
    ListOwnedFilesMimeAsc(ctx context.Context, arg db.ListOwnedFilesMimeAscParams) ([]db.ListOwnedFilesMimeAscRow, error)
    ListOwnedFilesMimeDesc(ctx context.Context, arg db.ListOwnedFilesMimeDescParams) ([]db.ListOwnedFilesMimeDescRow, error)
}

func NewSQLCRepository​

func NewSQLCRepository(pool *pgxpool.Pool, queries *db.Queries) Repository

NewSQLCRepository creates a postgres-backed db Repository instance.

type RevokeGrantParams​

RevokeGrantParams holds the validated inputs for revoking a file grant.

type RevokeGrantParams struct {
    FileID      uuid.UUID
    OwnerID     uuid.UUID
    GranteeType string
    GranteeID   uuid.UUID
    Permission  string
}

type S3Uploader​

S3Uploader is the interface the service uses to generate presigned upload URLs.

type S3Uploader interface {
    GeneratePresignedPutURL(ctx context.Context, key, contentType string, contentLength int64) (string, error)
}

type Service​

Service is the business-logic layer for the files feature.

type Service struct {
    // contains filtered or unexported fields
}

func NewService​

func NewService(repo Repository, s3 S3Uploader) *Service

NewService creates a new Service instance configured with the given repository.

func (*Service) CreateFile​

func (s *Service) CreateFile(ctx context.Context, p CreateFileParams) (CreateFileResult, error)

CreateFile inserts a pending file record in the database, generates a presigned S3 PUT URL, and returns both the file reference and the upload URL.

func (*Service) CreateGrant​

func (s *Service) CreateGrant(ctx context.Context, p CreateGrantParams) (Grant, error)

CreateGrant creates a file permission grant. The caller must own the file. If the grant already exists the existing row is returned (idempotent).

func (*Service) DeleteFile​

func (s *Service) DeleteFile(ctx context.Context, p DeleteFileParams, publisher QStashPublisher) error

DeleteFile soft-deletes the file within a transaction, then publishes an async S3 cleanup job via QStash. Returns apperrors.ErrNotFound if the file does not belong to the caller or is already in a deletion state.

func (*Service) GetFile​

func (s *Service) GetFile(ctx context.Context, p GetFileParams) (File, error)

GetFile retrieves a single file, verifying that the requesting user has access to it.

func (*Service) ListFiles​

func (s *Service) ListFiles(ctx context.Context, p ListFilesParams) ([]File, *string, error)

ListFiles queries the repository for a paginated list of files matching the given parameters.

func (*Service) RevokeGrant​

func (s *Service) RevokeGrant(ctx context.Context, p RevokeGrantParams) error

RevokeGrant revokes a file permission grant. The caller must own the file. If the grant does not exist the call is a no-op (idempotent).

func (*Service) UpdateFile​

func (s *Service) UpdateFile(ctx context.Context, p UpdateFileParams) (File, error)

UpdateFile renames a file after validating the new name. The name is trimmed of leading/trailing whitespace before validation. Returns apperrors.ErrNotFound if the file does not belong to the caller or is in a deletion state.

type SortDir​

SortDir represents the direction by which a file query should be ordered.

type SortDir string

type SortField​

SortField represents the field by which a file query should be ordered.

type SortField string

type UpdateFileParams​

UpdateFileParams contains the required inputs for renaming a file.

type UpdateFileParams struct {
    FileID  uuid.UUID
    OwnerID uuid.UUID
    Name    string
}

Generated by gomarkdoc