feat(cli): more doc, refactored iterator

cli/_examples/init/main.go

@@ -22,6 +22,7 @@ import (
 	"math/big"
 
 	"github.com/deepsquare-io/grid/cli/deepsquare"
+	"github.com/deepsquare-io/grid/cli/types"
 	"github.com/ethereum/go-ethereum/common"
 	"github.com/ethereum/go-ethereum/crypto"
 )
@@ -76,12 +77,20 @@ func watcherExample(ctx context.Context) {
 	}
 	defer watcher.Close()
 
-	// Test the client by checking the balance
-	watcher.SubscribeEvents()
+	// Test the watcher
+	ch := make(chan types.NewJobRequest, 1)
+	defer close(ch)
+	sub, err := watcher.SubscribeEvents(ctx, types.FilterNewJobRequest(ch))
+	if err != nil {
+		log.Fatalln(err.Error())
+	}
+	defer sub.Unsubscribe()
 
+	// TODO: handle events
 }
 
 func main() {
 	ctx := context.Background()
 	clientExample(ctx)
+	watcherExample(ctx)
 }

cli/_examples/jobs/main.go

@@ -0,0 +1,64 @@
+// Copyright (C) 2023 DeepSquare Association
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Lesser General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+
+	"github.com/deepsquare-io/grid/cli/deepsquare"
+	"github.com/ethereum/go-ethereum/common"
+	"github.com/ethereum/go-ethereum/crypto"
+)
+
+func main() {
+	ctx := context.Background()
+	pk, err := crypto.GenerateKey()
+	if err != nil {
+		log.Fatalln(err.Error())
+	}
+
+	// Initialize the client
+	client, err := deepsquare.NewClient(ctx, &deepsquare.ClientConfig{
+		MetaschedulerAddress: common.HexToAddress("0x48af46ee836514551886bbC3b5920Eba81126F62"),
+		UserPrivateKey:       pk, // Optional, but needed for authenticated requests
+		// RPCEndpoint:          "https://testnet.deepsquare.run/rpc",    // Optional
+		// SBatchEndpoint:       "https://sbatch.deepsquare.run/graphql", // Optional
+		// LoggerEndpoint:       "https://grid-logger.deepsquare.run",    // Optional
+	})
+	if err != nil {
+		log.Fatalln(err.Error())
+	}
+
+	// Get our jobs
+	jobs, err := client.GetJobs(ctx)
+	if err != nil {
+		log.Fatalln(err.Error())
+	}
+
+	// Iterate
+	for jobs.Next(ctx) {
+		fmt.Println(jobs.Current())
+	}
+
+	// Handle error
+	if jobs.Error() != nil {
+		if err != nil {
+			log.Fatalln(err.Error())
+		}
+	}
+}

cli/_examples/submit/main.go

@@ -0,0 +1,83 @@
+// Copyright (C) 2023 DeepSquare Association
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Lesser General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+package main
+
+import (
+	"context"
+	"log"
+	"math/big"
+	"strings"
+
+	"github.com/deepsquare-io/grid/cli/deepsquare"
+	"github.com/deepsquare-io/grid/cli/sbatch"
+	"github.com/ethereum/go-ethereum/common"
+	"github.com/ethereum/go-ethereum/crypto"
+)
+
+func main() {
+	ctx := context.Background()
+	pk, err := crypto.GenerateKey()
+	if err != nil {
+		log.Fatalln(err.Error())
+	}
+
+	// Initialize the client
+	client, err := deepsquare.NewClient(ctx, &deepsquare.ClientConfig{
+		MetaschedulerAddress: common.HexToAddress("0x48af46ee836514551886bbC3b5920Eba81126F62"),
+		UserPrivateKey:       pk, // Optional, but needed for authenticated requests
+		// RPCEndpoint:          "https://testnet.deepsquare.run/rpc",    // Optional
+		// SBatchEndpoint:       "https://sbatch.deepsquare.run/graphql", // Optional
+		// LoggerEndpoint:       "https://grid-logger.deepsquare.run",    // Optional
+	})
+	if err != nil {
+		log.Fatalln(err.Error())
+	}
+
+	// Submit a fake job.
+	var jobName [32]byte
+	jobNameS := "test"
+	copy(jobName[:], jobNameS)
+	_, err = client.SubmitJob(
+		ctx,
+		&sbatch.Job{
+			Resources: &sbatch.JobResources{
+				Tasks:       1,
+				CpusPerTask: 1,
+				MemPerCPU:   100,
+				GpusPerTask: 0,
+			},
+			Steps: []*sbatch.Step{
+				{
+					Run: &sbatch.StepRun{
+						Command: "echo test",
+					},
+				},
+			},
+		},
+		big.NewInt(100),
+		jobName,
+	)
+
+	// We expect an error
+	if err == nil {
+		panic("received no error")
+	}
+	if !strings.Contains(err.Error(), "insufficient funds for transfer") {
+		log.Fatalln(err.Error())
+	}
+
+	log.Printf("we've received an error '%s', but that's expected", err)
+}

