jpip

Documentation

Overview

Package jpip retrieves and decodes pixel streams referenced by DICOM JPIP transfer syntaxes.

Index

• Variables
• type BasicCredential
• type BearerCredential
• type ByteRange
• type CacheStats
• type Client
  • func NewClient(config Config) (*Client, error)
  • func (c *Client) CacheStats() CacheStats
  • func (c *Client) DecodeFrame(ctx context.Context, request Request, dataset *object.Object) (DecodedFrame, error)
  • func (c *Client) Retrieve(ctx context.Context, request Request) (Response, error)
• type Config
• type DecodedFrame
• type Error
  • func (e *Error) Error() string
  • func (e *Error) Unwrap() error
• type ErrorKind
• type Policy
• type Region
• type Request
• type Response
• type Rule
  • func RuleForHost(scheme, host, port string) (Rule, error)
  • func RuleFromURL(raw string) (Rule, error)
• type Size

Variables

var (
	ErrInvalidRequest         = errors.New("dicom: invalid JPIP request")
	ErrBearerTokenUnavailable = errors.New("dicom: JPIP bearer token unavailable")
	ErrPolicyDenied           = errors.New("dicom: JPIP endpoint denied by policy")
	ErrRedirectDenied         = errors.New("dicom: JPIP redirect denied by policy")
	ErrOffline                = errors.New("dicom: JPIP endpoint unavailable")
	ErrHTTPStatus             = errors.New("dicom: JPIP endpoint returned an unsuccessful status")
	ErrUnsupportedContentType = errors.New("dicom: unsupported JPIP response content type")
	ErrResponseTooLarge       = errors.New("dicom: JPIP response exceeds configured limit")
	ErrPartialResponse        = errors.New("dicom: incomplete JPIP response")
	ErrCorruptResponse        = errors.New("dicom: corrupt JPIP response")
	ErrIncrementalStream      = errors.New("dicom: JPIP incremental data-bin stream is not directly decodable")
	ErrDecode                 = errors.New("dicom: JPIP response decode failed")
)

Types

type BasicCredential

type BasicCredential struct {
	Origin   string
	Username string
	Password string
}

BasicCredential is applied only to the exact origin in Origin. It is never inherited by a redirect merely because a broader Rule permits that target.

type BearerCredential

type BearerCredential struct {
	Origin string
	Source dicomweb.BearerTokenSource
}

BearerCredential obtains a dynamic bearer token only for the exact origin in Origin. Its source may refresh tokens and optionally invalidate a token challenged with HTTP 401.

type ByteRange

type ByteRange struct {
	Start int64
	End   int64
}

ByteRange requests an inclusive HTTP byte range. It is useful for servers that expose a complete representation in addition to JPIP query controls.

type CacheStats

type CacheStats struct {
	Entries   int
	Bytes     int64
	MaxBytes  int64
	Hits      uint64
	Misses    uint64
	Evictions uint64
}

CacheStats is a PHI-free snapshot of the bounded response cache.

type Client

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

Client is safe for concurrent use.

func NewClient

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

NewClient validates config and returns a bounded, policy-enforcing client.

func (*Client) CacheStats

func (c *Client) CacheStats() CacheStats

CacheStats returns cache occupancy and counters without exposing target URLs.

func (*Client) DecodeFrame

func (c *Client) DecodeFrame(ctx context.Context, request Request, dataset *object.Object) (DecodedFrame, error)

DecodeFrame retrieves and decodes one complete JPEG 2000 or HTJ2K response. JPP/JPT data-bin streams are returned as a stable typed limitation because they require session-level data-bin assembly rather than a still-image codec.

func (*Client) Retrieve

func (c *Client) Retrieve(ctx context.Context, request Request) (Response, error)

Retrieve obtains one bounded representation. Completed and explicitly ranged representations are cached independently by canonical request.

type Config

type Config struct {
	HTTPClient       *http.Client
	Policy           Policy
	MaxResponseBytes int64
	MaxCacheBytes    int64
	MaxRetries       int
	Registry         pixeldata.Registry
	RetryDelay       func(attempt int, response *http.Response) time.Duration
}

Config controls a Client. Supplying HTTPClient is primarily useful for custom trust stores and tests; its transport remains the caller's responsibility. The default transport enforces TLS 1.2 or newer.

type DecodedFrame

type DecodedFrame struct {
	Metadata    pixeldata.Metadata
	Data        []byte
	ContentType string
	CacheHit    bool
}

DecodedFrame is the native frame produced from one complete JPIP response.

type Error

type Error struct {
	Kind        ErrorKind
	Operation   string
	StatusCode  int
	ContentType string
	Limit       int64
	Size        int64
	Err         error
}

Error describes a JPIP failure without retaining the provider URL or its query parameters. Provider URLs can contain short-lived target identifiers and must not become durable diagnostics.

func (*Error) Error

func (e *Error) Error() string

func (*Error) Unwrap

func (e *Error) Unwrap() error

type ErrorKind

type ErrorKind string

ErrorKind is a stable category callers can map to a user-facing diagnostic.

const (
	ErrorKindInvalidRequest         ErrorKind = "invalid-request"
	ErrorKindAuthentication         ErrorKind = "authentication"
	ErrorKindPolicyDenied           ErrorKind = "policy-denied"
	ErrorKindRedirectDenied         ErrorKind = "redirect-denied"
	ErrorKindOffline                ErrorKind = "offline"
	ErrorKindHTTPStatus             ErrorKind = "http-status"
	ErrorKindUnsupportedContentType ErrorKind = "unsupported-content-type"
	ErrorKindResponseTooLarge       ErrorKind = "response-too-large"
	ErrorKindPartialResponse        ErrorKind = "partial-response"
	ErrorKindCorruptResponse        ErrorKind = "corrupt-response"
	ErrorKindIncrementalStream      ErrorKind = "incremental-stream"
	ErrorKindDecode                 ErrorKind = "decode"
)

type Policy

type Policy struct {
	Rules             []Rule
	Credentials       []BasicCredential
	BearerCredentials []BearerCredential
}

Policy is an explicit network allowlist plus origin-bound credentials.

type Region

type Region struct {
	X      int
	Y      int
	Width  int
	Height int
}

Region requests a source region. Width and Height must both be positive when the region is present.

type Request

type Request struct {
	Reference pixeldata.JPIPReference
	Frame     int
	Size      Size
	Region    Region
	Range     *ByteRange
}

Request describes one JPIP representation. Frame is zero-based and becomes the DICOM/JPIP one-based stream query parameter.

type Response

type Response struct {
	Data        []byte
	ContentType string
	Partial     bool
	CacheHit    bool
}

Response is one bounded server representation.

type Rule

type Rule struct {
	Scheme string
	Host   string
	Port   string
}

Rule permits one scheme and host. Port is optional; an empty Port permits any port on the explicitly named host. Wildcards and subdomain matching are intentionally unsupported.

func RuleForHost

func RuleForHost(scheme, host, port string) (Rule, error)

RuleForHost creates a host rule. When port is empty, every port on that explicitly configured host is permitted.

func RuleFromURL

func RuleFromURL(raw string) (Rule, error)

RuleFromURL creates an exact-origin rule from an HTTP(S) URL.

type Size

type Size struct {
	Width  int
	Height int
}

Size requests a decoded resolution. Zero dimensions leave fsiz unspecified.