🚀 basic_setup — Basic Setup

This example demonstrates how to initialize a Composer repository client (repository.Repository), configure the target repository URL and an optional proxy, and prepare for all subsequent Packagist API calls.

🎯 Example Positioning

basic_setup is the 1st example in the Packagist API Remote Operations series and the starting point of the entire example system. It makes no network requests and solves exactly one thing: building the client object and configuring its parameters. All subsequent remote-operation examples (download_index, list_packages, get_statistics, etc.) build upon this initialization step.

• 📚 What you'll learn: how to use the Options struct of the pkg/repository package to describe the repository URL (ServerUrl) and proxy (Proxy), then how to assemble it into a Repository instance.
• 🔗 Corresponding SDK concepts: repository.Options (the configuration carrier) and repository.Repository (the client type that holds the configuration and exposes all repository API methods).
• 💡 Why it stands alone as an example: decoupling "configuration" from "invocation" lets you switch to a private mirror, add a proxy, or set up a test double by changing only one place without touching business code.

💻 Full Code

package main

import (
	"fmt"

	"github.com/scagogogo/composer-skills/pkg/repository"
)

func main() {
	// Example 1: Basic setup - create a Composer repository client

	// Step 1: Create repository options
	// ServerUrl: specifies the base URL of the Composer repository
	// Proxy: optional; if the repository must be accessed via a proxy, set the proxy URL
	options := &repository.Options{
		ServerUrl: "https://packagist.org", // Official Composer repository
		// If a proxy is needed, uncomment the line below
		// Proxy: "http://your-proxy-server:port",
	}

	// Step 2: Initialize a repository client
	// Repository holds options internally; all repository API methods build request URLs and apply the proxy based on it
	repo := &repository.Repository{
		options: options,
	}

	// Step 3: Print the configuration to confirm successful initialization (this example makes no network requests)
	fmt.Println("Repository client initialization example")
	fmt.Printf("Repository URL: %s\n", options.ServerUrl)

	_ = repo // Subsequent examples will use repo to call List / Statistics and other methods

	// Example output:
	// Repository client initialization example
	// Repository URL: https://packagist.org
}

🧩 Code Walkthrough

• 🧱 Constructing the config object: &repository.Options{ServerUrl: ..., Proxy: ...} is the configuration source for all calls. ServerUrl points to the official Packagist repository https://packagist.org; for a private Satis or mirror, just change it to the corresponding address.
• 🌐 Leaving the proxy field blank: Proxy defaults to an empty string. Inside Repository.getBytes, it only attaches proxy settings when x.options.Proxy != "", so "no proxy" costs nothing — no conditional branch needed.
• 🔌 Assembling the client: &repository.Repository{options: options} injects the configuration into the client. Repository has only one unexported field options *Options, so this is the standard way to construct an instance from outside the package.
• 🚫 No network triggered: This example only constructs and prints; it calls no API methods, so running it produces no HTTP traffic. It's suitable for verifying "whether the configuration chain is wired up" in CI or offline environments.
• 🧪 Testable replacement: Point ServerUrl at a local server started by httptest.NewServer, and you can unit-test methods like repo.List() and repo.Statistics() without relying on the public internet — this is exactly the pattern the SDK's own tests use.
• 🛡️ Avoiding unused warnings: _ = repo explicitly discards the variable, ensuring compilation passes even at the "initialize only, don't call yet" demo stage.

▶️ How to Run

Run directly from the example directory:

cd /home/cc11001100/github/scagogogo/composer-skills/examples/basic_setup
go run main.go

✅ This example makes no network requests, so it can be run repeatedly at any time with no rate-limit or server-load concerns.

📚 SDK Methods Involved

Method / Type	Package	Role	Doc Link
Options	pkg/repository	Repository config (ServerUrl + Proxy)	/sdk/packagist/methods/get-statistics
Repository	pkg/repository	Repository client, carries all Packagist API methods	/sdk/packagist/methods/get-statistics

📝 Note: Options and Repository are infrastructure types rather than single endpoint methods. The links in this table point to the Statistics method docs as an entry point, so you can follow the thread to see all APIs mounted on Repository (List, ListSecurityAdvisories, ListAdvisories, Statistics, etc.) and how their requests are assembled.

🚀 Going Further

• 🌍 Switch to a private mirror: Change ServerUrl to your self-hosted Satis or Toran Proxy address, and pair it with build-satis to reuse the same calling code on an intranet.
• 🛡️ Add timeout and retry: Before calling repo.List(ctx), derive a timeout-bearing ctx with context.WithTimeout, and apply a bounded backoff retry for transient network errors to improve stability on flaky networks.
• 🧵 Concurrency safety: Repository itself has no state-write races, so a single repo instance can be safely shared across goroutines, saving the overhead of repeated construction.
• 🧪 Test doubles: Refer to newTestRepository in the SDK tests — use httptest.NewServer to return fixed JSON and run deterministic unit tests on business logic that calls repo, avoiding dependence on the public internet.
• 🔐 Auth extension: When private repository authentication is needed, extend the Options with token/credential fields, or inject an Authorization header at the getBytes layer (the same way Proxy is injected).