cli/deepsquare/deepsquare_doc.go

@@ -60,14 +60,168 @@ The private key can be parsed with the `go-ethereum` package:
 
 # Submitting Jobs
 
+To submit jobs, simply do:
+
+	_, err = client.SubmitJob(
+		ctx,
+		&sbatch.Job{
+			Resources: &sbatch.JobResources{
+				Tasks:       1,
+				CpusPerTask: 1,
+				MemPerCPU:   100,
+				GpusPerTask: 0,
+			},
+			Steps: []*sbatch.Step{
+				{
+					Run: &sbatch.StepRun{
+						Command: "echo test",
+					},
+				},
+			},
+		},
+		big.NewInt(100),
+		jobName,
+	)
+
+The object `sbatch.Job` has `json` and `yaml` tags, so it's possible to unmarshall a JSON object to an sbatch.Job.
+
 # Managing Jobs
 
+Get a job:
+
+	job, err := client.GetJob(ctx, jobID)
+
+Get your jobs:
+
+	jobs, err := client.GetJobs(ctx)
+	if err != nil {
+		log.Fatalln(err.Error())
+	}
+
+	// Iterate
+	for jobs.Next(ctx) {
+		fmt.Println(jobs.Current())
+	}
+
+	// Handle error
+	if jobs.Error() != nil {
+		if err != nil {
+			log.Fatalln(err.Error())
+		}
+	}
+
+Top-up a job:
+
+	err := client.TopUpJob(ctx, jobID, amount)
+
+Panicking a job (only for admins):
+
+	err := client.PanicJob(ctx, jobID, reason)
+
 # Managing Allowance
 
+To get, do:
+
+	allowance, err := client.GetAllowance(ctx)
+
+To set, do:
+
+	err := client.SetAllowance(ctx, amount)
+
+To watch, do:
+
+	approvals := make(chan types.Approval, 1)
+		sub, err := m.watcher.SubscribeEvents(
+			ctx,
+			types.FilterApproval(approvals),
+		)
+		if err != nil {
+			// ...
+		}
+		defer sub.Unsubscribe()
+
+		allowances, err := m.client.ReduceToAllowance(ctx, approvals)
+
+		for {
+			select {
+			case allowance := <-allowances:
+				// Handle allowance
+
+			case err := <-sub.Err():
+				// Handle error
+			}
+		}
+
 # Managing Credits
 
-# Managing Providers
+To get, do:
+
+	credits, err := client.Balance(ctx)
+	// Or
+	credits, err := client.BalanceOf(ctx, address)
+
+To transfer, do:
+
+	err := client.Transfer(ctx, address, amount)
+
+To watch, do:
+
+	transfers := make(chan types.Transfer, 1)
+	sub, err := m.watcher.SubscribeEvents(
+		ctx,
+		types.FilterTransfer(transfers),
+	)
+	if err != nil {
+		// ...
+	}
+	defer sub.Unsubscribe()
+
+	balances, err := m.client.ReduceToBalance(ctx, transfers)
+
+	for {
+		select {
+		case balance := <-balances:
+			// Handle balance
+
+		case err := <-sub.Err():
+			// Handle error
+		}
+	}
+
+# Managing Providers (for admins)
+
+To get, do:
+
+	provider, err := client.GetProvider(ctx, providerAddress)
+
+To list all providers, do:
+
+	providers, err := client.GetProviders(ctx, providerAddress)
+
+To approve, do:
+
+	err := client.Approve(ctx, providerAddress)
+
+To remove, do:
+
+	err := client.Remove(ctx, providerAddress)
 
 # Watching events
+
+To watch the events, the watcher has a `SubscribeEvents` method in which you can pass filters:
+
+	transfers := make(chan types.Transfer, 1)
+	sub, err := m.watcher.SubscribeEvents(
+		ctx,
+		types.FilterTransfer(transfers),
+	)
+	if err != nil {
+		// ...
+	}
+	defer sub.Unsubscribe()
+
+A thread will be handling the passing of data to the channels.
+
+Call `sub.Unsubscribe()` to stop the subscription, and use `<-sub.Err()` to fetch the error.
 */
 package deepsquare