gonduit

README

gonduit

A Go client for interacting with Phabricator via the Conduit API.

Currently this library is incomplete. This is a fork from https://github.com/jpoehls/go-conduit with support for some additional call and options. The library is a bit messy right now.

Getting started

Installing the library

A simple go get should do it:

go get github.com/etcinit/gonduit

For reproducible builds, you can also use Glide.

Authentication

Gonduit supports the following authentication methods:

• tokens
• session

If you are creating a bot/automated script, you should create a bot account on Phabricator rather than using your own.

tokens: Getting a conduit API token

To get an API token, go to https://{PHABRICATOR_URL}/settings/panel/apitokens/. From there, you should be able to create and copy an API token to use with the client.

session: Getting a conduit certificate

To get a conduit certificate, go to https://{PHABRICATOR_URL}/settings/panel/conduit. From there, you should be able to copy your certificate.

Basic Usage

Connecting

To construct an instance of a Gonduit client, use Dial with the URL of your install and an options object. Dial connects to the API, checks compatibility, and finally creates a Client instance:

client, err := gonduit.Dial(
	"https://phabricator.psyduck.info",
	&core.ClientOptions{
		APIToken: "api-SOMETOKEN"
	}
)

While certificate-based/session authentication is being deprecated in favor of API tokens, Gonduit still supports certificates in case you are using an older install. After calling Dial, you will also need to call client.Connect to create a session. The session key will be stored in the client itself and it will automatically be passed on on every subsequent request.

client, err := gonduit.Dial(
	"https://phabricator.psyduck.info",
	&core.ClientOptions{
		Cert: "CERTIFICATE",
		CertUser: "USERNAME",
	}
)

err = client.Connect()

Errors

Any conduit error response will be returned as a core.ConduitError type:

client, err := gonduit.Dial(
	"https://phabricator.psyduck.info",
	&core.ClientOptions{
		APIToken: "api-SOMETOKEN"
	}
)

ce, ok := err.(*core.ConduitError)
if ok {
	println("code: " + ce.Code())
	println("info: " + ce.Info())
}

// Or, use the built-in utility function:
if core.IsConduitError(err) {
	// do something else
}

Supported Calls

All the supported API calls are available in the Client struct. Every function is named after the Conduit method they call: For phid.query, we have Client.PHIDQuery. The same applies for request and responses: requests.PHIDQueryRequest and responses.PHIDQueryResponse.

Additionally, every general request method has the following signature:

func (c *Conn) ConduitMethodName(req Request) (Response, error)

Some methods may also have specialized functions, you should refer the GoDoc for more information on how to use them.

List of supported calls:

• conduit.connect
• conduit.query
• differential.query
• diffusion.querycommit
• file.download
• macro.creatememe
• maniphest.query
• maniphest.createtask
• paste.create
• paste.query
• phid.lookup
• phid.query
• project.query
• repository.query

Arbitrary calls

If you need to call an API method that is not supported by this client library, you can use the client.Call method to make arbitrary calls.

You will need to provide a struct with the request body and a struct for the response. The request has to be able to be able to be serialized into JSON, and the response has be able to be unserialized from JSON.

Request structs must also "extend" the requests.Request struct, which contains additional fields needed to authenticate with Conduit.

type phidLookupRequest struct {
	Names   []string         `json:"names"`
	requests.Request // Includes __conduit__ field needed for authentication.
}

type phidLookupResponse map[string]*struct{
	URI      string `json:"uri"`
	FullName string `json:"fullName"`
	Status   string `json:"status"`
}

req := &phidLookupRequest {
	Names: []string{"T1"},
	Session: client.Session,
}
var res phidLookupResponse

err := client.Call("phid.lookup", req, &res)

Documentation

Overview

Package gonduit provides a client for Phabricator's Conduit API.

Index

• type Conn
  • func Dial(host string, options *core.ClientOptions) (*Conn, error)
  • func (c *Conn) Call(method string, params interface{}, result interface{}) error
  • func (c *Conn) ConduitQuery() (*responses.ConduitQueryResponse, error)
  • func (c *Conn) Connect() error
  • func (c *Conn) DifferentialQuery(req requests.DifferentialQueryRequest) (*responses.DifferentialQueryResponse, error)
  • func (c *Conn) DiffusionQueryCommits(req requests.DiffusionQueryCommitsRequest) (*responses.DiffusionQueryCommitsResponse, error)
  • func (c *Conn) FileDownload(req requests.FileDownloadRequest) (*responses.FileDownloadResponse, error)
  • func (c *Conn) MacroCreateMeme(req requests.MacroCreateMemeRequest) (*responses.MacroCreateMemeResponse, error)
  • func (c *Conn) ManiphestCreateTask(req requests.ManiphestCreateTaskRequest) (*entities.ManiphestTask, error)
  • func (c *Conn) ManiphestQuery(req requests.ManiphestQueryRequest) (*responses.ManiphestQueryResponse, error)
  • func (c *Conn) PHIDLookup(req requests.PHIDLookupRequest) (responses.PHIDLookupResponse, error)
  • func (c *Conn) PHIDLookupSingle(name string) (*entities.PHIDResult, error)
  • func (c *Conn) PHIDQuery(req requests.PHIDQueryRequest) (responses.PHIDQueryResponse, error)
  • func (c *Conn) PHIDQuerySingle(phid string) (*entities.PHIDResult, error)
  • func (c *Conn) PasteCreate(req *requests.PasteCreateRequest) (responses.PasteCreateResponse, error)
  • func (c *Conn) PasteQuery(req *requests.PasteQueryRequest) (responses.PasteQueryResponse, error)
  • func (c *Conn) ProjectQuery(req requests.ProjectQueryRequest) (*responses.ProjectQueryResponse, error)
  • func (c *Conn) RepositoryQuery(req requests.RepositoryQueryRequest) (*responses.RepositoryQueryResponse, error)
