client

package module
v0.3.11 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 7, 2026 License: MIT Imports: 14 Imported by: 4

README

syfon client (Go SDK)

Go Reference Go Report Card Go Version CI Client Coverage dependabot Latest Release PRs Welcome GitHub Stars

This module provides a reusable Go client for Syfon APIs.

  • Module: github.com/calypr/syfon/client
  • Pattern: Vault-style grouped services (Client.Data(), Client.Index(), Client.Buckets(), etc.)
  • Current surface:
    • Health: /healthz
    • Data: /data/upload, /data/upload/{file_id}, /data/upload/bulk, /data/download/{file_id}, multipart endpoints
    • Index: /index, /index/{id}, bulk endpoints
    • Buckets: /data/buckets, /data/buckets/{bucket}, /data/buckets/{bucket}/scopes
    • Core: /index/v1/sha256/validity
    • Metrics: /index/v1/metrics/*

Usage

package main

import (
  "context"
  "errors"
  "log"

  "github.com/calypr/syfon/apigen/bucketapi"
  "github.com/calypr/syfon/apigen/errorapi"
  "github.com/calypr/syfon/client/apierror"
  syclient "github.com/calypr/syfon/client"
)

func main() {
  c, err := syclient.New(
    "http://127.0.0.1:8080",
    syclient.WithBasicAuth("user", "pass"),
  )
  if err != nil {
    log.Fatal(err)
  }

  provider := "s3"
  region := "us-east-1"
  accessKey := "..."
  secretKey := "..."

  err = c.Buckets().Put(context.Background(), bucketapi.PutBucketRequest{
    Bucket:       "cbds",
    Provider:     &provider,
    Region:       &region,
    AccessKey:    &accessKey,
    SecretKey:    &secretKey,
    Organization: "syfon",
    ProjectId:    "e2e",
  })
  if err != nil {
    log.Fatal(err)
  }

  if err := c.Health().Ping(context.Background()); err != nil {
    var apiErr *apierror.APIError
    if errors.As(err, &apiErr) {
      log.Printf("Syfon request %s failed with %s (%d), request ID %s", apiErr.URL, apiErr.Code, apiErr.Status, apiErr.RequestID)
    }
    if errors.Is(err, errorapi.ErrUnavailable) {
      log.Printf("Syfon is temporarily unavailable")
    }
    log.Fatal(err)
  }
}

After it successfully reads an HTTP response body, Syfon maps responses with status 400 or greater to *apierror.APIError. The error preserves the HTTP status, exact machine-readable code, broad error category, public message, request ID, request method and URL, response headers, and response body. A response-body read failure remains an ordinary wrapped error. Use errors.Is with a broad sentinel for portable control flow:

record, err := c.DRS().GetObject(context.Background(), "object-id")
if errors.Is(err, errorapi.ErrNotFound) {
  // The object does not exist or is not visible to this caller.
}

APIError.Code has the exported errorapi.ErrorCode type and preserves unknown server-defined codes. Exact sentinels work with errors.Is, while the broad sentinel remains available for fallback handling:

switch {
case errors.Is(err, errorapi.ErrObjectChecksumImmutable):
  // Do not retry this update with a different checksum.
case errors.Is(err, errorapi.ErrConflict):
  // Handle another conflict reason.
}

Code comparisons such as apiErr.Code == errorapi.ErrorCodeObjectChecksumImmutable are also stable. APIError.Category has the exported errorapi.ErrorCategory type. The exported broad sentinels are ErrNotFound, ErrUnauthorized, ErrForbidden, ErrConflict, ErrInvalidInput, ErrRateLimited, and ErrUnavailable.

Error contract

Import error definitions from github.com/calypr/syfon/apigen/errorapi. Use an exact sentinel when the operation needs one reason:

if errors.Is(err, errorapi.ErrObjectNotFound) {
	// The requested object is missing.
}

Use errorapi.ErrNotFound when any not-found reason is enough. An exact not-found error also matches the broad sentinel. The broad sentinel does not identify a particular exact reason. The old error constants and type aliases from client/apierror were removed. client/services.ErrObjectNotFound is the deprecated compatibility alias; use errorapi.ErrNotFound to preserve its broad matching behavior. The client/apierror package owns the APIError response type, while apigen/errorapi owns sentinels and codes.

The client returns ordinary wrapped errors for request construction, transport failure, response-body reads, and malformed JSON in a successful response. A malformed non-2xx response, after its body is read, still returns *apierror.APIError. The parser uses the HTTP status when the response body is empty or is not valid JSON. For a valid payload, a known exact code from the top-level or nested error object wins over numeric code or status fields, and its category is derived from that code. An unknown code string is kept in APIError.Code for forward compatibility. The parsed message and request ID are preserved. Fractional and out-of-range numeric codes are ignored.

The server accepts X-Request-Id. If the header is empty, the server creates a request ID. The server includes that ID in the error response and logs it with the internal error. Error responses use public-safe status text for 5xx messages. Inspect APIError.Body or server logs only in a controlled diagnostic context, because those values can contain provider or database details. When both the response header and JSON body contain a request ID, the client uses the response header.

LFS and multipart behavior

LFSService.Batch and LFSService.StageMetadata require their generated 200 response payloads. A missing success payload is returned as a shared *apierror.APIError. LFS batch object errors remain in the batch response and must be checked per object. LFSService.Verify accepts only HTTP 200.

The request layer retries only bodyless GET, HEAD, and OPTIONS calls by default. Multipart writes are not retried by that layer. The multipart engine persists a checkpoint after initialization and after each successful part, then removes it after successful completion. A failed completion leaves the checkpoint for a later resume. A repeated completion that returns not found is an error; the client does not infer success from a prior attempt. Server-side multipart sessions are process-memory state, so a server restart loses the session lookup. This is separate from the client checkpoint, which can support resuming a transfer after a client restart.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type BasicAuth

type BasicAuth struct {
	Username string
	Password string
}

type Client

type Client struct {
	// contains filtered or unexported fields
}

func New

func New(baseURL string, opts ...Option) (*Client, error)

func NewClient

func NewClient(cfg *Config) (*Client, error)

func (*Client) Address

func (c *Client) Address() string

func (*Client) BucketAPI

func (c *Client) BucketAPI() *bucketapi.ClientWithResponses

func (*Client) Buckets

func (c *Client) Buckets() *syfonclient.BucketsService

func (*Client) DRS

func (c *Client) DRS() *syfonclient.DRSService

func (*Client) DRSAPI

func (c *Client) DRSAPI() *drs.ClientWithResponses

func (*Client) Data

func (c *Client) Data() *syfonclient.DataService

func (*Client) Do added in v0.3.6

func (c *Client) Do(req *http.Request) (*http.Response, error)

func (*Client) HTTPClient

func (c *Client) HTTPClient() *http.Client

func (*Client) Health

func (c *Client) Health() *syfonclient.HealthService

func (*Client) Index

func (c *Client) Index() *syfonclient.IndexService

func (*Client) InternalAPI

func (c *Client) InternalAPI() *internalapi.ClientWithResponses

func (*Client) LFS

func (c *Client) LFS() *syfonclient.LFSService

func (*Client) LFSAPI

func (c *Client) LFSAPI() *lfsapi.ClientWithResponses

Schema-specific generated clients

func (*Client) Logger

func (c *Client) Logger() *logs.Gen3Logger

func (*Client) Metrics

func (c *Client) Metrics() *syfonclient.MetricsService

func (*Client) MetricsAPI

func (c *Client) MetricsAPI() *metricsapi.ClientWithResponses

type Config

type Config struct {
	Address    string
	HTTPClient *http.Client
	UserAgent  string
	BasicAuth  *BasicAuth
	Token      string
}

func DefaultConfig

func DefaultConfig() *Config

type Option

type Option func(*Config)

func WithBasicAuth

func WithBasicAuth(user, pass string) Option

func WithBearerToken

func WithBearerToken(token string) Option

func WithHTTPClient

func WithHTTPClient(client *http.Client) Option

func WithUserAgent

func WithUserAgent(userAgent string) Option

Directories

Path Synopsis
Package cloud contains client-side data-provider inspection helpers used when a caller needs to talk directly to S3/GCS/Azure object storage.
Package cloud contains client-side data-provider inspection helpers used when a caller needs to talk directly to S3/GCS/Azure object storage.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL