feat(protocol/http, mcpserver, download): add checksum verification, MCP speed tool, pause webhook, and CLI flags (#1542)

pkg/download/downloader.go

@@ -1912,6 +1912,7 @@ func (d *Downloader) doPause(task *Task) (err error) {
 	}
 	if handled {
 		d.emit(EventKeyPause, task)
+		d.triggerWebhooks(WebhookEventDownloadPause, task, nil)
 	}
 	return nil
 }

pkg/download/model.go

@@ -23,6 +23,9 @@ type ResolveResult struct {
 	Res *base.Resource `json:"res"`
 }
 
+// Task represents a download unit.
+// Options flow path:
+// REST Request (model.CreateTask/ResolveTask) -> pkg/download Downloader -> Task.Meta.Opts (base.Options) -> Fetcher.Resolve/Start (e.g. internal/protocol/http/fetcher.go)
 type Task struct {
 	ID        string               `json:"id"`
 	Protocol  string               `json:"protocol"`

pkg/download/webhook.go

@@ -21,6 +21,7 @@ type WebhookEvent string
 const (
 	WebhookEventDownloadDone  WebhookEvent = "DOWNLOAD_DONE"
 	WebhookEventDownloadError WebhookEvent = "DOWNLOAD_ERROR"
+	WebhookEventDownloadPause WebhookEvent = "DOWNLOAD_PAUSE"
 )
 
 // WebhookData is the data sent to webhook URLs

pkg/download/webhook_test.go

@@ -814,6 +814,49 @@ func TestWebhook_TestWebhookUrl_VerifyTestPayload(t *testing.T) {
 	})
 }
 
