amclient

package module
v0.5.0 Latest Latest
Warning

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

Go to latest
Published: Aug 5, 2026 License: Apache-2.0 Imports: 15 Imported by: 1

README

amclient

PkgGoDev

This repository provides the go.artefactual.dev/amclient module.

The API is still experimental, breaking changes MAY occur.

Go support

This project is maintained on a best-effort basis. When its Go baseline is updated, it aims to follow the Go release policy by supporting the two latest stable releases and, where practical, the most recently deprecated release for an additional six months. The go.mod directive and versions tested in CI are the authoritative current support matrix. Older Go versions may work but are not supported.

Documentation

Overview

Package amclient provides a Go client for the Archivematica Dashboard API.

A Client exposes services for transfers, ingests, processing configurations, packages, jobs, and tasks. Each service operation returns a Response that wraps the underlying HTTP response.

Archivematica 1.11 and newer identify the pipeline and Dashboard version in API response headers. The pipeline identifier is shared by Dashboard, MCPServer, MCPClient, and other Archivematica subsystems. Use Client.ServerInfo to retrieve this information explicitly, or Response.ServerInfo to extract it from an operation that has already completed. Version provides component access and comparison helpers for clients that need to gate behavior on an Archivematica release.

Index

Examples

Constants

This section is empty.

Variables

View Source
var ErrServerInfoUnavailable = errors.New("archivematica server information unavailable")

ErrServerInfoUnavailable indicates that an Archivematica response does not include the server version header. Use errors.Is to test for this error.

Functions

func CheckResponse

func CheckResponse(r *http.Response) error

CheckResponse checks the API response for errors, and returns them if present. A response is considered an error if it has a status code outside the 200 range. API error responses are expected to have either no response body, or a JSON response body that maps to ErrorResponse. Any other response body will be silently ignored.

Types

type Client

type Client struct {

	// Base URL for API requests.
	BaseURL *url.URL

	// User agent for client
	UserAgent string

	// Authentication
	User string
	Key  string

	// Services used for communicating with the API
	Transfer         TransferService
	Ingest           IngestService
	ProcessingConfig ProcessingConfigService
	Package          PackageService
	Jobs             JobsService
	Task             TaskService
	// contains filtered or unexported fields
}

Client manages communication with Archivematica API.

func New

func New(httpClient *http.Client, bu, u, k string, opts ...ClientOpt) (*Client, error)

New returns a new Archivematica API client instance.

func NewClient

func NewClient(httpClient *http.Client, bu, u, k string) *Client

NewClient returns a new Archivematica API client.

func (*Client) Do

func (c *Client) Do(ctx context.Context, req *http.Request, v interface{}) (*Response, error)

Do sends an API request and returns the API response. The API response is JSON decoded and stored in the value pointed to by v, or returned as an error if an API error has occurred. If v implements the io.Writer interface, the raw response will be written to v, without attempting to decode it.

func (*Client) NewRequest

func (c *Client) NewRequest(ctx context.Context, method, urlStr string, body interface{}, opts ...RequestOpt) (*http.Request, error)

NewRequest creates an API request. A relative URL can be provided in urlStr, which will be resolved to the BaseURL of the Client. Relative URLS should always be specified without a preceding slash. If specified, the value pointed to by body is form encoded and included in as the request body.

func (*Client) NewRequestJSON

func (c *Client) NewRequestJSON(ctx context.Context, method, urlStr string, body interface{}, opts ...RequestOpt) (*http.Request, error)

NewRequestJSON is similar to NewRequest but encodes the value to JSON.

func (*Client) ServerInfo added in v0.5.0

func (c *Client) ServerInfo(ctx context.Context) (*ServerInfo, *Response, error)

ServerInfo retrieves information about the Archivematica Dashboard server. Each call makes an authenticated, non-mutating GET request; results are not cached.

Archivematica's package endpoint returns 501 Not Implemented for GET while including server information in its response headers. ServerInfo treats that expected status as successful when the headers are valid. In that case the returned Response retains its 501 status and err is nil.

Example

Server information can be retrieved explicitly when no other API response is available.

package main

import (
	"context"
	"fmt"
	"log"
	"net/http"

	"go.artefactual.dev/amclient"
)

func main() {
	client := amclient.NewClient(
		http.DefaultClient,
		"https://archivematica.example.com/",
		"api-user",
		"api-key",
	)

	info, _, err := client.ServerInfo(context.Background())
	if err != nil {
		log.Fatal(err)
	}

	if info.Version.AtLeast(1, 19, 0) {
		fmt.Println("Archivematica supports idempotent package creation")
	}
}

type ClientOpt

type ClientOpt func(*Client) error

ClientOpt are options for New.

func SetUserAgent

func SetUserAgent(ua string) ClientOpt

SetUserAgent is a client option for setting the user agent.

type ErrorResponse

type ErrorResponse struct {
	// HTTP response that caused this error
	Response *http.Response
}

An ErrorResponse reports the error caused by an API request

func (*ErrorResponse) Error

func (r *ErrorResponse) Error() string

type IngestHideResponse

type IngestHideResponse struct {
	Removed bool `json:"removed"`
}

type IngestService

type IngestService interface {
	Status(context.Context, string) (*IngestStatusResponse, *Response, error)
	Hide(context.Context, string) (*IngestHideResponse, *Response, error)
}

Ingest is an interface for interfacing with the Ingest endpoints of the Dashboard API.

type IngestServiceOp

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

IngestServiceOp handles communication with the Ingest related methods of the Archivematica API.

func (*IngestServiceOp) Hide

func (*IngestServiceOp) Status

type IngestStatusResponse

type IngestStatusResponse struct {
	ID           string `json:"uuid"`
	Status       string `json:"status"`
	Name         string `json:"name"`
	SIPID        string `json:"sip_uuid"`
	Microservice string `json:"microservice"`
	Directory    string `json:"directory"`
	Path         string `json:"path"`
	Message      string `json:"message"`
	Type         string `json:"type"`
}

type Job

type Job struct {
	ID           string    `json:"uuid"`
	Name         string    `json:"name"`
	Status       JobStatus `json:"status"`
	Microservice string    `json:"microservice"`
	LinkID       string    `json:"link_uuid"`
	Tasks        []Task    `json:"tasks"`
}

type JobStatus

type JobStatus int
const (
	JobStatusUnknown JobStatus = iota
	JobStatusUserInput
	JobStatusProcessing
	JobStatusComplete
	JobStatusFailed
)

func (JobStatus) MarshalJSON

func (s JobStatus) MarshalJSON() ([]byte, error)

MarshalJSON marshals the enum as a quoted json string

func (*JobStatus) UnmarshalJSON

func (s *JobStatus) UnmarshalJSON(b []byte) error

UnmarshalJSON unmashals a quoted json string to the enum value

type JobsListRequest

type JobsListRequest struct {
	Microservice string `json:"microservice,omitempty"`
	LinkID       string `json:"link_uuid,omitempty"`
	Name         string `json:"name,omitempty"`

	// Detailed instructs the server to return additional data in the response.
	// This feature is available starting from Archivematica 1.16, which was not
	// released at the time this comment was written.
	Detailed bool `json:"-"`
}

type JobsService

type JobsService interface {
	List(context.Context, string, *JobsListRequest) ([]Job, *Response, error)
}

type JobsServiceOp

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

func (*JobsServiceOp) List

func (s *JobsServiceOp) List(ctx context.Context, ID string, r *JobsListRequest) ([]Job, *Response, error)

type PackageCreateRequest

type PackageCreateRequest struct {
	Name             string `json:"name"`
	Type             string `json:"type"`
	Path             string `json:"path"`
	Accession        string `json:"accession,omitempty"`
	AccessSystemID   string `json:"access_system_id,omitempty"`
	MetadataSetID    string `json:"metadata_set_id,omitempty"`
	ProcessingConfig string `json:"processing_config,omitempty"`
	AutoApprove      *bool  `json:"auto_approve,omitempty"`
	IdempotencyKey   string `json:"-"`
}

type PackageCreateResponse

type PackageCreateResponse struct {
	ID string `json:"id,omitempty"`
}

type PackageService

