Documentation ¶
Overview ¶
Package centraldogma provides a Go client for accessing Central Dogma. Visit https://line.github.io/centraldogma/ to learn more about Central Dogma.
Usage:
import "go.linecorp.com/centraldogma"
Create a client with the username and password, then use the client to access the Central Dogma HTTP APIs. For example:
username := "foo" password := "bar" client, err := centraldogma.NewClientWithToken("https://localhost:443", "myToken", nil) projects, res, err := client.ListProjects(context.Background())
Note that all of the APIs are using the https://godoc.org/context which can pass cancellation and deadlines for handling a request.
Index ¶
- Constants
- Variables
- func DefaultHTTP2Transport(baseURL string) (*http2.Transport, error)
- func DefaultMetricCollectorConfig(name string) (c *metrics.Config)
- func DefaultOAuth2Transport(baseURL, token string, transport http.RoundTripper) (*oauth2.Transport, error)
- func GlobalPrometheusMetricCollector(config *metrics.Config) (m *metrics.Metrics, err error)
- func StatsdMetricCollector(config *metrics.Config, addr string) (m *metrics.Metrics, err error)
- func StatsiteMetricCollector(config *metrics.Config, addr string) (m *metrics.Metrics, err error)
- type Author
- type Change
- type ChangeType
- type Client
- func (c *Client) CreateProject(ctx context.Context, name string) (pro *Project, httpStatusCode int, err error)
- func (c *Client) CreateRepository(ctx context.Context, projectName, repoName string) (repo *Repository, httpStatusCode int, err error)
- func (c *Client) FileWatcher(projectName, repoName string, query *Query) (*Watcher, error)
- func (c *Client) GetDiff(ctx context.Context, projectName, repoName, from, to string, query *Query) (change *Change, httpStatusCode int, err error)
- func (c *Client) GetDiffs(ctx context.Context, projectName, repoName, from, to, pathPattern string) (changes []*Change, httpStatusCode int, err error)
- func (c *Client) GetFile(ctx context.Context, projectName, repoName, revision string, query *Query) (entry *Entry, httpStatusCode int, err error)
- func (c *Client) GetFiles(ctx context.Context, projectName, repoName, revision, pathPattern string) (entries []*Entry, httpStatusCode int, err error)
- func (c *Client) GetHistory(ctx context.Context, projectName, repoName, from, to, pathPattern string, ...) (commits []*Commit, httpStatusCode int, err error)
- func (c *Client) ListFiles(ctx context.Context, projectName, repoName, revision, pathPattern string) (entries []*Entry, httpStatusCode int, err error)
- func (c *Client) ListProjects(ctx context.Context) (pros []*Project, httpStatusCode int, err error)
- func (c *Client) ListRemovedProjects(ctx context.Context) (removedPros []*Project, httpStatusCode int, err error)
- func (c *Client) ListRemovedRepositories(ctx context.Context, projectName string) (removedRepos []*Repository, httpStatusCode int, err error)
- func (c *Client) ListRepositories(ctx context.Context, projectName string) (repos []*Repository, httpStatusCode int, err error)
- func (c *Client) NormalizeRevision(ctx context.Context, projectName, repoName, revision string) (normalizedRev int, httpStatusCode int, err error)
- func (c *Client) PurgeProject(ctx context.Context, name string) (httpStatusCode int, err error)
- func (c *Client) PurgeRepository(ctx context.Context, projectName, repoName string) (httpStatusCode int, err error)
- func (c *Client) Push(ctx context.Context, projectName, repoName, baseRevision string, ...) (result *PushResult, httpStatusCode int, err error)
- func (c *Client) RemoveProject(ctx context.Context, name string) (httpStatusCode int, err error)
- func (c *Client) RemoveRepository(ctx context.Context, projectName, repoName string) (httpStatusCode int, err error)
- func (c *Client) RepoWatcher(projectName, repoName, pathPattern string) (*Watcher, error)
- func (c *Client) SecurityEnabled() (bool, error)
- func (c *Client) SetMetricCollector(m *metrics.Metrics)
- func (c *Client) UnremoveProject(ctx context.Context, name string) (pro *Project, httpStatusCode int, err error)
- func (c *Client) UnremoveRepository(ctx context.Context, projectName, repoName string) (repo *Repository, httpStatusCode int, err error)
- func (c *Client) WatchFile(ctx context.Context, projectName, repoName string, query *Query, ...) (result <-chan WatchResult, closer func(), err error)
- func (c *Client) WatchRepository(ctx context.Context, projectName, repoName, pathPattern string, ...) (result <-chan WatchResult, closer func(), err error)
- type Commit
- type CommitMessage
- type Entry
- type EntryContent
- type EntryType
- type Project
- type PushResult
- type Query
- type QueryType
- type Repository
- type WatchListener
- type WatchResult
- type Watcher
Constants ¶
const ( DefaultChannelBuffer = 128 UnknownHttpStatusCode = 0 DefaultClientName = "centralDogmaClient" )
Variables ¶
var ( ErrLatestNotSet = fmt.Errorf("latest is not set yet") ErrQueryMustBeSet = fmt.Errorf("query should not be nil") ErrWatcherClosed = fmt.Errorf("watcher is closed") ErrTokenEmpty = fmt.Errorf("token should not be empty") ErrTransportMustBeSet = fmt.Errorf("transport should not be nil") ErrTransportMustNotBeOAuth2 = fmt.Errorf("transport cannot be oauth2.Transport") ErrMetricCollectorConfigMustBeSet = fmt.Errorf("metric collector config should not be nil") )
Functions ¶
func DefaultHTTP2Transport ¶
DefaultHTTP2Transport returns a http2.Transport which could be used on cleartext or encrypted connection depending on the scheme of the baseURL.
func DefaultMetricCollectorConfig ¶
DefaultMetricCollectorConfig returns default metric collector config.
func DefaultOAuth2Transport ¶
func DefaultOAuth2Transport(baseURL, token string, transport http.RoundTripper) (*oauth2.Transport, error)
DefaultOAuth2Transport returns an oauth2.Transport which internally uses the specified transport and attaches the specified token to every request using the authorization header. If the transport is a type of oauth2.Transport, it will throw an error.
func GlobalPrometheusMetricCollector ¶
GlobalPrometheusMetricCollector returns global metric collector which sinks to Prometheus metrics endpoint. Be aware that function may cause panic on error.
func StatsdMetricCollector ¶
StatsdMetricCollector returns metric collector which sinks to statsd endpoint.
Types ¶
type Change ¶
type Change struct { Path string `json:"path"` Type ChangeType `json:"type"` Content interface{} `json:"content,omitempty"` }
Change represents a change to commit in the repository.
func (*Change) MarshalJSON ¶
func (*Change) UnmarshalJSON ¶
type ChangeType ¶
type ChangeType int
const ( UpsertJSON ChangeType = iota + 1 UpsertText Remove Rename ApplyJSONPatch ApplyTextPatch )
func (ChangeType) String ¶
func (c ChangeType) String() string
String returns the string value of ChangeType
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
A Client communicates with the Central Dogma server API.
func NewClientWithToken ¶
func NewClientWithToken(baseURL, token string, transport http.RoundTripper) (*Client, error)
NewClientWithToken returns a Central Dogma client which communicates the server at baseURL, using the specified token and transport. If transport is nil, http2.Transport is used by default.
func (*Client) CreateProject ¶
func (c *Client) CreateProject(ctx context.Context, name string) (pro *Project, httpStatusCode int, err error)
CreateProject creates a project.
func (*Client) CreateRepository ¶
func (c *Client) CreateRepository( ctx context.Context, projectName, repoName string) (repo *Repository, httpStatusCode int, err error)
CreateRepository creates a repository.
func (*Client) FileWatcher ¶
FileWatcher returns a Watcher which notifies its listeners when the result of the given Query becomes available or changes. For example:
query := &Query{Path: "/a.json", Type: Identity} watcher := client.FileWatcher("foo", "bar", query) myCh := make(chan interface{}) watcher.Watch(func(revision int, value interface{}) { myCh <- value }) myValue := <-myCh
func (*Client) GetDiff ¶
func (c *Client) GetDiff(ctx context.Context, projectName, repoName, from, to string, query *Query) (change *Change, httpStatusCode int, err error)
GetDiff returns the diff of a file between two revisions. If the from and to are not specified, this will return the diff from the init to the latest revision.
func (*Client) GetDiffs ¶
func (c *Client) GetDiffs(ctx context.Context, projectName, repoName, from, to, pathPattern string) (changes []*Change, httpStatusCode int, err error)
GetDiffs returns the diffs of the files that match the given path pattern. A path pattern is a variant of glob:
- "/**": find all files recursively
- "*.json": find all JSON files recursively
- "/foo/*.json": find all JSON files under the directory /foo
- "/*/foo.txt": find all files named foo.txt at the second depth level
- "*.json,/bar/*.txt": use comma to match any patterns
If the from and to are not specified, this will return the diffs from the init to the latest revision.
func (*Client) GetFile ¶
func (c *Client) GetFile( ctx context.Context, projectName, repoName, revision string, query *Query) (entry *Entry, httpStatusCode int, err error)
GetFile returns the file at the specified revision and path with the specified Query.
func (*Client) GetFiles ¶
func (c *Client) GetFiles(ctx context.Context, projectName, repoName, revision, pathPattern string) (entries []*Entry, httpStatusCode int, err error)
GetFiles returns the files that match the given path pattern. A path pattern is a variant of glob:
- "/**": find all files recursively
- "*.json": find all JSON files recursively
- "/foo/*.json": find all JSON files under the directory /foo
- "/*/foo.txt": find all files named foo.txt at the second depth level
- "*.json,/bar/*.txt": use comma to match any patterns
func (*Client) GetHistory ¶
func (c *Client) GetHistory(ctx context.Context, projectName, repoName, from, to, pathPattern string, maxCommits int) (commits []*Commit, httpStatusCode int, err error)
GetHistory returns the history of the files that match the given path pattern. A path pattern is a variant of glob:
- "/**": find all files recursively
- "*.json": find all JSON files recursively
- "/foo/*.json": find all JSON files under the directory /foo
- "/*/foo.txt": find all files named foo.txt at the second depth level
- "*.json,/bar/*.txt": use comma to match any patterns
If the from and to are not specified, this will return the history from the init to the latest revision.
func (*Client) ListFiles ¶
func (c *Client) ListFiles(ctx context.Context, projectName, repoName, revision, pathPattern string) (entries []*Entry, httpStatusCode int, err error)
ListFiles returns the list of files that match the given path pattern. A path pattern is a variant of glob:
- "/**": find all files recursively
- "*.json": find all JSON files recursively
- "/foo/*.json": find all JSON files under the directory /foo
- "/*/foo.txt": find all files named foo.txt at the second depth level
- "*.json,/bar/*.txt": use comma to match any patterns
func (*Client) ListProjects ¶
ListProjects returns the list of projects.
func (*Client) ListRemovedProjects ¶
func (c *Client) ListRemovedProjects(ctx context.Context) (removedPros []*Project, httpStatusCode int, err error)
ListRemovedProjects returns the list of removed projects.
func (*Client) ListRemovedRepositories ¶
func (c *Client) ListRemovedRepositories( ctx context.Context, projectName string) (removedRepos []*Repository, httpStatusCode int, err error)
ListRemovedRepositories returns the list of the removed repositories which can be unremoved using UnremoveRepository.
func (*Client) ListRepositories ¶
func (c *Client) ListRepositories( ctx context.Context, projectName string) (repos []*Repository, httpStatusCode int, err error)
ListRepositories returns the list of repositories.
func (*Client) NormalizeRevision ¶
func (c *Client) NormalizeRevision( ctx context.Context, projectName, repoName, revision string) (normalizedRev int, httpStatusCode int, err error)
NormalizeRevision converts the relative revision number to the absolute revision number(e.g. -1 -> 3).
func (*Client) PurgeProject ¶
PurgeProject purges a project which was removed before.
func (*Client) PurgeRepository ¶
func (c *Client) PurgeRepository(ctx context.Context, projectName, repoName string) (httpStatusCode int, err error)
PurgeRepository purges a repository which was removed before.
func (*Client) Push ¶
func (c *Client) Push(ctx context.Context, projectName, repoName, baseRevision string, commitMessage *CommitMessage, changes []*Change) (result *PushResult, httpStatusCode int, err error)
Push pushes the specified changes to the repository.
func (*Client) RemoveProject ¶
RemoveProject removes a project. A removed project can be unremoved using UnremoveProject.
func (*Client) RemoveRepository ¶
func (c *Client) RemoveRepository(ctx context.Context, projectName, repoName string) (httpStatusCode int, err error)
RemoveRepository removes a repository. A removed repository can be unremoved using UnremoveRepository.
func (*Client) RepoWatcher ¶
RepoWatcher returns a Watcher which notifies its listeners when the repository that matched the given pathPattern becomes available or changes. For example:
watcher := client.RepoWatcher("foo", "bar", "/*.json") myCh := make(chan interface{}) watcher.Watch(func(revision int, value interface{}) { myCh <- value }) myValue := <-myCh
func (*Client) SecurityEnabled ¶
SecurityEnabled returns whether the security of the server is enabled or not.
func (*Client) SetMetricCollector ¶
SetMetricCollector sets metric collector for the client. For example, with Prometheus:
config := centraldogma.DefaultMetricCollectorConfig("client_name") metricCollector := centraldogma.GlobalPrometheusMetricCollector(config) client.SetMetricCollector(metricCollector)
Or Statsd:
config := centraldogma.DefaultMetricCollectorConfig("client_name") metricCollector, err := centraldogma.StatsdMetricCollector(config, "127.0.0.1:8125") if err != nil { panic(err) } client.SetMetricCollector(metricCollector)
func (*Client) UnremoveProject ¶
func (c *Client) UnremoveProject(ctx context.Context, name string) (pro *Project, httpStatusCode int, err error)
UnremoveProject unremoves a removed project.
func (*Client) UnremoveRepository ¶
func (c *Client) UnremoveRepository( ctx context.Context, projectName, repoName string) (repo *Repository, httpStatusCode int, err error)
UnremoveRepository unremoves a repository.
func (*Client) WatchFile ¶
func (c *Client) WatchFile( ctx context.Context, projectName, repoName string, query *Query, timeout time.Duration, ) (result <-chan WatchResult, closer func(), err error)
WatchFile watches on file changes. The watched result will be returned through the returned channel. The API also provides a manual closer to stop watching and release underlying resources. In short, watching will be stopped in case either context is cancelled or closer is called. Manually closing returned channel is unsafe and may cause sending on closed channel error. Usage:
query := &Query{Path: "/a.json", Type: Identity} ctx := context.Background() changes, closer, err := client.WatchFile(ctx, "foo", "bar", query, 2 * time.Minute) if err != nil { panic(err) } defer closer() // stop watching and release underlying resources. /* close(changes) */ // manually closing is unsafe, don't do this. for { select { case <-ctx.Done(): ... case change := <-changes: // got change json.Unmarshal(change.Entry.Content, &expect) ... } }
func (*Client) WatchRepository ¶
func (c *Client) WatchRepository( ctx context.Context, projectName, repoName, pathPattern string, timeout time.Duration, ) (result <-chan WatchResult, closer func(), err error)
WatchRepository watches on repository changes. The watched result will be returned through the returned channel. The API also provides a manual closer to stop watching and release underlying resources. In short, watching will be stopped in case either context is cancelled or closer is called. Manually closing returned channel is unsafe and may cause sending on closed channel error. Usage:
query := &Query{Path: "/a.json", Type: Identity} ctx := context.Background() changes, closer, err := client.WatchRepository(ctx, "foo", "bar", "/*.json", 2 * time.Minute) if err != nil { panic(err) } defer closer() // stop watching and release underlying resources. /* close(changes) */ // manually closing is unsafe, don't do this. for { select { case <-ctx.Done(): ... case change := <-changes: // got change json.Unmarshal(change.Entry.Content, &expect) ... } }
type Commit ¶
type Commit struct { Revision int `json:"revision"` Author Author `json:"author,omitempty"` CommitMessage CommitMessage `json:"commitMessage,omitempty"` PushedAt string `json:"pushedAt,omitempty"` }
Commit represents a commit in the repository.
type CommitMessage ¶
type CommitMessage struct { Summary string `json:"summary"` Detail string `json:"detail,omitempty"` Markup string `json:"markup,omitempty"` }
CommitMessages represents a commit message in the repository.
type Entry ¶
type Entry struct { Path string `json:"path"` Type EntryType `json:"type"` // can be JSON, TEXT or DIRECTORY Content EntryContent `json:"content,omitempty"` Revision int `json:"revision,omitempty"` URL string `json:"url,omitempty"` ModifiedAt string `json:"modifiedAt,omitempty"` }
Entry represents an entry in the repository.
func (*Entry) MarshalJSON ¶
func (*Entry) UnmarshalJSON ¶
type EntryContent ¶
type EntryContent []byte
EntryContent represents the content of an entry
func (*EntryContent) UnmarshalJSON ¶
func (e *EntryContent) UnmarshalJSON(b []byte) error
type Project ¶
type Project struct { Name string `json:"name"` Creator Author `json:"creator,omitempty"` URL string `json:"url,omitempty"` CreatedAt string `json:"createdAt,omitempty"` }
Project represents a project in the Central Dogma server.
type PushResult ¶
PushResult represents a result of push in the repository.
type Query ¶
type Query struct { Path string // QueryType can be "identity" or "json_path". "identity" is used to retrieve the content as it is. // "json_path" applies a series of JSON path to the content. // See https://github.com/json-path/JsonPath/blob/master/README.md Type QueryType Expressions []string }
Query specifies a query on a file.
type Repository ¶
type Repository struct { Name string `json:"name"` Creator Author `json:"creator,omitempty"` HeadRevision int `json:"headRevision,omitempty"` URL string `json:"url,omitempty"` CreatedAt string `json:"createdAt,omitempty"` }
Repository represents a repository in the Central Dogma server.
type WatchResult ¶
type WatchResult struct { Revision int `json:"revision"` Entry Entry `json:"entry,omitempty"` HttpStatusCode int Err error }
WatchResult represents a result from watch operation.
type Watcher ¶
type Watcher struct {
// contains filtered or unexported fields
}
Watcher watches the changes of a repository or a file.
func (*Watcher) AwaitInitialValue ¶
func (w *Watcher) AwaitInitialValue() *WatchResult
AwaitInitialValue awaits for the initial value to be available.
func (*Watcher) AwaitInitialValueWith ¶
func (w *Watcher) AwaitInitialValueWith(timeout time.Duration) *WatchResult
AwaitInitialValueWith awaits for the initial value to be available during the specified timeout.
func (*Watcher) Close ¶
func (w *Watcher) Close()
Close stops watching the file specified in the Query or the pathPattern in the repository.
func (*Watcher) Latest ¶
func (w *Watcher) Latest() *WatchResult
Latest returns the latest Revision and value of WatchFile() or WatchRepository() result.
func (*Watcher) Watch ¶
func (w *Watcher) Watch(listener WatchListener) error
Watch registers a func that will be invoked when the value of the watched entry becomes available or changes.