+func TestWebhook_TriggerOnPause(t *testing.T) {
+	receivedData := make(chan *WebhookData, 1)
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		var data WebhookData
+		if err := json.NewDecoder(r.Body).Decode(&data); err != nil {
+			t.Errorf("Failed to decode data: %v", err)
+			return
+		}
+		receivedData <- &data
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer server.Close()
+
+	setupWebhookTest(t, func(downloader *Downloader) {
+		cfg, _ := downloader.GetConfig()
+		cfg.Webhook = &base.WebhookConfig{
+			Enable: true,
+			URLs:   []string{server.URL},
+		}
+		downloader.PutConfig(cfg)
+
+		task := NewTask()
+		task.Protocol = "http"
+		task.Meta = &mockFetcherMeta
+
+		downloader.triggerWebhooks(WebhookEventDownloadPause, task, nil)
+
+		select {
+		case data := <-receivedData:
+			if data.Event != WebhookEventDownloadPause {
+				t.Errorf("Expected event 'DOWNLOAD_PAUSE', got '%s'", data.Event)
+			}
+			if data.Payload == nil || data.Payload.Task == nil {
+				t.Error("Expected payload.task to be present")
+			} else if data.Payload.Task.ID != task.ID {
+				t.Errorf("Expected task ID '%s', got '%s'", task.ID, data.Payload.Task.ID)
+			}
+		case <-time.After(2 * time.Second):
+			t.Error("Timeout waiting for webhook")
+		}
+	})
+}
+
 func setupWebhookTest(t *testing.T, fn func(downloader *Downloader)) {
 	defaultDownloader.Setup()
 	defaultDownloader.cfg.StorageDir = ".test_storage"

pkg/mcpserver/server.go

@@ -12,6 +12,7 @@ import (
 
 	"github.com/GopeedLab/gopeed/pkg/base"
 	"github.com/GopeedLab/gopeed/pkg/download"
+	phttp "github.com/GopeedLab/gopeed/pkg/protocol/http"
 	"github.com/google/jsonschema-go/jsonschema"
 	"github.com/modelcontextprotocol/go-sdk/mcp"
 )
@@ -65,12 +66,13 @@ type btRequestExtra struct {
 }
 
 type httpTaskExtra struct {
-	Connections                int    `json:"connections,omitempty" jsonschema:"Number of HTTP download connections"`
-	AutoTorrent                *bool  `json:"autoTorrent,omitempty" jsonschema:"Automatically create a BitTorrent task after downloading a torrent file"`
-	DeleteTorrentAfterDownload *bool  `json:"deleteTorrentAfterDownload,omitempty" jsonschema:"Delete the torrent file after automatically creating its BitTorrent task"`
-	AutoExtract                *bool  `json:"autoExtract,omitempty" jsonschema:"Automatically extract the downloaded archive"`
-	ArchivePassword            string `json:"archivePassword,omitempty" jsonschema:"Password for an encrypted archive"`
-	DeleteAfterExtract         bool   `json:"deleteAfterExtract,omitempty" jsonschema:"Delete archive files after successful extraction"`
+	Connections                int             `json:"connections,omitempty" jsonschema:"Number of HTTP download connections"`
+	AutoTorrent                *bool           `json:"autoTorrent,omitempty" jsonschema:"Automatically create a BitTorrent task after downloading a torrent file"`
+	DeleteTorrentAfterDownload *bool           `json:"deleteTorrentAfterDownload,omitempty" jsonschema:"Delete the torrent file after automatically creating its BitTorrent task"`
+	AutoExtract                *bool           `json:"autoExtract,omitempty" jsonschema:"Automatically extract the downloaded archive"`
+	ArchivePassword            string          `json:"archivePassword,omitempty" jsonschema:"Password for an encrypted archive"`
+	DeleteAfterExtract         bool            `json:"deleteAfterExtract,omitempty" jsonschema:"Delete archive files after successful extraction"`
+	Checksum                   *checksumOption `json:"checksum,omitempty" jsonschema:"Optional checksum verification settings"`
 }
 
 // downloadRequest is the MCP-facing form of base.Request. The REST model uses
@@ -129,6 +131,11 @@ func isBitTorrentRequest(rawURL string) bool {
 		strings.HasPrefix(upperURL, "DATA:APPLICATION/X-BITTORRENT;BASE64,")
 }
 
+type checksumOption struct {
+	Algorithm string `json:"algorithm" jsonschema:"Checksum algorithm: md5, sha1, or sha256"`
+	Expected  string `json:"expected" jsonschema:"Expected hex-encoded checksum hash"`
+}
+
 // downloadOptions is the MCP-facing form of base.Options. Only HTTP currently
 // defines protocol-specific task options, so Extra has one concrete schema.
 type downloadOptions struct {
@@ -186,12 +193,31 @@ func (o *downloadOptions) baseOptions() *base.Options {
 	if o == nil {
 		return nil
 	}
+	var extra any
+	if o.Extra != nil {
+		var checksum *phttp.ChecksumOption
+		if o.Extra.Checksum != nil {
+			checksum = &phttp.ChecksumOption{
+				Algorithm: o.Extra.Checksum.Algorithm,
+				Expected:  o.Extra.Checksum.Expected,
+			}
+		}
+		extra = &phttp.OptsExtra{
+			Connections:                o.Extra.Connections,
+			AutoTorrent:                o.Extra.AutoTorrent,
+			DeleteTorrentAfterDownload: o.Extra.DeleteTorrentAfterDownload,
+			AutoExtract:                o.Extra.AutoExtract,
+			ArchivePassword:            o.Extra.ArchivePassword,
+			DeleteAfterExtract:         o.Extra.DeleteAfterExtract,
+			Checksum:                   checksum,
+		}
+	}
 	return &base.Options{
 		Name:          o.Name,
 		Path:          o.Path,
 		AsDefaultPath: o.AsDefaultPath,
 		SelectFiles:   o.SelectFiles,
-		Extra:         o.Extra,
+		Extra:         extra,
 	}
 }
 
@@ -270,6 +296,13 @@ type getTaskStatsOutput struct {
 	Stats any `json:"stats"`
 }
 
+type getDownloadSpeedInput struct{}
+
+type getDownloadSpeedOutput struct {
+	TotalSpeed      int64 `json:"totalSpeed"`
+	ActiveTaskCount int   `json:"activeTaskCount"`
+}
+
 type taskActionOutput struct {
 	ID      string `json:"id"`
 	Success bool   `json:"success"`
@@ -416,6 +449,33 @@ func registerTools(server *mcp.Server, downloader *download.Downloader) {
 		return nil, &getTaskStatsOutput{Stats: stats}, nil
 	})
 
+	mcp.AddTool(server, &mcp.Tool{
+		Name:        "get_download_speed",
+		Title:       "Get download speed",
+		Description: "Returns the combined download speed across all currently active tasks and how many tasks are actively downloading. Use get_task_status instead if you need the speed, progress, or ETA of one specific task.",
+		Annotations: &mcp.ToolAnnotations{ReadOnlyHint: true, OpenWorldHint: &closedWorld},
+	}, func(_ context.Context, _ *mcp.CallToolRequest, _ *getDownloadSpeedInput) (*mcp.CallToolResult, *getDownloadSpeedOutput, error) {
+		allTasks := downloader.GetTasks()
+		var totalSpeed int64
+		activeCount := 0
+
+		for _, task := range allTasks {
+			status, err := downloader.RuntimeStatus(task.ID)
+			if err != nil {
+				continue
+			}
+			if status.Status == base.DownloadStatusRunning {
+				activeCount++
+				totalSpeed += status.Speed
+			}
+		}
+
+		return nil, &getDownloadSpeedOutput{
+			TotalSpeed:      totalSpeed,
+			ActiveTaskCount: activeCount,
+		}, nil
+	})
+
 	registerTaskAction(server, downloader, "pause_task", "Pause task", "Pause one Gopeed task.", &nondestructive, &closedWorld, downloader.Pause)
 	registerTaskAction(server, downloader, "continue_task", "Continue task", "Continue a paused or failed Gopeed task.", &nondestructive, &openWorld, downloader.Continue)
 

pkg/mcpserver/server_test.go

@@ -64,6 +64,7 @@ func TestStreamableHTTPTools(t *testing.T) {
 		"continue_task",
 		"create_task",
 		"delete_task",
+		"get_download_speed",
 		"get_task",
 		"get_task_stats",
 		"get_task_status",

pkg/mcpserver/speed_test.go

@@ -0,0 +1,103 @@
+package mcpserver
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/GopeedLab/gopeed/pkg/base"
+	"github.com/GopeedLab/gopeed/pkg/download"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+func TestGetDownloadSpeedTool(t *testing.T) {
+	// Serve a test payload that takes a little bit of time or streams bytes
+	testServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Length", "1048576")
+		w.WriteHeader(http.StatusOK)
+		chunk := make([]byte, 8192)
+		for i := 0; i < 128; i++ {
+			_, _ = w.Write(chunk)
+			time.Sleep(10 * time.Millisecond)
+		}
+	}))
+	defer testServer.Close()
+
+	downloader := download.NewDownloader(&download.DownloaderConfig{
+		Storage:    download.NewMemStorage(),
+		StorageDir: t.TempDir(),
+	})
+	if err := downloader.Setup(); err != nil {
+		t.Fatal(err)
+	}
+	defer downloader.Close()
+
+	httpServer := httptest.NewServer(NewHandler(downloader))
+	defer httpServer.Close()
+
+	client := mcp.NewClient(&mcp.Implementation{Name: "gopeed-test", Version: "1.0.0"}, nil)
+	session, err := client.Connect(context.Background(), &mcp.StreamableClientTransport{Endpoint: httpServer.URL}, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer session.Close()
+
+	// 1. Zero tasks test (returns 0 totalSpeed and 0 activeTaskCount)
+	result, err := session.CallTool(context.Background(), &mcp.CallToolParams{
+		Name:      "get_download_speed",
+		Arguments: map[string]any{},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if result.IsError {
+		t.Fatalf("get_download_speed returned error: %+v", result.Content)
+	}
+	structured, ok := result.StructuredContent.(map[string]any)
+	if !ok {
+		t.Fatalf("structured content type = %T", result.StructuredContent)
+	}
+	if activeCount, ok := structured["activeTaskCount"].(float64); !ok || activeCount != 0 {
+		t.Fatalf("activeTaskCount = %v, want 0", structured["activeTaskCount"])
+	}
+	if totalSpeed, ok := structured["totalSpeed"].(float64); !ok || totalSpeed != 0 {
+		t.Fatalf("totalSpeed = %v, want 0", structured["totalSpeed"])
+	}
+
+	// 2. Start a real download task
+	taskID, err := downloader.CreateDirect(&base.Request{
+		URL: testServer.URL,
+	}, &base.Options{
+		Path: t.TempDir(),
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer func() {
+		_ = downloader.Delete(&download.TaskFilter{IDs: []string{taskID}}, true)
+	}()
+
+	// Query get_download_speed while downloading
+	result, err = session.CallTool(context.Background(), &mcp.CallToolParams{
+		Name:      "get_download_speed",
+		Arguments: map[string]any{},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if result.IsError {
+		t.Fatalf("get_download_speed returned error: %+v", result.Content)
+	}
+	structured, ok = result.StructuredContent.(map[string]any)
+	if !ok {
+		t.Fatalf("structured content type = %T", result.StructuredContent)
+	}
+	if _, ok := structured["activeTaskCount"].(float64); !ok {
+		t.Fatalf("activeTaskCount missing or wrong type: %v", structured["activeTaskCount"])
+	}
+	if _, ok := structured["totalSpeed"].(float64); !ok {
+		t.Fatalf("totalSpeed missing or wrong type: %v", structured["totalSpeed"])
+	}
+}

pkg/protocol/http/model.go

@@ -1,11 +1,83 @@
 package http
 
+import (
+	"encoding/hex"
+	"fmt"
+	"strings"
+)
+
 type ReqExtra struct {
 	Method string            `json:"method"`
 	Header map[string]string `json:"header"`
 	Body   string            `json:"body"`
 }
 
+// ChecksumOption specifies an expected checksum to verify against
+// the completed download. Only supported for HTTP downloads.
+type ChecksumOption struct {
+	Algorithm string `json:"algorithm"` // "md5" | "sha1" | "sha256"
+	Expected  string `json:"expected"`  // hex-encoded expected hash
+}
+
+// IsEmpty returns true when chk is nil, or when both Algorithm and Expected
+// are blank after trimming whitespace.
+func (chk *ChecksumOption) IsEmpty() bool {
+	if chk == nil {
+		return true
+	}
+	return strings.TrimSpace(chk.Algorithm) == "" && strings.TrimSpace(chk.Expected) == ""
+}
+
+// NormalizedAlgorithm returns the canonical lower-cased algorithm ("md5", "sha1", "sha256")
+// and true if recognized, or ("", false) if unsupported.
+func (chk *ChecksumOption) NormalizedAlgorithm() (string, bool) {
+	if chk == nil {
+		return "", false
+	}
+	switch strings.ToLower(strings.TrimSpace(chk.Algorithm)) {
+	case "md5":
+		return "md5", true
+	case "sha1", "sha-1":
+		return "sha1", true
+	case "sha256", "sha-256":
+		return "sha256", true
+	default:
+		return "", false
+	}
+}
+
+// Validate checks whether the checksum option is valid.
+// Empty options return nil (no verification).
+func (chk *ChecksumOption) Validate() error {
+	if chk.IsEmpty() {
+		return nil
+	}
+	algo, ok := chk.NormalizedAlgorithm()
+	if !ok {
+		return fmt.Errorf("unsupported checksum algorithm: %s", chk.Algorithm)
+	}
+	expected := strings.TrimSpace(chk.Expected)
+	if expected == "" {
+		return fmt.Errorf("checksum expected hash is required when algorithm is set")
+	}
+	var expectedLen int
+	switch algo {
+	case "md5":
+		expectedLen = 32
+	case "sha1":
+		expectedLen = 40
+	case "sha256":
+		expectedLen = 64
+	}
+	if len(expected) != expectedLen {
+		return fmt.Errorf("invalid checksum hash length for %s: expected %d characters, got %d", algo, expectedLen, len(expected))
+	}
+	if _, err := hex.DecodeString(expected); err != nil {
+		return fmt.Errorf("invalid checksum hash for %s: expected valid hexadecimal string", algo)
+	}
+	return nil
+}
+
 type OptsExtra struct {
 	Connections int `json:"connections"`
 	// AutoTorrent when task download complete, and it is a .torrent file, it will be auto create a new task for the torrent file
@@ -21,6 +93,8 @@ type OptsExtra struct {
 	ArchivePassword string `json:"archivePassword"`
 	// DeleteAfterExtract when true, deletes the archive file after successful extraction
 	DeleteAfterExtract bool `json:"deleteAfterExtract"`
+	// Checksum verifies the completed file against an expected hash after download
+	Checksum *ChecksumOption `json:"checksum,omitempty"`
 }
 
 // Stats for download

pkg/protocol/http/model_test.go

@@ -0,0 +1,162 @@
+package http
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestOptsExtra_Checksum(t *testing.T) {
+	extra := &OptsExtra{
+		Checksum: &ChecksumOption{
+			Algorithm: "sha256",
+			Expected:  "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
+		},
+	}
+	if extra.Checksum.Algorithm != "sha256" || extra.Checksum.Expected != "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" {
+		t.Fatalf("unexpected checksum: %+v", extra.Checksum)
+	}
+}
+
+func TestChecksumOption_Validate(t *testing.T) {
+	validMd5 := "0123456789abcdef0123456789abcdef"
+	validSha1 := "0123456789abcdef0123456789abcdef01234567"
+	validSha256 := "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+
+	tests := []struct {
+		name      string
+		option    *ChecksumOption
+		wantErr   bool
+		errSubstr string
+	}{
+		{
+			name:    "nil option",
+			option:  nil,
+			wantErr: false,
+		},
+		{
+			name:    "empty option (empty strings)",
+			option:  &ChecksumOption{Algorithm: "", Expected: ""},
+			wantErr: false,
+		},
+		{
+			name:    "empty option (whitespace strings)",
+			option:  &ChecksumOption{Algorithm: "   ", Expected: "   "},
+			wantErr: false,
+		},
+		{
+			name:    "valid md5 lowercase",
+			option:  &ChecksumOption{Algorithm: "md5", Expected: validMd5},
+			wantErr: false,
+		},
+		{
+			name:    "valid md5 uppercase",
+			option:  &ChecksumOption{Algorithm: "MD5", Expected: strings.ToUpper(validMd5)},
+			wantErr: false,
+		},
+		{
+			name:    "valid sha1 lowercase",
+			option:  &ChecksumOption{Algorithm: "sha1", Expected: validSha1},
+			wantErr: false,
+		},
+		{
+			name:    "valid sha-1 alias",
+			option:  &ChecksumOption{Algorithm: "SHA-1", Expected: strings.ToUpper(validSha1)},
+			wantErr: false,
+		},
+		{
+			name:    "valid sha256 lowercase",
+			option:  &ChecksumOption{Algorithm: "sha256", Expected: validSha256},
+			wantErr: false,
+		},
+		{
+			name:    "valid sha-256 alias",
+			option:  &ChecksumOption{Algorithm: "sha-256", Expected: validSha256},
+			wantErr: false,
+		},
+		{
+			name:    "valid sha256 with whitespace around hash and algorithm",
+			option:  &ChecksumOption{Algorithm: "  sha256  ", Expected: "  " + validSha256 + "  "},
+			wantErr: false,
+		},
+		{
+			name:      "unknown algorithm",
+			option:    &ChecksumOption{Algorithm: "crc32", Expected: "12345678"},
+			wantErr:   true,
+			errSubstr: "unsupported checksum algorithm",
+		},
+		{
+			name:      "algorithm set but hash blank",
+			option:    &ChecksumOption{Algorithm: "sha256", Expected: "   "},
+			wantErr:   true,
+			errSubstr: "checksum expected hash is required",
+		},
+		{
+			name:      "sha256 with abc (short length)",
+			option:    &ChecksumOption{Algorithm: "sha256", Expected: "abc"},
+			wantErr:   true,
+			errSubstr: "expected 64 characters, got 3",
+		},
+		{
+			name:      "sha256 with 64 x g (non-hex)",
+			option:    &ChecksumOption{Algorithm: "sha256", Expected: strings.Repeat("g", 64)},
+			wantErr:   true,
+			errSubstr: "expected valid hexadecimal string",
+		},
+		{
+			name:      "sha256 with 63 x a (off-by-one short)",
+			option:    &ChecksumOption{Algorithm: "sha256", Expected: strings.Repeat("a", 63)},
+			wantErr:   true,
+			errSubstr: "expected 64 characters, got 63",
+		},
+		{
+			name:      "sha256 with 65 x a (off-by-one long)",
+			option:    &ChecksumOption{Algorithm: "sha256", Expected: strings.Repeat("a", 65)},
+			wantErr:   true,
+			errSubstr: "expected 64 characters, got 65",
+		},
+		{
+			name:      "md5 with 31 chars",
+			option:    &ChecksumOption{Algorithm: "md5", Expected: strings.Repeat("a", 31)},
+			wantErr:   true,
+			errSubstr: "expected 32 characters, got 31",
+		},
+		{
+			name:      "md5 with 33 chars",
+			option:    &ChecksumOption{Algorithm: "md5", Expected: strings.Repeat("a", 33)},
+			wantErr:   true,
+			errSubstr: "expected 32 characters, got 33",
+		},
+		{
+			name:      "md5 with sha256-length hash (64 chars)",
+			option:    &ChecksumOption{Algorithm: "md5", Expected: validSha256},
+			wantErr:   true,
+			errSubstr: "expected 32 characters, got 64",
+		},
+		{
+			name:      "sha1 with 39 chars",
+			option:    &ChecksumOption{Algorithm: "sha1", Expected: strings.Repeat("a", 39)},
+			wantErr:   true,
+			errSubstr: "expected 40 characters, got 39",
+		},
+		{
+			name:      "sha1 with 41 chars",
+			option:    &ChecksumOption{Algorithm: "sha1", Expected: strings.Repeat("a", 41)},
+			wantErr:   true,
+			errSubstr: "expected 40 characters, got 41",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			err := tt.option.Validate()
+			if (err != nil) != tt.wantErr {
+				t.Fatalf("Validate() error = %v, wantErr %v", err, tt.wantErr)
+			}
+			if tt.wantErr && tt.errSubstr != "" {
+				if err == nil || !strings.Contains(err.Error(), tt.errSubstr) {
+					t.Fatalf("Validate() error = %v, want substring %q", err, tt.errSubstr)
+				}
+			}
+		})
+	}
+}