fetch

Documentation

Overview

Package fetch retrieves a rock's `source.url` into a working directory.

Fetch is the default-options entry point; FetchWith takes Options carrying the rockspec's source metadata (tag/branch for git, md5/file for archives) plus transport tweaks (insecure hosts, User-Agent). Both return the on-disk path of the unpacked working tree.

The dispatcher selects a Backend per URL scheme:

http, https                          → http.go (net/http GET + unpack)
git, git+http, git+https, git+ssh,
git+file                             → git.go  (go-git clone, no binary)
file                                 → file.go (copy local tree)

Unknown schemes return ErrUnsupportedRockspecFeature wrapped with the scheme name.

All backends honor ctx for cancellation at the network/transport level — the HTTP request and the go-git clone are ctx-bound. Note that local archive extraction after an HTTP fetch is not interrupted mid-unpack. None mutate process state — no os.Setenv, no os.Chdir.

Index

• func Fetch(ctx context.Context, rawURL, destDir string) (string, error)
• func FetchWith(ctx context.Context, rawURL, destDir string, opts Options) (string, error)
• type Backend
• type Options

Examples

• Fetch
• FetchWith

Functions

func Fetch

func Fetch(ctx context.Context, rawURL, destDir string) (string, error)

Fetch retrieves rawURL into destDir using the default options and returns the on-disk path to the unpacked working tree.

Equivalent to FetchWith(ctx, rawURL, destDir, Options{}).

Example

ExampleFetch retrieves a rock source over the file:// scheme by copying a local directory tree into destDir.

package main

import (
	"context"
	"fmt"
	"os"
	"path/filepath"

	"github.com/tarantool/go-luarocks/fetch"
)

func main() {
	srcDir, err := os.MkdirTemp("", "src")
	if err != nil {
		panic(err)
	}

	defer func() { _ = os.RemoveAll(srcDir) }()

	dstDir, err := os.MkdirTemp("", "dst")
	if err != nil {
		panic(err)
	}

	defer func() { _ = os.RemoveAll(dstDir) }()

	if err := os.WriteFile(filepath.Join(srcDir, "hello.lua"), []byte("return 42\n"), 0o644); err != nil {
		panic(err)
	}

	got, err := fetch.Fetch(context.Background(), "file://"+srcDir, dstDir)
	if err != nil {
		panic(err)
	}

	body, err := os.ReadFile(filepath.Join(got, "hello.lua"))
	if err != nil {
		panic(err)
	}

	fmt.Print(string(body))
}

Output:
return 42

func FetchWith

func FetchWith(ctx context.Context, rawURL, destDir string, opts Options) (string, error)

FetchWith is the options-bearing form of Fetch.

Example

ExampleFetchWith is the options-bearing form: source.tag / source.md5 / insecure hosts / user-agent all ride on Options. Here the http backend downloads from an in-process server and verifies the payload's md5 before accepting it.

package main

import (
	"context"
	"fmt"
	"net/http"
	"net/http/httptest"
	"os"
	"path/filepath"

	"github.com/tarantool/go-luarocks/fetch"
)

func main() {
	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
		_, _ = w.Write([]byte("return { answer = 42 }\n"))
	}))
	defer srv.Close()

	dstDir, err := os.MkdirTemp("", "dst")
	if err != nil {
		panic(err)
	}

	defer func() { _ = os.RemoveAll(dstDir) }()

	got, err := fetch.FetchWith(
		context.Background(),
		srv.URL+"/answer.lua",
		dstDir,
		fetch.Options{MD5: "9a411841b564fa0fc78745f8de8f6340", UserAgent: "go-luarocks"},
	)
	if err != nil {
		panic(err)
	}

	body, err := os.ReadFile(filepath.Join(got, "answer.lua"))
	if err != nil {
		panic(err)
	}

	fmt.Print(string(body))
}

Output:
return { answer = 42 }

Types

type Backend

type Backend interface {
	Fetch(ctx context.Context, rawURL, destDir string, opts Options) (string, error)
}

Backend is the per-scheme fetch implementation. The dispatch table registers one Backend per scheme group (http*, git*, file).

type Options

type Options struct {
	// InsecureServers lists URL hosts for which the http backend skips
	// TLS certificate verification. Escape hatch for rocks.tarantool.org.
	InsecureServers []string

	// UserAgent overrides the default User-Agent header sent by
	// the http backend.
	UserAgent string

	// Tag is the value of `source.tag` from the rockspec, passed to the
	// git backend as the tag ref `refs/tags/<tag>`. Empty means default branch.
	Tag string

	// Branch is the value of `source.branch` from the rockspec, passed
	// to the git backend as the branch ref `refs/heads/<branch>`. Set Tag or Branch but
	// not both; if both are set Tag wins.
	Branch string

	// File is the value of `source.file` from the rockspec. When set, the http
	// and file backends save the download under this name (driving archive-type
	// detection) instead of deriving it from the URL path. Empty means derive
	// from the URL (upstream: source.file or dir.base_name(url)).
	File string

	// MD5 is the value of `source.md5` from the rockspec. When set, the http
	// and file backends verify the fetched archive's md5 before unpacking and
	// abort on mismatch (upstream fetch.get_sources → fs.check_md5). Empty
	// means no verification.
	MD5 string

	// Version is the rockspec version. When it is an scm-/dev- version with no
	// source.tag, the git backend computes a commit identifier from HEAD.
	Version string

	// IdentifierOut, when non-nil, receives the git commit identifier the git
	// backend computes for an scm-/dev- version (out-param; avoids widening the
	// Backend result for this optional metadata).
	IdentifierOut *string
}

Options tunes a Fetch invocation. The zero value is the documented default: no insecure hosts, no extra User-Agent override, no source metadata. Pass via FetchWith.