From 424b95d881aa497359629d5095eb3abd7b9a5431 Mon Sep 17 00:00:00 2001 From: Arnaud Date: Wed, 8 Oct 2025 09:01:03 +0200 Subject: [PATCH] Add comments and change exported functions --- codex/debug.go | 15 +++++++--- codex/p2p.go | 9 ++++-- codex/upload.go | 68 ++++++++++++++++++++------------------------ codex/upload_test.go | 8 +++--- 4 files changed, 52 insertions(+), 48 deletions(-) diff --git a/codex/debug.go b/codex/debug.go index a4f7d21..8166ddf 100644 --- a/codex/debug.go +++ b/codex/debug.go @@ -36,9 +36,14 @@ type RoutingTable struct { } type DebugInfo struct { - ID string `json:"id"` // Peer ID - Addrs []string `json:"addrs"` // Peer info addresses - Spr string `json:"spr"` // Signed Peer Record + // Peer ID + ID string `json:"id"` + + // Peer info addresses + // Specified with `ListenAddresses` in `CodexConfig` + Addrs []string `json:"addrs"` + + Spr string `json:"spr"` AnnounceAddresses []string `json:"announceAddresses"` PeersTable RoutingTable `json:"table"` } @@ -90,6 +95,9 @@ func (node CodexNode) UpdateLogLevel(logLevel string) error { return err } +// CodexPeerDebug retrieves the peer record for a given peer ID. +// This function is available only if the flag +// -d:codex_enable_api_debug_peers=true was set at build time. func (node CodexNode) CodexPeerDebug(peerId string) (PeerRecord, error) { var record PeerRecord @@ -109,6 +117,5 @@ func (node CodexNode) CodexPeerDebug(peerId string) (PeerRecord, error) { } err = json.Unmarshal([]byte(value), &record) - return record, err } diff --git a/codex/p2p.go b/codex/p2p.go index 6d1561f..62ebc92 100644 --- a/codex/p2p.go +++ b/codex/p2p.go @@ -10,10 +10,15 @@ package codex */ import "C" import ( - "log" "unsafe" ) +// Connect connects to a peer using its peer ID and optional multiaddresses. +// If `peerAddresses` param is supplied, it will be used to dial the peer, +// otherwise the `peerId` is used to invoke peer discovery, if it succeeds +// the returned addresses will be used to dial. +// `peerAddresses` the listening addresses of the peers to dial, +// eg the one specified with `ListenAddresses` in `CodexConfig`. func (node CodexNode) Connect(peerId string, peerAddresses []string) error { bridge := newBridgeCtx() defer bridge.free() @@ -28,8 +33,6 @@ func (node CodexNode) Connect(peerId string, peerAddresses []string) error { defer C.free(unsafe.Pointer(cAddresses[i])) } - log.Println("peerAddresses", cAddresses) - if C.cGoCodexConnect(node.ctx, cPeerId, &cAddresses[0], C.uintptr_t(len(peerAddresses)), bridge.resp) != C.RET_OK { return bridge.callError("cGoCodexConnect") } diff --git a/codex/upload.go b/codex/upload.go index f816a5e..7b15638 100644 --- a/codex/upload.go +++ b/codex/upload.go @@ -35,11 +35,11 @@ import ( const defaultBlockSize = 1024 * 64 -type OnUploadProgressFunc func(read, total int, percent float64, err error) +type onUploadProgressFunc func(read, total int, percent float64, err error) -type ChunckSize int +type chunckSize int -func (c ChunckSize) valOrDefault() int { +func (c chunckSize) valOrDefault() int { if c == 0 { return defaultBlockSize } @@ -47,14 +47,32 @@ func (c ChunckSize) valOrDefault() int { return int(c) } -func (c ChunckSize) toSizeT() C.size_t { +func (c chunckSize) toSizeT() C.size_t { return C.size_t(c.valOrDefault()) } -type CodexUploadOptions struct { - filepath string - chunkSize ChunckSize - onProgress OnUploadProgressFunc +type UploadOptions struct { + // filepath can be the full path when using UploadFile + // otherwise the file name. + // It is used to detect the mimetype. + filepath string + + // chunkSize is the size of each upload chunk, passed as `blockSize` to the Codex node + // store. Default is to 64 KB. + chunkSize chunckSize + + // onProgress is a callback function that is called after each chunk is uploaded with: + // - read: the number of bytes read in the last chunk. + // - total: the total number of bytes read so far. + // - percent: the percentage of the total file size that has been uploaded. It is + // determined from a `stat` call if it is a file and from the length of the buffer + // if it is a buffer. Otherwise, it is 0. + // - err: an error, if one occurred. + // + // If the chunk size is more than the `chunkSize` parameter, the callback is called + // after the block is actually stored in the block store. Otherwise, it is called + // after the chunk is sent to the stream. + onProgress onUploadProgressFunc } func getReaderSize(r io.Reader) int64 { @@ -76,15 +94,7 @@ func getReaderSize(r io.Reader) int64 { // It returns a session ID that can be used for subsequent upload operations. // This function is called by UploadReader and UploadFile internally. // You should use this function only if you need to manage the upload session manually. -// The options parameter contains the following fields: -// - filepath: the full path or the name of the file to upload. The metadata such as the -// filename and mimetype are extracted from this path / name. -// - chunkSize: the size of each upload chunk, passed as `blockSize` to the Codex node -// store. Default is to 64 KB. -// - onProgress: a callback function that is called after each chunk is uploaded. If the chunk -// size is more than the `chunkSize` parameter, the callback is called after the block is actually -// stored in the block store. Otherwise, it is called after the chunk is sent to the stream. -func (node CodexNode) UploadInit(options *CodexUploadOptions) (string, error) { +func (node CodexNode) UploadInit(options *UploadOptions) (string, error) { bridge := newBridgeCtx() defer bridge.free() @@ -163,28 +173,12 @@ func (node CodexNode) UploadCancel(sessionId string) error { // It takes the upload options and the reader as parameters. // It returns the CID of the uploaded file or an error. // -// The options parameter contains the following fields: -// - filepath: the name of the file to upload. -// - chunkSize: the size of each upload chunk, passed as `blockSize` to the Codex node -// store. Default is to 64 KB. -// - onProgress: a callback function that is called after each chunk is uploaded with: -// - read: the number of bytes read in the last chunk. -// - total: the total number of bytes read so far. -// - percent: the percentage of the total file size that has been uploaded. It is -// determined from a `stat` call if the reader is a file and from the length of the buffer -// if the reader is a buffer. Otherwise, it is 0. -// - err: an error, if one occurred. -// -// If the chunk size is more than the `chunkSize` parameter, the callback is called after -// the block is actually stored in the block store. Otherwise, it is called after the chunk -// is sent to the stream. -// // Internally, it calls: // - UploadInit to create the upload session. // - UploadChunk to upload a chunk to codex. // - UploadFinalize to finalize the upload session. // - UploadCancel if an error occurs. -func (node CodexNode) UploadReader(options CodexUploadOptions, r io.Reader) (string, error) { +func (node CodexNode) UploadReader(options UploadOptions, r io.Reader) (string, error) { sessionId, err := node.UploadInit(&options) if err != nil { return "", err @@ -242,7 +236,7 @@ func (node CodexNode) UploadReader(options CodexUploadOptions, r io.Reader) (str } // UploadReaderAsync is the asynchronous version of UploadReader using a goroutine. -func (node CodexNode) UploadReaderAsync(options CodexUploadOptions, r io.Reader, onDone func(cid string, err error)) { +func (node CodexNode) UploadReaderAsync(options UploadOptions, r io.Reader, onDone func(cid string, err error)) { go func() { cid, err := node.UploadReader(options, r) onDone(cid, err) @@ -269,7 +263,7 @@ func (node CodexNode) UploadReaderAsync(options CodexUploadOptions, r io.Reader, // is sent to the stream. // // Internally, it calls UploadInit to create the upload session. -func (node CodexNode) UploadFile(options CodexUploadOptions) (string, error) { +func (node CodexNode) UploadFile(options UploadOptions) (string, error) { bridge := newBridgeCtx() defer bridge.free() @@ -317,7 +311,7 @@ func (node CodexNode) UploadFile(options CodexUploadOptions) (string, error) { } // UploadFileAsync is the asynchronous version of UploadFile using a goroutine. -func (node CodexNode) UploadFileAsync(options CodexUploadOptions, onDone func(cid string, err error)) { +func (node CodexNode) UploadFileAsync(options UploadOptions, onDone func(cid string, err error)) { go func() { cid, err := node.UploadFile(options) onDone(cid, err) diff --git a/codex/upload_test.go b/codex/upload_test.go index d3852b0..6e6657a 100644 --- a/codex/upload_test.go +++ b/codex/upload_test.go @@ -17,7 +17,7 @@ func TestUploadReader(t *testing.T) { buf := bytes.NewBuffer([]byte("Hello World!")) len := buf.Len() - cid, err := codex.UploadReader(CodexUploadOptions{filepath: "hello.txt", onProgress: func(read, total int, percent float64, err error) { + cid, err := codex.UploadReader(UploadOptions{filepath: "hello.txt", onProgress: func(read, total int, percent float64, err error) { if err != nil { log.Fatalf("Error happened during upload: %v\n", err) } @@ -54,7 +54,7 @@ func TestUploadFile(t *testing.T) { log.Fatalf("Error happened during file stat: %v\n", err) } - options := CodexUploadOptions{filepath: "./testdata/hello.txt", onProgress: func(read, total int, percent float64, err error) { + options := UploadOptions{filepath: "./testdata/hello.txt", onProgress: func(read, total int, percent float64, err error) { if err != nil { log.Fatalf("Error happened during upload: %v\n", err) } @@ -85,7 +85,7 @@ func TestUploadFileNoProgress(t *testing.T) { start := true codex := newCodexNode(t, start) - options := CodexUploadOptions{filepath: "./testdata/doesnt_exist.txt"} + options := UploadOptions{filepath: "./testdata/doesnt_exist.txt"} cid, err := codex.UploadFile(options) if err == nil { @@ -101,7 +101,7 @@ func TestManualUpload(t *testing.T) { start := true codex := newCodexNode(t, start) - sessionId, err := codex.UploadInit(&CodexUploadOptions{filepath: "hello.txt"}) + sessionId, err := codex.UploadInit(&UploadOptions{filepath: "hello.txt"}) if err != nil { log.Fatal("Error happened:", err.Error()) }