feat(sub): expose last subscription fetch time (#6217)

* feat(sub): expose last subscription fetch time

Record successful GET subscription fetches per client and surface the timestamp in the client API and UI.

* fix(frontend): include last subscription fetch in client traffic

* Update sub_fetch_test.go

---------

Co-authored-by: Hermes Agent <hermes-agent@localhost>

internal/sub/controller.go

@@ -385,10 +385,12 @@ func (a *SUBController) subs(c *gin.Context) {
 		return
 	}
 	if shouldAutoServeClash(a.subClashAutoDetect, a.clashEnabled, false, userAgent, a.clashUserAgent) && a.serveClashBody(c, false) {
+		a.recordSubscriptionFetch(c)
 		logSubscriptionRoute(userAgent, "clash")
 		return
 	}
 	if shouldAutoServeJson(a.jsonAutoDetect, a.jsonEnabled, false, userAgent, a.jsonUserAgent) && a.serveJsonBody(c, true, "application/json; charset=utf-8", false) {
+		a.recordSubscriptionFetch(c)
 		logSubscriptionRoute(userAgent, "json")
 		return
 	}
@@ -425,6 +427,16 @@ func (a *SUBController) subs(c *gin.Context) {
 		} else {
 			c.String(200, result.String())
 		}
+		a.recordSubscriptionFetch(c)
+	}
+}
+
+func (a *SUBController) recordSubscriptionFetch(c *gin.Context) {
+	if c.Request == nil || c.Request.Method != http.MethodGet || c.Writer.Status() != http.StatusOK {
+		return
+	}
+	if err := a.subService.RecordSubscriptionFetch(c.Param("subid")); err != nil {
+		logger.Warning("Failed to record subscription fetch:", err)
 	}
 }
 