• type Dialer
  • func (d *Dialer) Dial(host string, options *core.ClientOptions) (*Conn, error)

Types

type Conn

type Conn struct {
	Session *entities.Session
	// contains filtered or unexported fields
}

Conn is a connection to the conduit API.

func Dial

func Dial(host string, options *core.ClientOptions) (*Conn, error)

Dial connects to conduit and confirms the API capabilities for future calls.

func (*Conn) Call

func (c *Conn) Call(
	method string,
	params interface{},
	result interface{},
) error

Call allows you to make a raw conduit method call. Params will be marshalled as JSON and the result JSON will be unmarshalled into the result interface{}.

This is primarily useful for calling conduit endpoints that aren't specifically supported by other methods in this package.

func (*Conn) ConduitQuery

func (c *Conn) ConduitQuery() (*responses.ConduitQueryResponse, error)

ConduitQuery performs a call to conduit.query.

func (*Conn) Connect

func (c *Conn) Connect() error

Connect calls conduit.connect to open an authenticated session for future requests.

func (*Conn) DifferentialQuery

func (c *Conn) DifferentialQuery(
	req requests.DifferentialQueryRequest,
) (*responses.DifferentialQueryResponse, error)

DifferentialQuery performs a call to differential.query.

func (*Conn) DiffusionQueryCommits

func (c *Conn) DiffusionQueryCommits(
	req requests.DiffusionQueryCommitsRequest,
) (*responses.DiffusionQueryCommitsResponse, error)

DiffusionQueryCommits performs a call to diffusion.querycommits.

func (*Conn) FileDownload

func (c *Conn) FileDownload(
	req requests.FileDownloadRequest,
) (*responses.FileDownloadResponse, error)

FileDownload performs a call to file.download.

func (*Conn) MacroCreateMeme

func (c *Conn) MacroCreateMeme(
	req requests.MacroCreateMemeRequest,
) (*responses.MacroCreateMemeResponse, error)

MacroCreateMeme performs a call to macro.creatememe.

func (*Conn) ManiphestCreateTask

func (c *Conn) ManiphestCreateTask(
	req requests.ManiphestCreateTaskRequest,
) (*entities.ManiphestTask, error)

ManiphestCreateTask performs a call to maniphest.createtask.

func (*Conn) ManiphestQuery

func (c *Conn) ManiphestQuery(
	req requests.ManiphestQueryRequest,
) (*responses.ManiphestQueryResponse, error)

ManiphestQuery performs a call to maniphest.query.

func (*Conn) PHIDLookup

func (c *Conn) PHIDLookup(
	req requests.PHIDLookupRequest,
) (responses.PHIDLookupResponse, error)

PHIDLookup calls the phid.lookup endpoint.

func (*Conn) PHIDLookupSingle

func (c *Conn) PHIDLookupSingle(name string) (*entities.PHIDResult, error)

PHIDLookupSingle calls the phid.lookup endpoint with a single name.

func (*Conn) PHIDQuery

func (c *Conn) PHIDQuery(
	req requests.PHIDQueryRequest,
) (responses.PHIDQueryResponse, error)

PHIDQuery calls the phid.query endpoint.

func (*Conn) PHIDQuerySingle

func (c *Conn) PHIDQuerySingle(phid string) (*entities.PHIDResult, error)

PHIDQuerySingle calls the phid.query endpoint with a single phid.

func (*Conn) PasteCreate

func (c *Conn) PasteCreate(
	req *requests.PasteCreateRequest,
) (responses.PasteCreateResponse, error)

PasteCreate calls the paste.create endpoint.

func (*Conn) PasteQuery

func (c *Conn) PasteQuery(
	req *requests.PasteQueryRequest,
) (responses.PasteQueryResponse, error)

PasteQuery calls the paste.query endpoint.

func (*Conn) ProjectQuery

func (c *Conn) ProjectQuery(
	req requests.ProjectQueryRequest,
) (*responses.ProjectQueryResponse, error)

ProjectQuery performs a call to project.query.

func (*Conn) RepositoryQuery

func (c *Conn) RepositoryQuery(
	req requests.RepositoryQueryRequest,
) (*responses.RepositoryQueryResponse, error)

RepositoryQuery performs a call to repository.query.

type Dialer

type Dialer struct {
	ClientName        string
	ClientVersion     string
	ClientDescription string
}

A Dialer contains options for connecting to an address.

func (*Dialer) Dial

func (d *Dialer) Dial(
	host string,
	options *core.ClientOptions,
) (*Conn, error)

Dial connects to conduit and confirms the API capabilities for future calls.