type PackageService interface {
	Create(context.Context, *PackageCreateRequest) (*PackageCreateResponse, *Response, error)
}

type PackageServiceOp

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

func (*PackageServiceOp) Create

type ProcessingConfig

type ProcessingConfig struct {
	bytes.Buffer
}

ProcessingConfig represents the processing configuration document returned by the Dashboard API.

type ProcessingConfigOp

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

ProcessingConfigOp handles communication with the Tranfer related methods of the Archivematica API.

func (*ProcessingConfigOp) Get

Get obtains a processing configuration given its name.

func (*ProcessingConfigOp) List

func (s *ProcessingConfigOp) List(ctx context.Context) ([]string, *Response, error)

type ProcessingConfigService

type ProcessingConfigService interface {
	Get(context.Context, string) (*ProcessingConfig, *Response, error)
	List(context.Context) ([]string, *Response, error)
}

ProcessingConfigService is an interface for interfacing with the processing configuration endpoints of the Dashboard API.

type RequestOpt

type RequestOpt func(*http.Request)

RequestOpt is a function type used to alter requests.

func WithRequestAcceptXML

func WithRequestAcceptXML() RequestOpt

WithRequestAcceptXML sets the Accept header to "application/xml". This is needed when consuming endpoints that require this configuration.

type Response

type Response struct {
	*http.Response
}

Response is an Archivematica response. This wraps the standard http.Response returned from Archivematica.

func (*Response) ServerInfo added in v0.5.0

func (r *Response) ServerInfo() (*ServerInfo, error)

ServerInfo extracts Archivematica server information from response headers. It does not make a network request. It returns ErrServerInfoUnavailable when the version header is absent and an error when the version is malformed.

Example
package main

import (
	"context"
	"fmt"
	"log"
	"net/http"

	"go.artefactual.dev/amclient"
)

func main() {
	client := amclient.NewClient(
		http.DefaultClient,
		"https://archivematica.example.com/",
		"api-user",
		"api-key",
	)

	_, response, err := client.ProcessingConfig.List(context.Background())
	if err != nil {
		log.Fatal(err)
	}

	info, err := response.ServerInfo()
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Archivematica %s (pipeline %s)\n", info.Version, info.ID)
}

type ServerInfo added in v0.5.0

type ServerInfo struct {
	// Version is the Archivematica release version.
	Version Version

	// ID is the pipeline identifier shared by Dashboard, MCPServer, MCPClient,
	// and other Archivematica subsystems. It is empty when the server does not
	// provide X-Archivematica-ID.
	ID string
}

ServerInfo describes the Archivematica server and pipeline that handled an API request.

type Task

type Task struct {
	ID          string       `json:"uuid"`
	ExitCode    int          `json:"exit_code"`
	FileID      string       `json:"file_uuid"`
	Filename    string       `json:"file_name"`
	CreatedAt   TaskDateTime `json:"time_created"`
	StartedAt   TaskDateTime `json:"time_started"`
	CompletedAt TaskDateTime `json:"time_ended"`
	Duration    TaskDuration `json:"duration"`
}

type TaskDateTime

type TaskDateTime struct {
	time.Time
}

func (*TaskDateTime) UnmarshalJSON

func (t *TaskDateTime) UnmarshalJSON(data []byte) error

type TaskDuration added in v0.3.0

type TaskDuration time.Duration

TaskDuration extends the standard time.Duration type to provide specialized unmarshaling from JSON. Unlike time.Duration, which typically requires duration values to be specified in string format (like "300ms", "1h30m"), TaskDuration is designed to unmarshal from two distinct JSON value types:

  1. Integer values representing the duration in seconds.
  2. A specific string literal "< 1", which we interpret as half a second.

Examples:

  • `{"duration": 60}` unmarshals to 60 seconds,
  • `{"duration": "< 1"}` unmarshals to 500 milliseconds.

Python function: https://github.com/artefactual/archivematica/blob/2c03a79e710d655c3740ddbc4bc62eebd4e4b4fe/src/dashboard/src/components/helpers.py#L163-L170.

func (*TaskDuration) UnmarshalJSON added in v0.3.0

func (d *TaskDuration) UnmarshalJSON(data []byte) error

