Skip to content

RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.

feat(go-connector): add Box connector (#18934)

mkaaadf62b10dc9784
diff --git a/internal/syncer/connector/box.go b/internal/syncer/connector/box.go
new file mode 100644
index 0000000000..c3a6948437
--- /dev/null
+++ b/internal/syncer/connector/box.go
@@ -0,0 +1,787 @@
+//
+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+package connector
+
+import (
+ "context"
+ "encoding/json"
+ "fmt"
+ "io"
+ "net/http"
+ "net/url"
+ "path"
+ "sort"
+ "strconv"
+ "strings"
+ "sync"
+ "time"
+)
+
+const (
+ defaultBoxBatchSize = 2
+ defaultBoxSizeThreshold = 20 * 1024 * 1024
+ boxRequestTimeout = 60 * time.Second
+ boxAPIBaseURL = "https://api.box.com/2.0"
+ boxOAuthTokenURL = "https://api.box.com/oauth2/token"
+)
+
+// BoxConnector reads files from one Box account.
+type BoxConnector struct {
+ folderID string
+ batchSize int
+ allowImages bool
+ sizeThreshold int64
+ clientID string
+ clientSecret string
+ accessToken string
+ refreshToken string
+
+ apiBaseURL string
+ tokenURL string
+ httpClient *http.Client
+
+ tokenMu sync.Mutex
+
+ listFolderItems func(ctx context.Context, folderID, marker string, limit int) (boxItemsPage, error)
+ getFile func(ctx context.Context, fileID string) (boxFile, error)
+ downloadFile func(ctx context.Context, fileID string, sizeThreshold int64) ([]byte, error)
+}
+
+// NewBoxConnector creates a Box connector from Python-compatible config.
+func NewBoxConnector(config map[string]any) (*BoxConnector, error) {
+ credentials := configAnyMap(config["credentials"])
+ clientID, clientSecret, accessToken, refreshToken, err := boxCredentials(credentials)
+ if err != nil {
+ return nil, err
+ }
+ folderID := strings.TrimSpace(stringConfig(config["folder_id"]))
+ if folderID == "" {
+ folderID = "0"
+ }
+ batchSize := configInt(firstNonEmpty(stringConfig(config["sync_batch_size"]), stringConfig(config["batch_size"])), defaultBoxBatchSize)
+ sizeThreshold := int64(configInt(config["size_threshold"], defaultBoxSizeThreshold))
+ if sizeThreshold <= 0 {
+ sizeThreshold = defaultBoxSizeThreshold
+ }
+ connector := &BoxConnector{
+ folderID: folderID,
+ batchSize: batchSize,
+ allowImages: configBoolDefault(config["allow_images"], false),
+ sizeThreshold: sizeThreshold,
+ clientID: clientID,
+ clientSecret: clientSecret,
+ accessToken: accessToken,
+ refreshToken: refreshToken,
+ apiBaseURL: boxAPIBaseURL,
+ tokenURL: boxOAuthTokenURL,
+ httpClient: &http.Client{
+ Timeout: boxRequestTimeout,
+ },
+ }
+ connector.listFolderItems = connector.defaultListFolderItems
+ connector.getFile = connector.defaultGetFile
+ connector.downloadFile = connector.defaultDownloadFile
+ return connector, nil
+}
+
+// Validate validates Box settings and credentials against the Box API.
+func (c *BoxConnector) Validate(ctx context.Context) error {
+ if err := c.validateConfig(); err != nil {
+ return err
+ }
+ if err := c.getCurrentUser(ctx); err != nil {
+ return fmt.Errorf("Box validation failed: %w", err)
+ }
+ return nil
+}
+
+// ValidateConnectorSetting validates an unsaved Box config.
+func (c *BoxConnector) ValidateConnectorSetting(ctx context.Context, request map[string]any) error {
+ if c == nil {
+ return fmt.Errorf("box connector is nil")
+ }
+ ctx, cancel := context.WithTimeout(ctx, connectorSettingValidationTimeout)
+ defer cancel()
+ connector, err := NewBoxConnector(request)
+ if err != nil {
+ return err
+ }
+ connector.apiBaseURL = c.apiBaseURL
+ connector.tokenURL = c.tokenURL
+ connector.httpClient = c.httpClient
+ connector.listFolderItems = c.listFolderItems
+ connector.getFile = c.getFile
+ connector.downloadFile = c.downloadFile
+ if err := connector.getCurrentUser(ctx); err != nil {
+ return fmt.Errorf("Box validation failed: %w", err)
+ }
+ return nil
+}
+
+// OpenSync opens one Box sync session without listing the source up front.
+func (c *BoxConnector) OpenSync(ctx context.Context, request SyncRequest) (SyncSession, error) {
+ if err := c.validateConfig(); err != nil {
+ return nil, err
+ }
+ return &boxSyncSession{
+ connector: c,
+ request: request,
+ batchSize: c.batchSize,
+ }, nil
+}
+
+// OpenPrune opens one complete Box prune snapshot session.
+func (c *BoxConnector) OpenPrune(ctx context.Context, request PruneRequest) (PruneSession, error) {
+ if err := c.validateConfig(); err != nil {
+ return nil, err
+ }
+ return &boxPruneSession{
+ connector: c,
+ batchSize: c.batchSize,
+ }, nil
+}
+
+// Fetch downloads a Box file referenced by a previous sync batch.
+func (c *BoxConnector) Fetch(ctx context.Context, ref FetchReference) ([]byte, error) {
+ var fetch boxFetchReference
+ if err := json.Unmarshal([]byte(ref.Key), &fetch); err != nil {
+ return nil, err
+ }
+ if strings.TrimSpace(fetch.FileID) == "" {
+ return nil, fmt.Errorf("Box fetch reference has no file id")
+ }
+ blob, err := c.downloadFile(ctx, fetch.FileID, c.sizeThreshold)
+ if err != nil {
+ return nil, err
+ }
+ if int64(len(blob)) > c.sizeThreshold {
+ return nil, fmt.Errorf("Box file %s exceeds size threshold", fetch.FileID)
+ }
+ return blob, nil
+}
+
+func (c *BoxConnector) validateConfig() error {
+ if c == nil {
+ return fmt.Errorf("box connector is nil")
+ }
+ if strings.TrimSpace(c.folderID) == "" {
+ return fmt.Errorf("Box folder_id is required")
+ }
+ if strings.TrimSpace(c.clientID) == "" || strings.TrimSpace(c.clientSecret) == "" || strings.TrimSpace(c.accessToken) == "" || strings.TrimSpace(c.refreshToken) == "" {
+ return fmt.Errorf("Box credentials must include client_id, client_secret, access_token, and refresh_token")
+ }
+ if c.batchSize <= 0 {
+ return fmt.Errorf("batch_size must be a positive integer")
+ }
+ return nil
+}
+
+func (c *BoxConnector) getCurrentUser(ctx context.Context) error {
+ var user map[string]any
+ return c.doRequest(ctx, http.MethodGet, c.apiBaseURL+"/users/me", &user)
+}
+
+func (c *BoxConnector) defaultListFolderItems(ctx context.Context, folderID, marker string, limit int) (boxItemsPage, error) {
+ if limit <= 0 {
+ limit = c.batchSize
+ if limit <= 0 {
+ limit = defaultBoxBatchSize
+ }
+ }
+ endpoint := c.apiBaseURL + "/folders/" + url.PathEscape(folderID) + "/items?usemarker=true&limit=" + strconv.Itoa(limit)
+ if marker != "" {
+ endpoint += "&marker=" + url.QueryEscape(marker)
+ }
+ var page boxItemsPage
+ err := c.doRequest(ctx, http.MethodGet, endpoint, &page)
+ return page, err
+}
+
+func (c *BoxConnector) defaultGetFile(ctx context.Context, fileID string) (boxFile, error) {
+ var file boxFile
+ err := c.doRequest(ctx, http.MethodGet, c.apiBaseURL+"/files/"+url.PathEscape(fileID), &file)
+ return file, err
+}
+
+func (c *BoxConnector) defaultDownloadFile(ctx context.Context, fileID string, sizeThreshold int64) ([]byte, error) {
+ limit := sizeThreshold
+ if limit <= 0 {
+ limit = defaultBoxSizeThreshold
+ }
+ return c.getBytes(ctx, c.apiBaseURL+"/files/"+url.PathEscape(fileID)+"/content", limit)
+}
+
+func (c *BoxConnector) doRequest(ctx context.Context, method, endpoint string, out any) error {
+ return c.doRequestOnce(ctx, method, endpoint, out, true)
+}
+
+func (c *BoxConnector) doRequestOnce(ctx context.Context, method, endpoint string, out any, allowRefresh bool) error {
+ ctx, cancel := context.WithTimeout(ctx, boxRequestTimeout)
+ defer cancel()
+ token, err := c.currentAccessToken()
+ if err != nil {
+ return err
+ }
+ req, err := http.NewRequestWithContext(ctx, method, endpoint, nil)
+ if err != nil {
+ return err
+ }
+ req.Header.Set("Authorization", "Bearer "+token)
+ resp, err := c.httpClient.Do(req)
+ if err != nil {
+ return err
+ }
+ if resp.StatusCode == http.StatusUnauthorized && allowRefresh {
+ _ = resp.Body.Close()
+ if err := c.refreshAccessToken(ctx); err != nil {
+ return fmt.Errorf("refresh Box access token: %w", err)
+ }
+ return c.doRequestOnce(ctx, method, endpoint, out, false)
+ }
+ defer resp.Body.Close()
+ if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+ return boxHTTPError(resp)
+ }
+ if out == nil {
+ return nil
+ }
+ return json.NewDecoder(resp.Body).Decode(out)
+}
+
+func (c *BoxConnector) getBytes(ctx context.Context, endpoint string, limit int64) ([]byte, error) {
+ return c.getBytesOnce(ctx, endpoint, limit, true)
+}
+
+func (c *BoxConnector) getBytesOnce(ctx context.Context, endpoint string, limit int64, allowRefresh bool) ([]byte, error) {
+ ctx, cancel := context.WithTimeout(ctx, boxRequestTimeout)
+ defer cancel()
+ token, err := c.currentAccessToken()
+ if err != nil {
+ return nil, err
+ }
+ req, err := http.NewRequestWithContext(ctx, http.MethodGet, endpoint, nil)
+ if err != nil {
+ return nil, err
+ }
+ req.Header.Set("Authorization", "Bearer "+token)
+ resp, err := c.httpClient.Do(req)
+ if err != nil {
+ return nil, err
+ }
+ if resp.StatusCode == http.StatusUnauthorized && allowRefresh {
+ _ = resp.Body.Close()
+ if err := c.refreshAccessToken(ctx); err != nil {
+ return nil, fmt.Errorf("refresh Box access token: %w", err)
+ }
+ return c.getBytesOnce(ctx, endpoint, limit, false)
+ }
+ defer resp.Body.Close()
+ if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+ return nil, boxHTTPError(resp)
+ }
+ blob, err := io.ReadAll(io.LimitReader(resp.Body, limit+1))
+ if err != nil {
+ return nil, err
+ }
+ if int64(len(blob)) > limit {
+ return nil, fmt.Errorf("Box file exceeds maximum size of %d bytes", limit)
+ }
+ return blob, nil
+}
+
+func (c *BoxConnector) currentAccessToken() (string, error) {
+ c.tokenMu.Lock()
+ defer c.tokenMu.Unlock()
+ if c.accessToken == "" {
+ return "", fmt.Errorf("Box access token is empty")
+ }
+ return c.accessToken, nil
+}
+
+func (c *BoxConnector) refreshAccessToken(ctx context.Context) error {
+ c.tokenMu.Lock()
+ defer c.tokenMu.Unlock()
+ if c.clientID == "" || c.clientSecret == "" || c.refreshToken == "" {
+ return fmt.Errorf("Box OAuth credentials are incomplete")
+ }
+ form := url.Values{}
+ form.Set("grant_type", "refresh_token")
+ form.Set("refresh_token", c.refreshToken)
+ form.Set("client_id", c.clientID)
+ form.Set("client_secret", c.clientSecret)
+
+ ctx, cancel := context.WithTimeout(ctx, boxRequestTimeout)
+ defer cancel()
+ req, err := http.NewRequestWithContext(ctx, http.MethodPost, c.tokenURL, strings.NewReader(form.Encode()))
+ if err != nil {
+ return err
+ }
+ req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+ resp, err := c.httpClient.Do(req)
+ if err != nil {
+ return err
+ }
+ defer resp.Body.Close()
+ body, err := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
+ if err != nil {
+ return err
+ }
+ var token boxTokenResponse
+ if err := json.Unmarshal(body, &token); err != nil {
+ return err
+ }
+ if resp.StatusCode >= http.StatusBadRequest || token.Error != "" {
+ if token.ErrorDescription != "" {
+ return fmt.Errorf("Box token refresh failed: %s", token.ErrorDescription)
+ }
+ if token.Error != "" {
+ return fmt.Errorf("Box token refresh failed: %s", token.Error)
+ }
+ return fmt.Errorf("Box token refresh failed: HTTP %d", resp.StatusCode)
+ }
+ if token.AccessToken == "" {
+ return fmt.Errorf("Box token refresh failed: empty access_token")
+ }
+ c.accessToken = token.AccessToken
+ if token.RefreshToken != "" {
+ c.refreshToken = token.RefreshToken
+ }
+ return nil
+}
+
+func (c *BoxConnector) collectFiles(ctx context.Context) ([]boxFile, error) {
+ var files []boxFile
+ seenFiles := map[string]struct{}{}
+ seenFolders := map[string]struct{}{}
+ var walk func(folderID, relativePath string) error
+ walk = func(folderID, relativePath string) error {
+ if _, ok := seenFolders[folderID]; ok {
+ return nil
+ }
+ seenFolders[folderID] = struct{}{}
+ marker := ""
+ for {
+ page, err := c.listFolderItems(ctx, folderID, marker, c.batchSize)
+ if err != nil {
+ return err
+ }
+ for _, entry := range page.Entries {
+ switch entry.Type {
+ case "file":
+ if entry.ID == "" {
+ continue
+ }
+ if _, ok := seenFiles[entry.ID]; ok {
+ continue
+ }
+ file, err := c.getFile(ctx, entry.ID)
+ if err != nil {
+ return err
+ }
+ file.relativePath = relativePath
+ seenFiles[entry.ID] = struct{}{}
+ files = append(files, file)
+ case "folder":
+ if entry.ID == "" {
+ continue
+ }
+ childPath := boxRelativePath(relativePath, entry.Name)
+ if err := walk(entry.ID, childPath); err != nil {
+ return err
+ }
+ }
+ }
+ if page.NextMarker == "" {
+ break
+ }
+ marker = page.NextMarker
+ }
+ return nil
+ }
+ if err := walk(c.folderID, ""); err != nil {
+ return nil, err
+ }
+ return files, nil
+}
+
+func (c *BoxConnector) isAcceptedFile(file boxFile) bool {
+ if strings.TrimSpace(file.ID) == "" || strings.TrimSpace(file.Name) == "" {
+ return false
+ }
+ if file.Size == nil || *file.Size < 0 || *file.Size > c.sizeThreshold {
+ return false
+ }
+ extension := boxExtension(file.Name)
+ if _, ok := webdavTextExtensions[extension]; ok {
+ return true
+ }
+ if _, ok := webdavDocumentExtensions[extension]; ok {
+ return true
+ }
+ if c.allowImages {
+ if _, ok := webdavImageExtensions[extension]; ok {
+ return true
+ }
+ }
+ return false
+}
+
+func (c *BoxConnector) sourceDocument(file boxFile) (SourceDocument, bool) {
+ if !c.isAcceptedFile(file) {
+ return SourceDocument{}, false
+ }
+ size := int64(0)
+ if file.Size != nil {
+ size = *file.Size
+ }
+ fetchKey, _ := json.Marshal(boxFetchReference{FileID: file.ID, Name: file.Name, Size: size})
+ metadata := map[string]any{
+ "file_id": file.ID,
+ "name": file.Name,
+ "url": boxFileURL(file),
+ }
+ if len(file.Metadata) > 0 {
+ var rawMetadata map[string]any
+ if json.Unmarshal(file.Metadata, &rawMetadata) == nil && len(rawMetadata) > 0 {
+ metadata["metadata"] = rawMetadata
+ }
+ }
+ return SourceDocument{
+ SourceID: boxSourceID(file.ID),
+ SemanticIdentifier: boxSemanticIdentifier(file),
+ Extension: boxExtension(file.Name),
+ FetchRef: &FetchReference{Key: string(fetchKey), SizeHint: size},
+ UpdatedAt: file.updatedAt(),
+ SizeBytes: size,
+ Metadata: metadata,
+ Fingerprint: file.fingerprint(),
+ }, true
+}
+
+func (c *BoxConnector) acceptedSlimDocuments(files []boxFile) []SlimDocument {
+ documents := make([]SlimDocument, 0, len(files))
+ for _, file := range files {
+ if c.isAcceptedFile(file) {
+ documents = append(documents, SlimDocument{SourceID: boxSourceID(file.ID)})
+ }
+ }
+ return documents
+}
+
+type boxSyncSession struct {
+ connector *BoxConnector
+ request SyncRequest
+ batchSize int
+
+ documents []SourceDocument
+ index int
+ loaded bool
+}
+
+// NextBatch returns the next Box source document batch.
+func (s *boxSyncSession) NextBatch(ctx context.Context) (SyncBatch, error) {
+ if !s.loaded {
+ if err := s.load(ctx); err != nil {
+ return SyncBatch{}, err
+ }
+ }
+ if s.index >= len(s.documents) {
+ return SyncBatch{}, io.EOF
+ }
+ end := s.index + s.batchSize
+ if end > len(s.documents) {
+ end = len(s.documents)
+ }
+ documents := s.documents[s.index:end]
+ s.index = end
+ return SyncBatch{Documents: documents, Checkpoint: boxSyncCheckpoint(documents[len(documents)-1])}, nil
+}
+
+// Close closes the Box sync session.
+func (s *boxSyncSession) Close() error {
+ return nil
+}
+
+// Fetch downloads a delayed Box document body.
+func (s *boxSyncSession) Fetch(ctx context.Context, ref FetchReference) ([]byte, error) {
+ return s.connector.Fetch(ctx, ref)
+}
+
+func (s *boxSyncSession) load(ctx context.Context) error {
+ files, err := s.connector.collectFiles(ctx)
+ if err != nil {
+ return err
+ }
+ documents := make([]SourceDocument, 0, len(files))
+ for _, file := range files {
+ if !includeBoxFile(s.request, file) {
+ continue
+ }
+ document, ok := s.connector.sourceDocument(file)
+ if ok {
+ documents = append(documents, document)
+ }
+ }
+ sort.Slice(documents, func(i, j int) bool { return documents[i].SourceID < documents[j].SourceID })
+ s.documents = documents
+ s.loaded = true
+ return s.applyResume(s.request.Resume)
+}
+
+// applyResume advances past the last committed Box document.
+func (s *boxSyncSession) applyResume(checkpoint *SyncCheckpoint) error {
+ if checkpoint == nil {
+ return nil
+ }
+ sourceID := firstNonEmpty(checkpoint.SourceID, checkpoint.Cursor)
+ if sourceID == "" {
+ return fmt.Errorf("box sync checkpoint has no source anchor: %w", ErrSyncResumeInvalid)
+ }
+ if !strings.HasPrefix(sourceID, "box:") || sourceID == "box:" {
+ return fmt.Errorf("box sync checkpoint source %q is invalid: %w", sourceID, ErrSyncResumeInvalid)
+ }
+ for index, document := range s.documents {
+ if document.SourceID == sourceID {
+ s.index = index + 1
+ return nil
+ }
+ }
+ return fmt.Errorf("box resume anchor %q was not found in the current listing: %w", sourceID, ErrSyncResumeInvalid)
+}
+
+func boxSyncCheckpoint(document SourceDocument) *SyncCheckpoint {
+ updatedAt := document.UpdatedAt
+ return &SyncCheckpoint{
+ Cursor: document.SourceID,
+ SourceID: document.SourceID,
+ UpdatedAt: &updatedAt,
+ }
+}
+
+type boxPruneSession struct {
+ connector *BoxConnector
+ batchSize int
+
+ documents []SlimDocument
+ index int
+ loaded bool
+}
+
+// NextBatch returns the next Box prune snapshot batch.
+func (s *boxPruneSession) NextBatch(ctx context.Context) (PruneBatch, error) {
+ if !s.loaded {
+ if err := s.load(ctx); err != nil {
+ return PruneBatch{}, err
+ }
+ }
+ if s.index >= len(s.documents) {
+ return PruneBatch{}, io.EOF
+ }
+ end := s.index + s.batchSize
+ if end > len(s.documents) {
+ end = len(s.documents)
+ }
+ documents := s.documents[s.index:end]
+ s.index = end
+ return PruneBatch{Documents: documents}, nil
+}
+
+// Close closes the Box prune session.
+func (s *boxPruneSession) Close() error {
+ return nil
+}
+
+func (s *boxPruneSession) load(ctx context.Context) error {
+ files, err := s.connector.collectFiles(ctx)
+ if err != nil {
+ return err
+ }
+ documents := s.connector.acceptedSlimDocuments(files)
+ sort.Slice(documents, func(i, j int) bool { return documents[i].SourceID < documents[j].SourceID })
+ s.documents = documents
+ s.loaded = true
+ return nil
+}
+
+type boxItemsPage struct {
+ Entries []boxItemEntry `json:"entries"`
+ NextMarker string `json:"next_marker"`
+}
+
+type boxItemEntry struct {
+ Type string `json:"type"`
+ ID string `json:"id"`
+ Name string `json:"name"`
+}
+
+type boxFile struct {
+ Type string `json:"type"`
+ ID string `json:"id"`
+ Name string `json:"name"`
+ Size *int64 `json:"size"`
+ ETag string `json:"etag"`
+ ModifiedAt string `json:"modified_at"`
+ ContentModifiedAt string `json:"content_modified_at"`
+ CreatedAt string `json:"created_at"`
+ WebLink string `json:"web_link"`
+ Metadata json.RawMessage `json:"metadata"`
+ FileVersion *boxFileVersion `json:"file_version"`
+
+ relativePath string
+}
+
+type boxFileVersion struct {
+ SHA1 string `json:"sha1"`
+}
+
+type boxTokenResponse struct {
+ AccessToken string `json:"access_token"`
+ RefreshToken string `json:"refresh_token"`
+ Error string `json:"error"`
+ ErrorDescription string `json:"error_description"`
+}
+
+type boxFetchReference struct {
+ FileID string `json:"file_id"`
+ Name string `json:"name"`
+ Size int64 `json:"size"`
+}
+
+func boxCredentials(credentials map[string]any) (clientID, clientSecret, accessToken, refreshToken string, err error) {
+ value, ok := credentials["box_tokens"]
+ if !ok || value == nil {
+ return "", "", "", "", nil
+ }
+ var payload struct {
+ ClientID string `json:"client_id"`
+ ClientSecret string `json:"client_secret"`
+ AccessToken string `json:"access_token"`
+ RefreshToken string `json:"refresh_token"`
+ }
+ switch typed := value.(type) {
+ case string:
+ if strings.TrimSpace(typed) == "" {
+ return "", "", "", "", nil
+ }
+ if err := json.Unmarshal([]byte(typed), &payload); err != nil {
+ return "", "", "", "", fmt.Errorf("parse box_tokens: %w", err)
+ }
+ case map[string]any:
+ payload.ClientID = stringConfig(typed["client_id"])
+ payload.ClientSecret = stringConfig(typed["client_secret"])
+ payload.AccessToken = stringConfig(typed["access_token"])
+ payload.RefreshToken = stringConfig(typed["refresh_token"])
+ default:
+ return "", "", "", "", fmt.Errorf("box_tokens must be a JSON string or object")
+ }
+ return strings.TrimSpace(payload.ClientID), strings.TrimSpace(payload.ClientSecret), strings.TrimSpace(payload.AccessToken), strings.TrimSpace(payload.RefreshToken), nil
+}
+
+func boxRelativePath(parent, name string) string {
+ if parent == "" {
+ return name
+ }
+ return parent + " / " + name
+}
+
+func boxSemanticIdentifier(file boxFile) string {
+ if file.relativePath == "" {
+ return file.Name
+ }
+ return file.relativePath + " / " + file.Name
+}
+
+func boxSourceID(fileID string) string {
+ return "box:" + fileID
+}
+
+func boxExtension(name string) string {
+ return strings.ToLower(path.Ext(name))
+}
+
+func boxFileURL(file boxFile) string {
+ if file.WebLink != "" {
+ return file.WebLink
+ }
+ return "https://app.box.com/file/" + url.PathEscape(file.ID)
+}
+
+func includeBoxFile(request SyncRequest, file boxFile) bool {
+ if request.FromBeginning {
+ return true
+ }
+ updatedAt := file.updatedAt()
+ if updatedAt.IsZero() {
+ return true
+ }
+ if len(request.Fingerprints) > 0 {
+ fingerprint := file.fingerprint()
+ stored, ok := request.Fingerprints[boxSourceID(file.ID)]
+ return fingerprint == "" || !ok || stored == "" || stored != fingerprint
+ }
+ return !beforeOrAtWindowStart(updatedAt, request.WindowStart) && !afterWindowEnd(updatedAt, request.WindowEnd)
+}
+
+func (f boxFile) updatedAt() time.Time {
+ for _, raw := range []string{f.ModifiedAt, f.ContentModifiedAt, f.CreatedAt} {
+ if parsed := parseBoxTime(raw); !parsed.IsZero() {
+ return parsed
+ }
+ }
+ return time.Now().UTC()
+}
+
+func (f boxFile) fingerprint() string {
+ sha1 := ""
+ if f.FileVersion != nil {
+ sha1 = f.FileVersion.SHA1
+ }
+ var size any
+ if f.Size != nil {
+ size = *f.Size
+ }
+ return stableFingerprint(map[string]any{
+ "id": f.ID,
+ "name": f.Name,
+ "path": f.relativePath,
+ "size": size,
+ "modified_at": f.ModifiedAt,
+ "content_modified_at": f.ContentModifiedAt,
+ "etag": f.ETag,
+ "sha1": sha1,
+ })
+}
+
+func parseBoxTime(raw string) time.Time {
+ raw = strings.TrimSpace(raw)
+ if raw == "" {
+ return time.Time{}
+ }
+ if parsed, err := time.Parse(time.RFC3339Nano, raw); err == nil {
+ return parsed.UTC()
+ }
+ return time.Time{}
+}
+
+func boxHTTPError(resp *http.Response) error {
+ data, _ := io.ReadAll(io.LimitReader(resp.Body, 4096))
+ message := strings.TrimSpace(string(data))
+ if message == "" {
+ message = resp.Status
+ }
+ return fmt.Errorf("Box request failed with status %d: %s", resp.StatusCode, message)
+}
diff --git a/internal/syncer/connector/box_test.go b/internal/syncer/connector/box_test.go
new file mode 100644
index 0000000000..52dd7223ae
--- /dev/null
+++ b/internal/syncer/connector/box_test.go
@@ -0,0 +1,645 @@
+//
+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+package connector
+
+import (
+ "context"
+ "errors"
+ "io"
+ "net/http"
+ "net/http/httptest"
+ "strings"
+ "testing"
+)
+
+const boxTestTokens = `{"client_id":"client","client_secret":"secret","access_token":"token","refresh_token":"refresh"}`
+
+func boxTestConnector(t *testing.T, config map[string]any) *BoxConnector {
+ t.Helper()
+ connector, err := NewBoxConnector(config)
+ if err != nil {
+ t.Fatalf("NewBoxConnector failed: %v", err)
+ }
+ return connector
+}
+
+func boxTestFile(id, name string, size int64, modified string) boxFile {
+ return boxFile{
+ ID: id,
+ Name: name,
+ Size: &size,
+ ModifiedAt: modified,
+ }
+}
+
+func TestNewBoxConnectorConfigDefaults(t *testing.T) {
+ connector := boxTestConnector(t, map[string]any{
+ "credentials": map[string]any{"box_tokens": boxTestTokens},
+ })
+ if connector.folderID != "0" {
+ t.Fatalf("folder_id = %q, want 0", connector.folderID)
+ }
+ if connector.batchSize != defaultBoxBatchSize {
+ t.Fatalf("batch_size = %d, want %d", connector.batchSize, defaultBoxBatchSize)
+ }
+ if connector.sizeThreshold != defaultBoxSizeThreshold {
+ t.Fatalf("size_threshold = %d, want %d", connector.sizeThreshold, defaultBoxSizeThreshold)
+ }
+ if connector.allowImages {
+ t.Fatalf("allow_images = true, want false")
+ }
+ if connector.clientID != "client" || connector.clientSecret != "secret" || connector.accessToken != "token" || connector.refreshToken != "refresh" {
+ t.Fatalf("credentials = %q/%q/%q/%q", connector.clientID, connector.clientSecret, connector.accessToken, connector.refreshToken)
+ }
+}
+
+func TestNewBoxConnectorConfigOverrides(t *testing.T) {
+ connector := boxTestConnector(t, map[string]any{
+ "folder_id": "123",
+ "sync_batch_size": 7,
+ "batch_size": 3,
+ "size_threshold": "10",
+ "allow_images": true,
+ "credentials": map[string]any{
+ "box_tokens": map[string]any{
+ "client_id": "client",
+ "client_secret": "secret",
+ "access_token": "token",
+ "refresh_token": "refresh",
+ },
+ },
+ })
+ if connector.folderID != "123" {
+ t.Fatalf("folder_id = %q, want 123", connector.folderID)
+ }
+ if connector.batchSize != 7 {
+ t.Fatalf("batch_size = %d, want 7", connector.batchSize)
+ }
+ if connector.sizeThreshold != 10 {
+ t.Fatalf("size_threshold = %d, want 10", connector.sizeThreshold)
+ }
+ if !connector.allowImages {
+ t.Fatalf("allow_images = false, want true")
+ }
+}
+
+func TestNewBoxConnectorRejectsInvalidBoxTokens(t *testing.T) {
+ tests := []struct {
+ name string
+ value any
+ want string
+ }{
+ {name: "non string object", value: 123, want: "JSON string or object"},
+ {name: "invalid json", value: "{", want: "parse box_tokens"},
+ }
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ _, err := NewBoxConnector(map[string]any{
+ "credentials": map[string]any{"box_tokens": tt.value},
+ })
+ if err == nil || !strings.Contains(err.Error(), tt.want) {
+ t.Fatalf("NewBoxConnector err = %v, want containing %q", err, tt.want)
+ }
+ })
+ }
+}
+
+func TestBoxConnectorValidateCallsCurrentUserOnly(t *testing.T) {
+ var paths []string
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ paths = append(paths, r.URL.Path)
+ if r.URL.Path == "/users/me" {
+ w.WriteHeader(http.StatusOK)
+ _, _ = io.WriteString(w, `{"id":"1"}`)
+ return
+ }
+ w.WriteHeader(http.StatusNotFound)
+ }))
+ defer server.Close()
+
+ connector := boxTestConnector(t, map[string]any{
+ "credentials": map[string]any{"box_tokens": boxTestTokens},
+ })
+ connector.apiBaseURL = server.URL
+ connector.httpClient = server.Client()
+
+ if err := connector.Validate(context.Background()); err != nil {
+ t.Fatalf("Validate failed: %v", err)
+ }
+ if len(paths) != 1 || paths[0] != "/users/me" {
+ t.Fatalf("validation paths = %#v, want only /users/me", paths)
+ }
+}
+
+func TestRegisterBuiltInsOpensBox(t *testing.T) {
+ registry := NewRegistry()
+ RegisterBuiltIns(registry)
+ connector, err := registry.OpenFromConfig("box", map[string]any{
+ "credentials": map[string]any{"box_tokens": boxTestTokens},
+ })
+ if err != nil {
+ t.Fatalf("OpenFromConfig failed: %v", err)
+ }
+ if _, ok := connector.(*BoxConnector); !ok {
+ t.Fatalf("connector type = %T, want *BoxConnector", connector)
+ }
+}
+
+func TestBoxConnectorValidateMissingCredentials(t *testing.T) {
+ connector := boxTestConnector(t, map[string]any{
+ "credentials": map[string]any{},
+ })
+ err := connector.Validate(context.Background())
+ if err == nil || !strings.Contains(err.Error(), "credentials must include") {
+ t.Fatalf("Validate err = %v, want missing credential error", err)
+ }
+}
+
+func TestBoxConnectorValidateConnectorSettingUsesRequest(t *testing.T) {
+ var calls int
+ var authHeader string
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ calls++
+ authHeader = r.Header.Get("Authorization")
+ if r.URL.Path != "/users/me" || authHeader != "Bearer request-token" {
+ w.WriteHeader(http.StatusUnauthorized)
+ return
+ }
+ w.WriteHeader(http.StatusOK)
+ _, _ = io.WriteString(w, `{"id":"1"}`)
+ }))
+ defer server.Close()
+
+ receiver := boxTestConnector(t, map[string]any{
+ "credentials": map[string]any{"box_tokens": boxTestTokens},
+ })
+ receiver.apiBaseURL = server.URL
+ receiver.httpClient = server.Client()
+
+ err := receiver.ValidateConnectorSetting(context.Background(), map[string]any{
+ "folder_id": "0",
+ "credentials": map[string]any{
+ "box_tokens": `{"client_id":"client","client_secret":"secret","access_token":"request-token","refresh_token":"refresh"}`,
+ },
+ })
+ if err != nil {
+ t.Fatalf("ValidateConnectorSetting failed: %v", err)
+ }
+ if calls != 1 || authHeader != "Bearer request-token" {
+ t.Fatalf("calls = %d, auth = %q; want one request with request token", calls, authHeader)
+ }
+}
+
+func TestBoxConnectorValidateConnectorSettingRejectsMissingRequestCredentials(t *testing.T) {
+ receiver := boxTestConnector(t, map[string]any{
+ "credentials": map[string]any{"box_tokens": boxTestTokens},
+ })
+ err := receiver.ValidateConnectorSetting(context.Background(), map[string]any{
+ "credentials": map[string]any{},
+ })
+ if err == nil || !strings.Contains(err.Error(), "access token") {
+ t.Fatalf("ValidateConnectorSetting err = %v, want missing request token error", err)
+ }
+}
+
+func TestBoxConnectorOpenSyncListsLazilyAndFetches(t *testing.T) {
+ var listCalls int
+ var downloadIDs []string
+ connector := boxTestConnector(t, map[string]any{
+ "batch_size": 2,
+ "credentials": map[string]any{"box_tokens": boxTestTokens},
+ })
+ connector.listFolderItems = func(ctx context.Context, folderID, marker string, limit int) (boxItemsPage, error) {
+ listCalls++
+ if folderID == "0" {
+ return boxItemsPage{Entries: []boxItemEntry{{Type: "folder", ID: "folder", Name: "Folder"}}}, nil
+ }
+ return boxItemsPage{Entries: []boxItemEntry{
+ {Type: "file", ID: "alpha", Name: "alpha.txt"},
+ {Type: "file", ID: "beta", Name: "beta.txt"},
+ }}, nil
+ }
+ connector.getFile = func(ctx context.Context, fileID string) (boxFile, error) {
+ size := int64(5)
+ switch fileID {
+ case "alpha":
+ return boxFile{ID: "alpha", Name: "alpha.txt", Size: &size, ModifiedAt: "2026-01-02T00:00:00Z", WebLink: "https://app.box.com/file/alpha"}, nil
+ case "beta":
+ return boxFile{ID: "beta", Name: "beta.txt", Size: &size, ModifiedAt: "2026-01-03T00:00:00Z"}, nil
+ }
+ return boxFile{}, nil
+ }
+ connector.downloadFile = func(ctx context.Context, fileID string, sizeThreshold int64) ([]byte, error) {
+ downloadIDs = append(downloadIDs, fileID)
+ return []byte("body:" + fileID), nil
+ }
+
+ session, err := connector.OpenSync(context.Background(), SyncRequest{FromBeginning: true})
+ if err != nil {
+ t.Fatalf("OpenSync failed: %v", err)
+ }
+ defer session.Close()
+ if listCalls != 0 {
+ t.Fatalf("OpenSync listed eagerly: %d calls", listCalls)
+ }
+
+ batch, err := session.NextBatch(context.Background())
+ if err != nil {
+ t.Fatalf("NextBatch failed: %v", err)
+ }
+ if len(batch.Documents) != 2 {
+ t.Fatalf("batch documents = %d, want 2", len(batch.Documents))
+ }
+ if batch.Documents[0].SourceID != "box:alpha" || batch.Documents[0].SemanticIdentifier != "Folder / alpha.txt" {
+ t.Fatalf("first document = %#v", batch.Documents[0])
+ }
+ if batch.Documents[1].SourceID != "box:beta" || batch.Documents[1].SemanticIdentifier != "Folder / beta.txt" {
+ t.Fatalf("second document = %#v", batch.Documents[1])
+ }
+ if batch.Documents[0].Metadata["url"] != "https://app.box.com/file/alpha" {
+ t.Fatalf("metadata url = %#v", batch.Documents[0].Metadata["url"])
+ }
+ if listCalls != 2 {
+ t.Fatalf("list calls = %d, want 2", listCalls)
+ }
+
+ fetcher, ok := session.(Fetcher)
+ if !ok {
+ t.Fatalf("sync session does not implement Fetcher")
+ }
+ blob, err := fetcher.Fetch(context.Background(), *batch.Documents[0].FetchRef)
+ if err != nil {
+ t.Fatalf("Fetch failed: %v", err)
+ }
+ if string(blob) != "body:alpha" || strings.Join(downloadIDs, ",") != "alpha" {
+ t.Fatalf("fetched blob = %q, download ids = %#v", blob, downloadIDs)
+ }
+}
+
+func TestBoxConnectorOpenSyncFiltersAndWindow(t *testing.T) {
+ connector := boxTestConnector(t, map[string]any{
+ "batch_size": 10,
+ "credentials": map[string]any{"box_tokens": boxTestTokens},
+ })
+ connector.sizeThreshold = 5
+ files := []boxFile{
+ boxTestFile("old", "old.txt", 5, "2026-01-01T00:00:00Z"),
+ boxTestFile("alpha", "alpha.txt", 5, "2026-01-02T12:00:00Z"),
+ boxTestFile("future", "future.txt", 5, "2026-01-04T00:00:00Z"),
+ boxTestFile("image", "image.png", 5, "2026-01-02T12:00:00Z"),
+ boxTestFile("big", "big.txt", 6, "2026-01-02T12:00:00Z"),
+ boxTestFile("unknown", "unknown.xyz", 5, "2026-01-02T12:00:00Z"),
+ }
+ connector.listFolderItems = boxListFromFiles(files)
+ connector.getFile = boxGetFromFiles(files)
+
+ start := mustTime(t, "2026-01-02T00:00:00Z")
+ end := mustTime(t, "2026-01-03T00:00:00Z")
+ session, err := connector.OpenSync(context.Background(), SyncRequest{WindowStart: &start, WindowEnd: end})
+ if err != nil {
+ t.Fatalf("OpenSync failed: %v", err)
+ }
+ defer session.Close()
+
+ batch, err := session.NextBatch(context.Background())
+ if err != nil {
+ t.Fatalf("NextBatch failed: %v", err)
+ }
+ if len(batch.Documents) != 1 || batch.Documents[0].SourceID != "box:alpha" {
+ t.Fatalf("filtered documents = %#v", batch.Documents)
+ }
+}
+
+func TestBoxConnectorOpenSyncAllowImages(t *testing.T) {
+ files := []boxFile{
+ boxTestFile("doc", "doc.txt", 5, "2026-01-02T00:00:00Z"),
+ boxTestFile("image", "image.png", 5, "2026-01-02T00:00:00Z"),
+ }
+ for _, allow := range []bool{false, true} {
+ name := "allow_images=false"
+ if allow {
+ name = "allow_images=true"
+ }
+ t.Run(name, func(t *testing.T) {
+ connector := boxTestConnector(t, map[string]any{
+ "batch_size": 10,
+ "allow_images": allow,
+ "credentials": map[string]any{"box_tokens": boxTestTokens},
+ })
+ connector.listFolderItems = boxListFromFiles(files)
+ connector.getFile = boxGetFromFiles(files)
+ session, err := connector.OpenSync(context.Background(), SyncRequest{FromBeginning: true})
+ if err != nil {
+ t.Fatalf("OpenSync failed: %v", err)
+ }
+ defer session.Close()
+ batch, err := session.NextBatch(context.Background())
+ if err != nil {
+ t.Fatalf("NextBatch failed: %v", err)
+ }
+ want := 1
+ if allow {
+ want = 2
+ }
+ if len(batch.Documents) != want {
+ t.Fatalf("documents = %d, want %d", len(batch.Documents), want)
+ }
+ })
+ }
+}
+
+func TestBoxConnectorOpenSyncFingerprintFilter(t *testing.T) {
+ alpha := boxTestFile("alpha", "alpha.txt", 5, "2026-01-02T00:00:00Z")
+ beta := boxTestFile("beta", "beta.txt", 5, "2026-01-03T00:00:00Z")
+ gamma := boxTestFile("gamma", "gamma.txt", 5, "2026-01-04T00:00:00Z")
+ files := []boxFile{alpha, beta, gamma}
+ connector := boxTestConnector(t, map[string]any{
+ "batch_size": 10,
+ "credentials": map[string]any{"box_tokens": boxTestTokens},
+ })
+ connector.listFolderItems = boxListFromFiles(files)
+ connector.getFile = boxGetFromFiles(files)
+
+ session, err := connector.OpenSync(context.Background(), SyncRequest{
+ Fingerprints: map[string]string{
+ "box:alpha": alpha.fingerprint(),
+ "box:gamma": "old-fingerprint",
+ },
+ })
+ if err != nil {
+ t.Fatalf("OpenSync failed: %v", err)
+ }
+ defer session.Close()
+
+ batch, err := session.NextBatch(context.Background())
+ if err != nil {
+ t.Fatalf("NextBatch failed: %v", err)
+ }
+ var ids []string
+ for _, document := range batch.Documents {
+ ids = append(ids, document.SourceID)
+ }
+ if strings.Join(ids, ",") != "box:beta,box:gamma" {
+ t.Fatalf("fingerprint filtered ids = %#v", ids)
+ }
+}
+
+func TestBoxFileUpdatedAtPrecedence(t *testing.T) {
+ modified := boxFile{
+ ModifiedAt: "2026-01-03T00:00:00Z",
+ ContentModifiedAt: "2026-01-02T00:00:00Z",
+ CreatedAt: "2026-01-01T00:00:00Z",
+ }
+ if !modified.updatedAt().Equal(mustTime(t, "2026-01-03T00:00:00Z")) {
+ t.Fatalf("updatedAt = %v, want modified_at", modified.updatedAt())
+ }
+ content := boxFile{ContentModifiedAt: "2026-01-02T00:00:00Z", CreatedAt: "2026-01-01T00:00:00Z"}
+ if !content.updatedAt().Equal(mustTime(t, "2026-01-02T00:00:00Z")) {
+ t.Fatalf("updatedAt = %v, want content_modified_at", content.updatedAt())
+ }
+ created := boxFile{CreatedAt: "2026-01-01T00:00:00Z"}
+ if !created.updatedAt().Equal(mustTime(t, "2026-01-01T00:00:00Z")) {
+ t.Fatalf("updatedAt = %v, want created_at", created.updatedAt())
+ }
+}
+
+func TestBoxConnectorSkipsOversizeBeforeDownload(t *testing.T) {
+ var downloadCalls int
+ files := []boxFile{boxTestFile("big", "big.txt", 10, "2026-01-02T00:00:00Z")}
+ connector := boxTestConnector(t, map[string]any{
+ "batch_size": 10,
+ "credentials": map[string]any{"box_tokens": boxTestTokens},
+ })
+ connector.sizeThreshold = 5
+ connector.listFolderItems = boxListFromFiles(files)
+ connector.getFile = boxGetFromFiles(files)
+ connector.downloadFile = func(ctx context.Context, fileID string, sizeThreshold int64) ([]byte, error) {
+ downloadCalls++
+ return nil, nil
+ }
+
+ session, err := connector.OpenSync(context.Background(), SyncRequest{FromBeginning: true})
+ if err != nil {
+ t.Fatalf("OpenSync failed: %v", err)
+ }
+ defer session.Close()
+ if _, err := session.NextBatch(context.Background()); err != io.EOF {
+ t.Fatalf("NextBatch err = %v, want io.EOF", err)
+ }
+ if downloadCalls != 0 {
+ t.Fatalf("download calls = %d, want 0", downloadCalls)
+ }
+}
+
+func TestBoxConnectorPrune(t *testing.T) {
+ var listCalls int
+ files := []boxFile{
+ boxTestFile("a", "a.txt", 5, "2026-01-02T00:00:00Z"),
+ boxTestFile("b", "b.txt", 5, "2026-01-02T00:00:00Z"),
+ boxTestFile("image", "image.png", 5, "2026-01-02T00:00:00Z"),
+ boxTestFile("big", "big.txt", 10, "2026-01-02T00:00:00Z"),
+ }
+ connector := boxTestConnector(t, map[string]any{
+ "batch_size": 1,
+ "credentials": map[string]any{"box_tokens": boxTestTokens},
+ })
+ connector.sizeThreshold = 5
+ connector.listFolderItems = func(ctx context.Context, folderID, marker string, limit int) (boxItemsPage, error) {
+ listCalls++
+ return boxListFromFiles(files)(ctx, folderID, marker, limit)
+ }
+ connector.getFile = boxGetFromFiles(files)
+
+ prune, err := connector.OpenPrune(context.Background(), PruneRequest{})
+ if err != nil {
+ t.Fatalf("OpenPrune failed: %v", err)
+ }
+ defer prune.Close()
+ if listCalls != 0 {
+ t.Fatalf("OpenPrune listed eagerly: %d calls", listCalls)
+ }
+
+ first, err := prune.NextBatch(context.Background())
+ if err != nil || len(first.Documents) != 1 || first.Documents[0].SourceID != "box:a" {
+ t.Fatalf("first prune batch = %#v, err = %v", first, err)
+ }
+ second, err := prune.NextBatch(context.Background())
+ if err != nil || len(second.Documents) != 1 || second.Documents[0].SourceID != "box:b" {
+ t.Fatalf("second prune batch = %#v, err = %v", second, err)
+ }
+ if _, err := prune.NextBatch(context.Background()); err != io.EOF {
+ t.Fatalf("final prune NextBatch err = %v, want io.EOF", err)
+ }
+ if listCalls != 1 {
+ t.Fatalf("list calls = %d, want 1", listCalls)
+ }
+}
+
+func TestBoxConnectorResume(t *testing.T) {
+ files := []boxFile{
+ boxTestFile("a", "a.txt", 5, "2026-01-02T00:00:00Z"),
+ boxTestFile("b", "b.txt", 5, "2026-01-03T00:00:00Z"),
+ boxTestFile("c", "c.txt", 5, "2026-01-04T00:00:00Z"),
+ }
+ connector := boxTestConnector(t, map[string]any{
+ "batch_size": 10,
+ "credentials": map[string]any{"box_tokens": boxTestTokens},
+ })
+ connector.listFolderItems = boxListFromFiles(files)
+ connector.getFile = boxGetFromFiles(files)
+
+ session, err := connector.OpenSync(context.Background(), SyncRequest{
+ FromBeginning: true,
+ Resume: &SyncCheckpoint{SourceID: "box:b"},
+ })
+ if err != nil {
+ t.Fatalf("OpenSync failed: %v", err)
+ }
+ defer session.Close()
+
+ batch, err := session.NextBatch(context.Background())
+ if err != nil {
+ t.Fatalf("resumed NextBatch failed: %v", err)
+ }
+ if len(batch.Documents) != 1 || batch.Documents[0].SourceID != "box:c" {
+ t.Fatalf("resumed documents = %#v", batch.Documents)
+ }
+ if batch.Checkpoint == nil || batch.Checkpoint.SourceID != "box:c" {
+ t.Fatalf("resumed checkpoint = %#v", batch.Checkpoint)
+ }
+}
+
+func TestBoxConnectorResumeRejectsInvalidCheckpoint(t *testing.T) {
+ files := []boxFile{
+ boxTestFile("a", "a.txt", 5, "2026-01-02T00:00:00Z"),
+ boxTestFile("b", "b.txt", 5, "2026-01-03T00:00:00Z"),
+ }
+ tests := []*SyncCheckpoint{
+ {},
+ {SourceID: "dropbox:a"},
+ {SourceID: "box:"},
+ {SourceID: "box:missing"},
+ }
+ for _, checkpoint := range tests {
+ t.Run(checkpoint.SourceID, func(t *testing.T) {
+ connector := boxTestConnector(t, map[string]any{
+ "batch_size": 10,
+ "credentials": map[string]any{"box_tokens": boxTestTokens},
+ })
+ connector.listFolderItems = boxListFromFiles(files)
+ connector.getFile = boxGetFromFiles(files)
+ session, err := connector.OpenSync(context.Background(), SyncRequest{Resume: checkpoint})
+ if err != nil {
+ t.Fatalf("OpenSync err = %v, want session to defer resume validation", err)
+ }
+ defer session.Close()
+ if _, err := session.NextBatch(context.Background()); !errors.Is(err, ErrSyncResumeInvalid) {
+ t.Fatalf("NextBatch err = %v, want ErrSyncResumeInvalid", err)
+ }
+ })
+ }
+}
+
+func TestBoxConnectorOAuthRefreshAndRetry(t *testing.T) {
+ var refreshRequests int
+ var downloadRequests int
+ var downloadAuth []string
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ switch r.URL.Path {
+ case "/oauth2/token":
+ refreshRequests++
+ w.WriteHeader(http.StatusOK)
+ _, _ = io.WriteString(w, `{"access_token":"new-access","refresh_token":"new-refresh"}`)
+ case "/files/file/content":
+ downloadRequests++
+ downloadAuth = append(downloadAuth, r.Header.Get("Authorization"))
+ if downloadRequests == 1 {
+ w.WriteHeader(http.StatusUnauthorized)
+ return
+ }
+ w.WriteHeader(http.StatusOK)
+ _, _ = io.WriteString(w, "hello")
+ default:
+ w.WriteHeader(http.StatusNotFound)
+ }
+ }))
+ defer server.Close()
+
+ connector := boxTestConnector(t, map[string]any{
+ "credentials": map[string]any{"box_tokens": boxTestTokens},
+ })
+ connector.apiBaseURL = server.URL
+ connector.tokenURL = server.URL + "/oauth2/token"
+ connector.httpClient = server.Client()
+
+ blob, err := connector.defaultDownloadFile(context.Background(), "file", 10)
+ if err != nil {
+ t.Fatalf("defaultDownloadFile failed: %v", err)
+ }
+ if string(blob) != "hello" || refreshRequests != 1 || downloadRequests != 2 {
+ t.Fatalf("blob = %q, refresh = %d, downloads = %d", blob, refreshRequests, downloadRequests)
+ }
+ if connector.accessToken != "new-access" || connector.refreshToken != "new-refresh" {
+ t.Fatalf("tokens = %q/%q, want new-access/new-refresh", connector.accessToken, connector.refreshToken)
+ }
+ if len(downloadAuth) != 2 || downloadAuth[0] != "Bearer token" || downloadAuth[1] != "Bearer new-access" {
+ t.Fatalf("download auth headers = %#v", downloadAuth)
+ }
+}
+
+func TestBoxConnectorDownloadEnforcesSizeThreshold(t *testing.T) {
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ w.WriteHeader(http.StatusOK)
+ _, _ = io.WriteString(w, "123456")
+ }))
+ defer server.Close()
+
+ connector := boxTestConnector(t, map[string]any{
+ "credentials": map[string]any{"box_tokens": boxTestTokens},
+ })
+ connector.apiBaseURL = server.URL
+ connector.httpClient = server.Client()
+
+ _, err := connector.defaultDownloadFile(context.Background(), "file", 5)
+ if err == nil || !strings.Contains(err.Error(), "maximum size") {
+ t.Fatalf("defaultDownloadFile err = %v, want size threshold error", err)
+ }
+}
+
+func boxListFromFiles(files []boxFile) func(ctx context.Context, folderID, marker string, limit int) (boxItemsPage, error) {
+ return func(ctx context.Context, folderID, marker string, limit int) (boxItemsPage, error) {
+ entries := make([]boxItemEntry, 0, len(files))
+ for _, file := range files {
+ entries = append(entries, boxItemEntry{Type: "file", ID: file.ID, Name: file.Name})
+ }
+ return boxItemsPage{Entries: entries}, nil
+ }
+}
+
+func boxGetFromFiles(files []boxFile) func(ctx context.Context, fileID string) (boxFile, error) {
+ byID := make(map[string]boxFile, len(files))
+ for _, file := range files {
+ byID[file.ID] = file
+ }
+ return func(ctx context.Context, fileID string) (boxFile, error) {
+ file, ok := byID[fileID]
+ if !ok {
+ return boxFile{}, nil
+ }
+ return file, nil
+ }
+}
diff --git a/internal/syncer/connector/builtin.go b/internal/syncer/connector/builtin.go
index dcff5b9246..0fc6a61e42 100644
--- a/internal/syncer/connector/builtin.go
+++ b/internal/syncer/connector/builtin.go
@@ -32,6 +32,7 @@ func RegisterBuiltIns(registry *Registry) {
registerBuiltIn(registry, "bitbucket", NewBitbucketConnector)
registerBuiltIn(registry, "azure_devops", NewAzureDevOpsConnector)
registerBuiltIn(registry, "dropbox", NewDropboxConnector)
+ registerBuiltIn(registry, "box", NewBoxConnector)
registerBuiltIn(registry, "github", NewGitHubConnector)
registerBuiltIn(registry, "gitlab", NewGitlabConnector)
registerBuiltIn(registry, "gmail", NewGmailConnector)