ssclient

package module
v0.11.0 Latest Latest
Warning

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

 Go to latest Published: Mar 24, 2026 License: Apache-2.0 Imports: 23 Imported by: 0

README

ssclient

PkgGoDev OpenAPI docs

This repository provides the go.artefactual.dev/ssclient module. It does not provide functionality beyond making the underlying REST API available.

The API is still experimental, breaking changes MAY occur.

Usage

Check out example, a small program that imports this module to print a list of locations and pipelines found in Archivematica Storage Service.

Working with the high-level client

The main entrypoint is ssclient.New, which constructs a client with small, domain-oriented helpers such as Locations(), Packages(), and Pipelines(). This is the recommended way to use the module and should be the default path for interacting with the API.

Working with the generated client

This repository also ships a generated client based on the project's OpenAPI description. If you need an endpoint that the high-level wrapper does not expose yet, Client.Raw() returns that lower-level client as an escape hatch.

That generated API uses Kiota's request-builder pattern, including EmptyPathSegment() for Storage Service endpoints that require a trailing slash. See example for a side-by-side example using both the high-level client and the generated client.

[!WARNING] Prefer the high-level wrapper for normal use. Client.Raw() is an escape hatch for gaps in wrapper coverage while we continue to define that boundary. For background, see issue #20.

OpenAPI specification

We use TypeSpec to describe the Storage Service API as an OpenAPI schema.

You can browse the schema in two forms:

The description is still incomplete, and we expect to extend it over time as we cover more of the API.

Notes

The Storage Service API itself is built with TastyPie, which provides schema introspection endpoints such as:

curl http://127.0.0.1:62081/api/v2/?fullschema=true

An example of that output is available at ss-schema.json. That data has been useful as reference material while building the TypeSpec description.

If we want to expand coverage further, django-tastypie-swagger may be useful prior art because it already maps Tastypie resources into Swagger-style schema data.

Contributor notes

This repository is wrapper-first. Generated code is supporting infrastructure and a fallback escape hatch, not the primary interface we want callers to use.

When an endpoint's wire contract needs to be added or changed, the preferred pattern is:

  1. Fix TypeSpec first so the OpenAPI remains accurate.
  2. Regenerate Kiota without hand-editing generated files.
  3. Expose the operation through the public client wrapper and treat the generated Go surface as supporting infrastructure.

Current examples include:

  • Packages.Move, where Storage Service expects application/x-www-form-urlencoded and responds with 202 Accepted plus a Location header.
  • Packages.DeleteAIP, where multiple non-error 2xx outcomes need to be preserved explicitly.
  • Packages.ReviewAIPDeletion, where the server can return different 200 JSON payloads and the wrapper lifts application-level failures into a typed error for idiomatic Go callers.
  • AsyncService.Get and AsyncService.Wait, where the generated async endpoint and model types remain available but the wrapper exposes a more Go-oriented polling interface.

Documentation

Overview

Package ssclient provides a Go client for the Archivematica Storage Service API.

It wraps the client code generated by kiota-go from the OpenAPI specification.

The package provides a small, domain-oriented wrapper around the generated Kiota client for common operations while keeping the generated client accessible for advanced use cases.

The public API intentionally abstracts most of the generated request-builder surface, but it still uses generated Kiota model types for requests, responses, and enums where that keeps the SDK compact and close to the service schema.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func IsNotFound added in v0.7.0 

func IsNotFound(err error) bool

IsNotFound reports whether err represents a 404 response.

func MustParseAsyncOperationURI added in v0.11.0 

func MustParseAsyncOperationURI(resourceURI string) int

MustParseAsyncOperationURI extracts the task ID from a Storage Service async operation URI and panics if the URI is invalid.

func MustParseResourceURI added in v0.7.0 

func MustParseResourceURI(resourceURI string) (resource, uuid string)

MustParseResourceURI extracts the resource name and UUID from a Storage Service resource URI and panics if the URI is invalid.

func ParseAsyncOperationURI added in v0.11.0 

func ParseAsyncOperationURI(resourceURI string) (int, error)

ParseAsyncOperationURI extracts the task ID from a Storage Service async operation URI such as "/api/v2/async/1/".

func ParseResourceURI added in v0.7.0 

func ParseResourceURI(resourceURI string) (resource, uuid string, err error)

ParseResourceURI extracts the resource name and UUID from a Storage Service resource URI.

func StatusCode added in v0.7.0 

func StatusCode(err error) (int, bool)

StatusCode returns the HTTP status code from a supported Storage Service error, if present.

Types

type AsyncService added in v0.11.0 

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

AsyncService provides access to asynchronous operation tracking.

func (*AsyncService) Get added in v0.11.0 

func (s *AsyncService) Get(ctx context.Context, id int) (*models.AsyncTask, error)

Get returns the current state of an asynchronous task by ID.

func (*AsyncService) Wait added in v0.11.0 

func (s *AsyncService) Wait(ctx context.Context, id int, opts ...WaitOption) (*models.AsyncTask, error)

Wait polls the asynchronous task until it completes, the context is canceled, or a transport/protocol failure occurs.

type AsyncTaskError added in v0.11.0 