type TaskService

type TaskService interface {
	Read(context.Context, string) (*Task, *Response, error)
}

type TaskServiceOp

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

func (*TaskServiceOp) Read

func (s *TaskServiceOp) Read(ctx context.Context, ID string) (*Task, *Response, error)

type TransferApproveRequest

type TransferApproveRequest struct {
	Type      string `schema:"type"`
	Directory string `schema:"directory"`
}

TransferApproveRequest represents a request to approve a transfer.

type TransferApproveResponse

type TransferApproveResponse struct {
	Message string `json:"message"`
	UUID    string `json:"uuid"`
}

TransferApproveResponse represents a response to TransferApproveRequest.

type TransferHideResponse

type TransferHideResponse struct {
	Removed bool `json:"removed"`
}

type TransferService

TransferService is an interface for interfacing with the Transfer endpoints of the Dashboard API.

type TransferServiceOp

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

TransferServiceOp handles communication with the Tranfer related methods of the Archivematica API.

func (*TransferServiceOp) Approve

Approve approves an existing transfer awaiting for approval.

func (*TransferServiceOp) Hide

func (*TransferServiceOp) Start

Start starts a new transfer.

func (*TransferServiceOp) Status

func (*TransferServiceOp) Unapproved

Unapproved lists existing transfers waiting for approval.

type TransferStartRequest

type TransferStartRequest struct {
	Name  string   `schema:"name"`
	Type  string   `schema:"type"`
	Paths []string `schema:"paths"`
}

TransferStartRequest represents a request to start a transfer.

type TransferStartResponse

type TransferStartResponse struct {
	Message string `schema:"message"`
	Path    string `schema:"path"`
}

TransferStartResponse represents a response to TransferStartRequest.

type TransferStatusResponse

type TransferStatusResponse struct {
	ID           string `json:"uuid"`
	Status       string `json:"status"`
	Name         string `json:"name"`
	SIPID        string `json:"sip_uuid"`
	Microservice string `json:"microservice"`
	Directory    string `json:"directory"`
	Path         string `json:"path"`
	Message      string `json:"message"`
	Type         string `json:"type"`
}

func (TransferStatusResponse) SIP

func (t TransferStatusResponse) SIP() (string, bool)

type TransferUnapprovedRequest

type TransferUnapprovedRequest struct{}

TransferUnapprovedRequest represents a request to list unapproved transfer.

type TransferUnapprovedResponse

type TransferUnapprovedResponse struct {
	Message string                              `json:"message"`
	Results []*TransferUnapprovedResponseResult `json:"results"`
}

TransferUnapprovedResponse represents a response to TransferUnapprovedRequest.

type TransferUnapprovedResponseResult

type TransferUnapprovedResponseResult struct {
	Type      string `json:"type"`
	Directory string `json:"directory"`
	UUID      string `json:"uuid"`
}

TransferUnapprovedResponseResult represents a result of TransferUnapprovedResponse.

type Version added in v0.5.0

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

Version is an immutable numeric Archivematica release version parsed from the X-Archivematica-Version response header. Its zero value represents 0.0.0.

func (Version) AtLeast added in v0.5.0

func (v Version) AtLeast(major, minor, patch uint64) bool

AtLeast reports whether v is greater than or equal to the version identified by major, minor, and patch. It is intended for release feature checks such as v.AtLeast(1, 19, 0).

func (Version) Compare added in v0.5.0

func (v Version) Compare(other Version) int

Compare compares v with other. It returns -1, 0, or 1 when v is less than, equal to, or greater than other, respectively.

func (Version) Major added in v0.5.0

func (v Version) Major() uint64

Major returns the major version component.

func (Version) Minor added in v0.5.0

func (v Version) Minor() uint64

Minor returns the minor version component.

func (Version) Patch added in v0.5.0

func (v Version) Patch() uint64

Patch returns the patch version component.

func (Version) String added in v0.5.0

func (v Version) String() string

String returns the version in major.minor.patch form.

Directories

Path Synopsis
Package amclienttest is a generated GoMock package.
Package amclienttest is a generated GoMock package.

Jump to

Keyboard shortcuts

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