gonduit

package module
v0.6.1 Latest Latest
Warning

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

 Go to latest Published: Nov 26, 2019 License: MIT Imports: 11 Imported by: 0

README

gonduit Build Status GoDoc

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

Getting started

Installing the library

A simple go get should do it:

go get github.com/uber/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
  • differential.getcommitpaths
  • differential.getcommitmessage
  • diffusion.querycommit
  • file.download
  • macro.creatememe
  • maniphest.query
  • maniphest.createtask
  • maniphest.gettasktransactions
  • paste.create
  • paste.query
  • phid.lookup
  • phid.query
  • phriction.info
  • project.query
  • remarkup.process
  • repository.query
  • user.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

Constants

View Source 
const DifferentialGetCommitMessageMethod = "differential.getcommitmessage"

DifferentialGetCommitMessageMethod is method name on Phabricator API.

View Source 
const DifferentialGetCommitPathsMethod = "differential.getcommitpaths"

DifferentialGetCommitPathsMethod is method name on Phabricator API.

View Source 
const DifferentialQueryMethod = "differential.query"

DifferentialQueryMethod is method name on Phabricator API.

Variables

This section is empty.

Functions

This section is empty.

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 DialContext added in v0.4.0 

func DialContext(ctx context.Context, host string, options *core.ClientOptions) (*Conn, error)

DialContext connects to conduit and confirms the API capabilities for future calls, passing the given context through.

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) CallContext added in v0.4.0 

func (c *Conn) CallContext(
	ctx context.Context,
	method string,
	params interface{},
	result interface{},
) error

CallContext allows you to make a raw conduit method call with the given context. 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 added in v0.2.0 

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) ConnectContext added in v0.4.0 

func (c *Conn) ConnectContext(ctx context.Context) error

ConnectContext calls conduit.connect to open an authenticated session for future requests, passing through the given context.

func (*Conn) DifferentialGetCommitMessage added in v0.5.0 

func (c *Conn) DifferentialGetCommitMessage(
	req requests.DifferentialGetCommitMessageRequest,
) (*responses.DifferentialGetCommitMessageResponse, error)

DifferentialGetCommitMessage performs a call to differential.getcommitmessage.

func (*Conn) DifferentialGetCommitPaths added in v0.4.1 

func (c *Conn) DifferentialGetCommitPaths(
	req requests.DifferentialGetCommitPathsRequest,
) (*responses.DifferentialGetCommitPathsResponse, error)

DifferentialGetCommitPaths performs a call to differential.getcommitpaths.

func (*Conn) DifferentialQuery 

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

DifferentialQuery performs a call to differential.query.

func (*Conn) DifferentialQueryDiffs added in v0.4.0 

func (c *Conn) DifferentialQueryDiffs(
	req requests.DifferentialQueryDiffsRequest,
) (*responses.DifferentialQueryDiffsResponse, error)

DifferentialQueryDiffs performs a call to differential.querydiffs.

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 added in v0.2.0 

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

ManiphestCreateTask performs a call to maniphest.createtask.

func (*Conn) ManiphestGetTaskTransactions added in v0.3.0 

func (c *Conn) ManiphestGetTaskTransactions(
	req requests.ManiphestGetTaskTransactions,
) (*responses.ManiphestGetTaskTransactionsResponse, error)

func (*Conn) ManiphestQuery 

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

ManiphestQuery performs a call to maniphest.query.

func (*Conn) ManiphestSearch added in v0.3.3 

func (c *Conn) ManiphestSearch(
	req requests.ManiphestSearchRequest,
) (*responses.ManiphestSearchResponse, error)

ManiphestSearch performs a call to maniphest.search.

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) PhrictionInfo added in v0.3.0 

func (c *Conn) PhrictionInfo(
	req requests.PhrictionInfoRequest,
) (*responses.PhrictionInfoResponse, error)

PhrictionInfo performs a call to phriction.info

func (*Conn) ProjectQuery 

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

ProjectQuery performs a call to project.query.

func (*Conn) RemarkupProcess added in v0.3.0 

func (c *Conn) RemarkupProcess(
	req requests.RemarkupProcessRequest,
) (*responses.RemarkupProcessResponse, error)

RemarkupProcess performs a call to remarkup.process

func (*Conn) RepositoryQuery 

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

RepositoryQuery performs a call to repository.query.

func (*Conn) UserQuery added in v0.3.0 

func (c *Conn) UserQuery(
	req requests.UserQueryRequest,
) (*responses.UserQueryResponse, error)

UserQuery performs a call to differential.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.

func (*Dialer) DialContext added in v0.4.0 

func (d *Dialer) DialContext(
	ctx context.Context,
	host string,
	options *core.ClientOptions,
) (*Conn, error)

DialContext connects to conduit and confirms the API capabilities for future calls, passing the given context through.

Source Files

View all Source files

Directories

Path Synopsis
test
server

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.