type AsyncTaskError struct {
	Task    *models.AsyncTask
	Message string
}

AsyncTaskError describes a completed asynchronous task that finished in an application-level error state.

func (*AsyncTaskError) Error added in v0.11.0 

func (e *AsyncTaskError) Error() string

Error returns a readable representation of the failed async task.

type CheckFixityOptions added in v0.7.0 

type CheckFixityOptions struct {
	ForceLocal *bool
}

CheckFixityOptions configures a package fixity check request.

type Client added in v0.7.0 

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

Client is the public entrypoint for the wrapper around the generated Kiota client.

func New 

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

New constructs a Storage Service client backed by the generated Kiota client.

func (*Client) Adapter added in v0.7.0 

func (c *Client) Adapter() kabs.RequestAdapter

Adapter returns the underlying request adapter.

func (*Client) Async added in v0.11.0 

func (c *Client) Async() *AsyncService

Async returns asynchronous operation tracking helpers.

func (*Client) Locations added in v0.7.0 

func (c *Client) Locations() *LocationsService

Locations returns location-related operations.

func (*Client) Packages added in v0.7.0 

func (c *Client) Packages() *PackagesService

Packages returns package-related operations. The Storage Service transport uses "/file/" for these resources, but the public API exposes them as packages.

func (*Client) Pipelines added in v0.7.0 

func (c *Client) Pipelines() *PipelinesService

Pipelines returns pipeline-related operations.

func (*Client) Raw added in v0.7.0 

func (c *Client) Raw() *kiota.Client

Raw returns the generated Kiota client as an escape hatch.

type Config added in v0.7.0 

type Config struct {
	BaseURL     string
	Username    string
	Key         string
	HTTPClient  *http.Client
	Middlewares []khttp.Middleware
}

Config configures a Storage Service client.

type DeleteAIPAccepted added in v0.7.0 

type DeleteAIPAccepted struct {
	Message string `json:"message"`
	ID      int32  `json:"id"`
}

DeleteAIPAccepted is returned when the server creates a new deletion request.

type DeleteAIPAlreadyExists added in v0.7.0 

type DeleteAIPAlreadyExists struct {
	ErrorMessage string `json:"error_message"`
}

DeleteAIPAlreadyExists is returned when a pending deletion request already exists for the package.

type DeleteAIPResult added in v0.7.0 

type DeleteAIPResult struct {
	Accepted      *DeleteAIPAccepted
	AlreadyExists *DeleteAIPAlreadyExists
}

DeleteAIPResult preserves the two non-error outcomes exposed by the Storage Service delete request endpoint.

func (*DeleteAIPResult) HasExistingRequest added in v0.7.0 

func (r *DeleteAIPResult) HasExistingRequest() bool

HasExistingRequest reports whether the package already had a pending deletion request.

func (*DeleteAIPResult) IsAccepted added in v0.7.0 

func (r *DeleteAIPResult) IsAccepted() bool

IsAccepted reports whether the request created a new deletion event.

type FileStream added in v0.7.0 

type FileStream struct {
	StatusCode         int
	ContentType        string
	ContentLength      int64
	ContentDisposition string
	Filename           string
	Body               io.ReadCloser
}

FileStream describes a successful streamed file response and exposes common metadata derived from the HTTP headers alongside the live body reader.

type ListLocationsQuery added in v0.7.0 

type ListLocationsQuery struct {
	Description  *string
	Limit        *int32
	Offset       *int32
	OrderBy      *string
	PipelineID   *uuid.UUID
	Purpose      *models.LocationPurpose
	Quota        *int32
	RelativePath *string
	Used         *int32
	ID           *uuid.UUID
}

ListLocationsQuery describes the supported query parameters for listing locations.

type ListPipelinesQuery added in v0.7.0 

type ListPipelinesQuery struct {
	Description *string
	ID          *uuid.UUID
}

ListPipelinesQuery describes the supported query parameters for listing pipelines.

type LocationsService added in v0.7.0 

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

LocationsService provides location-related API operations.

func (*LocationsService) Default added in v0.7.0 

func (s *LocationsService) Default(ctx context.Context, purpose models.LocationPurpose) (string, error)

Default returns the Location header from the default-location redirect for a given purpose. The returned value is a resource URI; use ParseResourceURI to extract the resource identifier when needed.

func (*LocationsService) Get added in v0.7.0 

func (s *LocationsService) Get(ctx context.Context, id uuid.UUID) (*models.Location, error)

Get returns a location by ID.

func (*LocationsService) List added in v0.7.0 

func (s *LocationsService) List(ctx context.Context, query ListLocationsQuery) (*models.LocationList, error)

List returns a filtered list of locations.

func (*LocationsService) Move added in v0.7.0 

func (s *LocationsService) Move(ctx context.Context, id uuid.UUID, body *models.MoveRequest) error

Move moves files to the specified location.

type MoveResult added in v0.10.0 

type MoveResult struct {
	Location string
}

MoveResult captures the accepted async package move response.

type NotAvailableError added in v0.7.0 

type NotAvailableError struct {
	StatusCode int
	Headers    http.Header
	Body       []byte
	Message    string
}

