From 6ced549deaecb42b9bb93ea9efcb4c1bbaabe8a4 Mon Sep 17 00:00:00 2001 From: mhsanaei Date: Sat, 20 Sep 2025 09:35:50 +0200 Subject: docs: add comments for all functions --- web/job/check_client_ip_job.go | 2 ++ web/job/check_cpu_usage.go | 4 +++- web/job/check_hash_storage.go | 4 +++- web/job/check_xray_running_job.go | 8 ++++++-- web/job/clear_logs_job.go | 2 ++ web/job/periodic_traffic_reset_job.go | 4 ++++ web/job/stats_notify_job.go | 9 ++++++--- web/job/xray_traffic_job.go | 3 +++ 8 files changed, 29 insertions(+), 7 deletions(-) (limited to 'web/job') diff --git a/web/job/check_client_ip_job.go b/web/job/check_client_ip_job.go index 7704e10d..e783a6df 100644 --- a/web/job/check_client_ip_job.go +++ b/web/job/check_client_ip_job.go @@ -18,6 +18,7 @@ import ( "github.com/mhsanaei/3x-ui/v2/xray" ) +// CheckClientIpJob monitors client IP addresses from access logs and manages IP blocking based on configured limits. type CheckClientIpJob struct { lastClear int64 disAllowedIps []string @@ -25,6 +26,7 @@ type CheckClientIpJob struct { var job *CheckClientIpJob +// NewCheckClientIpJob creates a new client IP monitoring job instance. func NewCheckClientIpJob() *CheckClientIpJob { job = new(CheckClientIpJob) return job diff --git a/web/job/check_cpu_usage.go b/web/job/check_cpu_usage.go index 5cb9a21e..2ea87747 100644 --- a/web/job/check_cpu_usage.go +++ b/web/job/check_cpu_usage.go @@ -9,16 +9,18 @@ import ( "github.com/shirou/gopsutil/v4/cpu" ) +// CheckCpuJob monitors CPU usage and sends Telegram notifications when usage exceeds the configured threshold. type CheckCpuJob struct { tgbotService service.Tgbot settingService service.SettingService } +// NewCheckCpuJob creates a new CPU monitoring job instance. func NewCheckCpuJob() *CheckCpuJob { return new(CheckCpuJob) } -// Here run is a interface method of Job interface +// Run checks CPU usage over the last minute and sends a Telegram alert if it exceeds the threshold. func (j *CheckCpuJob) Run() { threshold, _ := j.settingService.GetTgCpu() diff --git a/web/job/check_hash_storage.go b/web/job/check_hash_storage.go index 5f826d63..2112079e 100644 --- a/web/job/check_hash_storage.go +++ b/web/job/check_hash_storage.go @@ -4,15 +4,17 @@ import ( "github.com/mhsanaei/3x-ui/v2/web/service" ) +// CheckHashStorageJob periodically cleans up expired hash entries from the Telegram bot's hash storage. type CheckHashStorageJob struct { tgbotService service.Tgbot } +// NewCheckHashStorageJob creates a new hash storage cleanup job instance. func NewCheckHashStorageJob() *CheckHashStorageJob { return new(CheckHashStorageJob) } -// Here Run is an interface method of the Job interface +// Run removes expired hash entries from the Telegram bot's hash storage. func (j *CheckHashStorageJob) Run() { // Remove expired hashes from storage j.tgbotService.GetHashStorage().RemoveExpiredHashes() diff --git a/web/job/check_xray_running_job.go b/web/job/check_xray_running_job.go index 8f5f0889..5b53b0c6 100644 --- a/web/job/check_xray_running_job.go +++ b/web/job/check_xray_running_job.go @@ -1,3 +1,5 @@ +// Package job provides background job implementations for the 3x-ui web panel, +// including traffic monitoring, system checks, and periodic maintenance tasks. package job import ( @@ -5,16 +7,18 @@ import ( "github.com/mhsanaei/3x-ui/v2/web/service" ) +// CheckXrayRunningJob monitors Xray process health and restarts it if it crashes. type CheckXrayRunningJob struct { xrayService service.XrayService - - checkTime int + checkTime int } +// NewCheckXrayRunningJob creates a new Xray health check job instance. func NewCheckXrayRunningJob() *CheckXrayRunningJob { return new(CheckXrayRunningJob) } +// Run checks if Xray has crashed and restarts it after confirming it's down for 2 consecutive checks. func (j *CheckXrayRunningJob) Run() { if !j.xrayService.DidXrayCrash() { j.checkTime = 0 diff --git a/web/job/clear_logs_job.go b/web/job/clear_logs_job.go index 70e03688..85e0d64a 100644 --- a/web/job/clear_logs_job.go +++ b/web/job/clear_logs_job.go @@ -9,8 +9,10 @@ import ( "github.com/mhsanaei/3x-ui/v2/xray" ) +// ClearLogsJob clears old log files to prevent disk space issues. type ClearLogsJob struct{} +// NewClearLogsJob creates a new log cleanup job instance. func NewClearLogsJob() *ClearLogsJob { return new(ClearLogsJob) } diff --git a/web/job/periodic_traffic_reset_job.go b/web/job/periodic_traffic_reset_job.go index 65aefb9d..6a370a51 100644 --- a/web/job/periodic_traffic_reset_job.go +++ b/web/job/periodic_traffic_reset_job.go @@ -5,19 +5,23 @@ import ( "github.com/mhsanaei/3x-ui/v2/web/service" ) +// Period represents the time period for traffic resets. type Period string +// PeriodicTrafficResetJob resets traffic statistics for inbounds based on their configured reset period. type PeriodicTrafficResetJob struct { inboundService service.InboundService period Period } +// NewPeriodicTrafficResetJob creates a new periodic traffic reset job for the specified period. func NewPeriodicTrafficResetJob(period Period) *PeriodicTrafficResetJob { return &PeriodicTrafficResetJob{ period: period, } } +// Run resets traffic statistics for all inbounds that match the configured reset period. func (j *PeriodicTrafficResetJob) Run() { inbounds, err := j.inboundService.GetInboundsByTrafficReset(string(j.period)) if err != nil { diff --git a/web/job/stats_notify_job.go b/web/job/stats_notify_job.go index 0d0907e0..b93f05cb 100644 --- a/web/job/stats_notify_job.go +++ b/web/job/stats_notify_job.go @@ -4,23 +4,26 @@ import ( "github.com/mhsanaei/3x-ui/v2/web/service" ) +// LoginStatus represents the status of a login attempt. type LoginStatus byte const ( - LoginSuccess LoginStatus = 1 - LoginFail LoginStatus = 0 + LoginSuccess LoginStatus = 1 // Successful login + LoginFail LoginStatus = 0 // Failed login attempt ) +// StatsNotifyJob sends periodic statistics reports via Telegram bot. type StatsNotifyJob struct { xrayService service.XrayService tgbotService service.Tgbot } +// NewStatsNotifyJob creates a new statistics notification job instance. func NewStatsNotifyJob() *StatsNotifyJob { return new(StatsNotifyJob) } -// Here run is a interface method of Job interface +// Run sends a statistics report via Telegram bot if Xray is running. func (j *StatsNotifyJob) Run() { if !j.xrayService.IsXrayRunning() { return diff --git a/web/job/xray_traffic_job.go b/web/job/xray_traffic_job.go index 8ba5a9f9..a9affb4b 100644 --- a/web/job/xray_traffic_job.go +++ b/web/job/xray_traffic_job.go @@ -10,6 +10,7 @@ import ( "github.com/valyala/fasthttp" ) +// XrayTrafficJob collects and processes traffic statistics from Xray, updating the database and optionally informing external APIs. type XrayTrafficJob struct { settingService service.SettingService xrayService service.XrayService @@ -17,10 +18,12 @@ type XrayTrafficJob struct { outboundService service.OutboundService } +// NewXrayTrafficJob creates a new traffic collection job instance. func NewXrayTrafficJob() *XrayTrafficJob { return new(XrayTrafficJob) } +// Run collects traffic statistics from Xray and updates the database, triggering restart if needed. func (j *XrayTrafficJob) Run() { if !j.xrayService.IsXrayRunning() { return -- cgit v1.2.3