jirasrv

jirasrv is a typed HTTP client foundation for Jira Server REST integrations, with method-aware retries and validated payloads.

-
Updated:

Table of contents

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/jirasrv"

A client foundation for the Jira Server REST API, with typed models for the common payloads: issues, transitions, comments, users, visibility, properties and metadata.

c, err := jirasrv.New(addr, token)

err = c.SendRequest(ctx, method, path, body, &result)

A foundation, not a wrapper for every endpoint

The Jira REST API is large, and versions differ between deployments. Rather than modelling every endpoint, the package handles the plumbing and exposes SendRequest as a generic typed entry point.

What it takes care of on each call:

  • composing the API base path (/rest/api/2)
  • bearer-token authentication headers
  • JSON encoding and content headers
  • payload validation
  • method-aware retry behaviour
  • health probing

So reaching an endpoint the typed models do not cover is a SendRequest call with your own request and response types, rather than a fork or a second client.

The typed models cover what integrations actually use: creating issues, moving them through transitions, adding comments, and setting properties.

Jira Server, not Jira Cloud

The base path is /rest/api/2, which is Jira Server and Data Center. Jira Cloud has diverged, with a different authentication model and different endpoint shapes, so this is not the client for a Cloud instance.

Authentication is a bearer token, which for Jira Server means a Personal Access Token.

Retries depend on the method

Retry behaviour is method-aware, which is the same distinction httpretrier makes and for the same reason.

A GET that fails can be retried freely. A POST that times out is ambiguous: the request may have been received and processed with only the response lost, so retrying can create a second issue or add a duplicate comment. Applying one retry policy to both is how integrations end up filing the same ticket three times.

WithRetryAttempts and WithRetryDelay tune the policy.

Timeouts are split

WithTimeout bounds a request; WithPingTimeout bounds the health check.

They differ because their jobs differ. A Jira request against a busy instance can legitimately take seconds, while a health check needs to answer inside whatever budget the orchestrator allows. One shared timeout forces a choice between a health check that hangs and requests that are cut short.

Client.HealthCheck satisfies the healthcheck contract, and WithHTTPClient injects a transport or a mock.

Timestamps

Jira’s timestamp format is neither RFC3339 nor anything else the standard library parses directly, which is why timeutil carries a TJira layout type. A field declared timeutil.DateTime[timeutil.TJira] round-trips Jira timestamps with no custom marshaller at the call site.

Validation before sending

Request payloads are validated through validator before the network call.

Jira rejects a malformed payload with an error naming a field in its own terms, which does not always map cleanly to the struct you sent. Validating locally fails at the call site with the field you actually got wrong.

Dependencies

Reaches the validation stack through validator, plus timeutil.