NotAvailableError describes a 202 response indicating the requested content is not locally available for download yet.

func (*NotAvailableError) Error added in v0.7.0 

func (e *NotAvailableError) Error() string

Error returns a readable representation of the unavailable response.

type PackagesService added in v0.7.0 

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

PackagesService provides package-related API operations.

func (*PackagesService) CheckFixity added in v0.7.0 

func (s *PackagesService) CheckFixity(ctx context.Context, id uuid.UUID, opts CheckFixityOptions) (*models.FixityResponse, error)

CheckFixity runs a fixity check for the given package ID.

func (*PackagesService) DeleteAIP added in v0.7.0 

func (s *PackagesService) DeleteAIP(ctx context.Context, id uuid.UUID, body *models.DeleteAipRequest) (*DeleteAIPResult, error)

DeleteAIP creates an AIP deletion request for the given package. The server exposes two non-error outcomes: one for a newly created request and one for an already pending request.

func (*PackagesService) DownloadFile added in v0.7.0 

func (s *PackagesService) DownloadFile(ctx context.Context, id uuid.UUID, relativePathToFile string) (*FileStream, error)

DownloadFile extracts a file from a package and streams it back.

func (*PackagesService) DownloadPackage added in v0.7.0 

func (s *PackagesService) DownloadPackage(ctx context.Context, id uuid.UUID) (*FileStream, error)

DownloadPackage returns the package archive as downloaded by Storage Service.

func (*PackagesService) DownloadPointerFile added in v0.7.0 

func (s *PackagesService) DownloadPointerFile(ctx context.Context, id uuid.UUID) (*FileStream, error)

DownloadPointerFile returns the package pointer file as a stream.

func (*PackagesService) Get added in v0.7.0 

func (s *PackagesService) Get(ctx context.Context, id uuid.UUID) (*models.PackageEscaped, error)

Get returns a package by ID.

func (*PackagesService) Move added in v0.7.0 

func (s *PackagesService) Move(ctx context.Context, id, locationID uuid.UUID) (*MoveResult, error)

Move starts an asynchronous package move to a different storage location. The returned Location header points at the async operation resource.

func (*PackagesService) ReviewAIPDeletion added in v0.7.0 

func (s *PackagesService) ReviewAIPDeletion(ctx context.Context, id uuid.UUID, body *models.ReviewAipDeletionRequest) (*ReviewAIPDeletionSuccess, error)

ReviewAIPDeletion approves or rejects an AIP deletion request associated with a package.

Storage Service reports two distinct business outcomes for this endpoint using the same HTTP 200 status code and content type:

  • success bodies use {"message": ...}
  • application-level failure bodies use {"error_message": ...}

That shape is part of the deployed API, but it is awkward for generated clients because there is no discriminator beyond the JSON fields themselves. The wrapper therefore executes the request and inspects the response body directly so callers can rely on err for both transport/protocol failures and application-level review failures. Callers that need structured failure details can use errors.As with *ReviewAIPDeletionError.

type PipelinesService added in v0.7.0 

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

PipelinesService provides pipeline-related API operations.

func (*PipelinesService) Get added in v0.7.0 

func (s *PipelinesService) Get(ctx context.Context, id uuid.UUID) (*models.Pipeline, error)

Get returns a pipeline by ID.

func (*PipelinesService) List added in v0.7.0 

func (s *PipelinesService) List(ctx context.Context, query ListPipelinesQuery) (*models.PipelineList, error)

List returns a filtered list of pipelines.

type ResponseError added in v0.7.0 

type ResponseError struct {
	StatusCode int
	Headers    http.Header
	Body       []byte
	Message    string
	Detail     string
	Cause      error
}

ResponseError describes a non-success HTTP response returned by Storage Service.

func (*ResponseError) Error added in v0.7.0 

func (e *ResponseError) Error() string

Error returns a readable representation of the failed response.

func (*ResponseError) Unwrap added in v0.7.0 

func (e *ResponseError) Unwrap() error

Unwrap returns the original error when this error wraps one.

type ReviewAIPDeletionError added in v0.11.0 

type ReviewAIPDeletionError struct {
	ErrorMessage string
	Detail       string
}

ReviewAIPDeletionError describes an application-level review failure returned by the review AIP deletion endpoint with HTTP 200.

func (*ReviewAIPDeletionError) Error added in v0.11.0 

func (e *ReviewAIPDeletionError) Error() string

Error returns a readable representation of the application-level review failure.

type ReviewAIPDeletionSuccess added in v0.10.0 

type ReviewAIPDeletionSuccess struct {
	Message string `json:"message"`
	Detail  string `json:"detail,omitempty"`
}

ReviewAIPDeletionSuccess captures a successful review response.

type WaitOption added in v0.11.0 

type WaitOption func(*waitOptions) error

WaitOption customizes the polling behavior of AsyncService.Wait.

func WithPollInterval added in v0.11.0 

func WithPollInterval(interval time.Duration) WaitOption

WithPollInterval sets the delay between successive polls performed by AsyncService.Wait.

Source Files

View all Source files

Directories

Path Synopsis
api
models

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.