@@ -650,6 +662,7 @@ func (a *SUBController) subJsons(c *gin.Context) {
 		if !a.serveJsonBody(c, a.jsonAlwaysArray, "application/json; charset=utf-8", true) {
 			writeSubError(c, nil)
 		}
+		a.recordSubscriptionFetch(c)
 		return
 	}
 	if a.maybeServeSubPage(c) {
@@ -662,6 +675,7 @@ func (a *SUBController) serveJson(c *gin.Context, alwaysReturnArray bool, conten
 	if !a.serveJsonBody(c, alwaysReturnArray, contentType, false) {
 		writeSubError(c, nil)
 	}
+	a.recordSubscriptionFetch(c)
 }
 
 func (a *SUBController) serveJsonBody(c *gin.Context, alwaysReturnArray bool, contentType string, rawDownload bool) bool {
@@ -693,6 +707,7 @@ func (a *SUBController) subClashs(c *gin.Context) {
 		if !a.serveClashBody(c, true) {
 			writeSubError(c, nil)
 		}
+		a.recordSubscriptionFetch(c)
 		return
 	}
 	if a.maybeServeSubPage(c) {
@@ -701,6 +716,7 @@ func (a *SUBController) subClashs(c *gin.Context) {
 	if !a.serveClashBody(c, false) {
 		writeSubError(c, nil)
 	}
+	a.recordSubscriptionFetch(c)
 }
 
 func (a *SUBController) serveClashBody(c *gin.Context, rawDownload bool) bool {

internal/sub/service.go

@@ -273,6 +273,16 @@ func (s *SubService) matchingClients(inbound *model.Inbound, subId string) []mod
 	return out
 }
 
+// RecordSubscriptionFetch records a successful subscription response for all clients sharing subId.
+func (s *SubService) RecordSubscriptionFetch(subId string) error {
+	if strings.TrimSpace(subId) == "" {
+		return nil
+	}
+	return database.GetDB().Model(&xray.ClientTraffic{}).
+		Where("email IN (SELECT email FROM clients WHERE sub_id = ?)", subId).
+		Update("last_sub_fetch", time.Now().UnixMilli()).Error
+}
+
 // GetSubs retrieves subscription links for a given subscription ID and host.
 func (s *SubService) GetSubs(subId string, host string) ([]string, []string, int64, xray.ClientTraffic, error) {
 	return s.ForRequest(host).getSubs(subId)

internal/sub/sub_fetch_test.go

@@ -0,0 +1,99 @@
+package sub
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/gin-gonic/gin"
+
+	"github.com/mhsanaei/3x-ui/v3/internal/database"
+	"github.com/mhsanaei/3x-ui/v3/internal/database/model"
+	"github.com/mhsanaei/3x-ui/v3/internal/xray"
+)
+
+func TestRecordSubscriptionFetch(t *testing.T) {
+	initSubDB(t)
+	db := database.GetDB()
+
+	clients := []model.ClientRecord{
+		{Email: "alpha@example.com", SubID: "sub-alpha", Enable: true},
+		{Email: "bravo@example.com", SubID: "sub-bravo", Enable: true},
+	}
+	for i := range clients {
+		if err := db.Create(&clients[i]).Error; err != nil {
+			t.Fatalf("create client %s: %v", clients[i].Email, err)
+		}
+		if err := db.Create(&xray.ClientTraffic{Email: clients[i].Email}).Error; err != nil {
+			t.Fatalf("create traffic %s: %v", clients[i].Email, err)
+		}
+	}
+
+	before := time.Now().UnixMilli()
+	if err := (&SubService{}).RecordSubscriptionFetch("sub-alpha"); err != nil {
+		t.Fatalf("RecordSubscriptionFetch: %v", err)
+	}
+
+	var alpha, bravo xray.ClientTraffic
+	if err := db.Where("email = ?", "alpha@example.com").First(&alpha).Error; err != nil {
+		t.Fatalf("load alpha traffic: %v", err)
+	}
+	if err := db.Where("email = ?", "bravo@example.com").First(&bravo).Error; err != nil {
+		t.Fatalf("load bravo traffic: %v", err)
+	}
+	if alpha.LastSubFetch < before {
+		t.Fatalf("alpha lastSubFetch = %d, want >= %d", alpha.LastSubFetch, before)
+	}
+	if bravo.LastSubFetch != 0 {
+		t.Fatalf("bravo lastSubFetch = %d, want 0", bravo.LastSubFetch)
+	}
+
+	if err := (&SubService{}).RecordSubscriptionFetch("unknown"); err != nil {
+		t.Fatalf("unknown subId: %v", err)
+	}
+	if err := (&SubService{}).RecordSubscriptionFetch(""); err != nil {
+		t.Fatalf("empty subId: %v", err)
+	}
+}
+
+func TestRecordSubscriptionFetchStatusGate(t *testing.T) {
+	initSubDB(t)
+	db := database.GetDB()
+	client := &model.ClientRecord{Email: "alpha@example.com", SubID: "sub-alpha", Enable: true}
+	if err := db.Create(client).Error; err != nil {
+		t.Fatalf("create client: %v", err)
+	}
+	if err := db.Create(&xray.ClientTraffic{Email: client.Email}).Error; err != nil {
+		t.Fatalf("create traffic: %v", err)
+	}
+
+	controller := &SUBController{subService: &SubService{}}
+	notFoundRecorder := httptest.NewRecorder()
+	notFound, _ := gin.CreateTestContext(notFoundRecorder)
+	notFound.Request = httptest.NewRequest(http.MethodGet, "/sub/sub-alpha", nil)
+	notFound.Params = gin.Params{{Key: "subid", Value: "sub-alpha"}}
+	notFound.Status(http.StatusNotFound)
+	controller.recordSubscriptionFetch(notFound)
+
+	var traffic xray.ClientTraffic
+	if err := db.Where("email = ?", client.Email).First(&traffic).Error; err != nil {
+		t.Fatalf("load traffic after 404: %v", err)
+	}
+	if traffic.LastSubFetch != 0 {
+		t.Fatalf("404 updated lastSubFetch to %d", traffic.LastSubFetch)
+	}
+
+	okRecorder := httptest.NewRecorder()
+	ok, _ := gin.CreateTestContext(okRecorder)
+	ok.Request = httptest.NewRequest(http.MethodGet, "/sub/sub-alpha", nil)
+	ok.Params = gin.Params{{Key: "subid", Value: "sub-alpha"}}
+	ok.Status(http.StatusOK)
+	controller.recordSubscriptionFetch(ok)
+	if err := db.Where("email = ?", client.Email).First(&traffic).Error; err != nil {
+		t.Fatalf("load traffic after 200: %v", err)
+	}
+	if traffic.LastSubFetch == 0 {
+		t.Fatal("200 did not update lastSubFetch")
+	}
+}