gittransaction

README

git-transaction

The purpose of this library is to use any git repository of your choice as single source of truth, enabling transaction support.

process

A git transaction follows this workflow (we assume that the repository was already pulled to some specified path):

1. Create new transaction using the factory method of the package
2. Write to the transaction as much as you want. Each write will trigger a commit.
3. Commit the transaction if the transaction has ended.

If something fails, a rollback is triggered and the branch is reset to its initial state. (the state before creating the new transaction)

concept of modes

Currently two modes are planned. One mode (Singlebranch Transaction) is thougt to be the simplest version of a transaction, which just writes to one single branch. This mode is sufficient, as long as only one single instance is working on the repository.

The second mode (Multibranch Transaction) aims to enable multiple instance working on the same

Additional there is a Debug Transaction mode. This mode does not write any transaction or similar and might be useful, during testing.

roadmap

To give you an idea on what is planned for this tool, here is a small roadmap ordered by time of completion ascending. If you have ideas for features you would like to see, don't hesitate to open an issue or even a merge request. The order of implementation can change or a goal can be omitted completely.

1. Singlebranch Transaction
2. Automatically detect writes (which calls write under the hood)
3. Support repositories which require credentials and allow signing transactions (configure key and sign commits)
4. Support ssh (not only http)
5. Multibranch Transaction
6. Automatic conflict resolution (maybe some rule based resolution strategy which can be defined?)

For goal three and four the underlying go-git implementation needs to be extended (for example the ability to merge branches must be implemented). A current version of supported devices can be found in the go-git compatibility documentation

when you should NOT use this library

You should definitely not use this library if:

• you need bleeding edge performance (networking is kind of a bottleneck)
• you can / are willing to use a database
• you need high concurrency guarantees. (since we are using git as underlying technology this is theoretically not a problem but maybe some manual action is required from time to time, which is not what we're looking for I think)

contribute

You want to contribute? I'm grateful for every contribution wether it is an issue, bug or even a merge request. Please take a look at CONTRIBUTING.md for further information.

a note on authentication

When it comes to authenticating yourself or a service account, it gets a bit tricky. Gitlab for example allows to create so called Personal Access Tokens which work over http basic auth, whereas Github also allows using so called Deploy Keys which are based on ssh. Currently only http basic auth is supported. One important difference is that if you are using Github with a personal access token, the token will allow access to all your repositories (global). On Gitlab the acces token is created on the repository (adds a new user to the project, local).

Guides to create personal access tokens for...

• Gitlab
• Github

Documentation

Index

• func New(m MODE, path string, token *Token) (*Context, Transaction, error)
• func SetIdGenerationStrategy(strategy IdGenerationStrategy)
• func SetupCredentials(ctx *Context, token *Token)
• type Context
• type DebugTransaction
  • func (sbt *DebugTransaction) Commit(ctx *Context) error
  • func (sbt *DebugTransaction) Rollback(ctx *Context) error
  • func (sbt *DebugTransaction) Write(ctx *Context) error
• type IdGenerationStrategy
• type MODE
• type PathIdGenerationStrategy
  • func (strategy *PathIdGenerationStrategy) GenerateId(path string) string
• type SinglebranchTransaction
  • func (sbt *SinglebranchTransaction) Commit(ctx *Context) error
  • func (sbt *SinglebranchTransaction) Rollback(ctx *Context) error
  • func (sbt *SinglebranchTransaction) Write(ctx *Context) error
• type Token
• type Transaction
  • func FindTransaction(ctx *Context) Transaction
• type UUIDIdGenerationStrategy
  • func (strategy *UUIDIdGenerationStrategy) GenerateId(seed string) string

Functions

func New

func New(m MODE, path string, token *Token) (*Context, Transaction, error)

creates a new transaction in given mode and path (must be git repo) returns a transaction context and the transaction or an error

func SetIdGenerationStrategy

func SetIdGenerationStrategy(strategy IdGenerationStrategy)

set the id generation strategy which shall be used to generate the transaction ids.

func SetupCredentials

func SetupCredentials(ctx *Context, token *Token)

setup credentials for the given transaction

Types

type Context

type Context struct {
	Id string
	// contains filtered or unexported fields
}

The transaction context holds information about a transaction

type DebugTransaction

type DebugTransaction struct {
	Transaction
}

The debug transaction abstracts a dummy transaction and might be useful for testing or deactivating some transaction while not needing to remove the implementation

func (*DebugTransaction) Commit

func (sbt *DebugTransaction) Commit(ctx *Context) error

On the debug transaction nothing will happen when calling Commit

func (*DebugTransaction) Rollback

func (sbt *DebugTransaction) Rollback(ctx *Context) error

On the debug transaction nothing will happen when calling Rollback

func (*DebugTransaction) Write

func (sbt *DebugTransaction) Write(ctx *Context) error

On the debug transaction nothing will happen when calling Write

type IdGenerationStrategy

type IdGenerationStrategy interface {
	GenerateId(string) string
}

The idGenerationStrategy interface defines the abstraction for creating an id.

type MODE

type MODE int

the mode defines how the transaction is executed

• SINGLEBRANCH: the transaction will be done in the currently active branch

currently only the SINGLEBRANCH option s supported.

const (
	SINGLEBRANCH MODE = 1 << iota
	// MULTIBRANCH
	DEBUG
)

type PathIdGenerationStrategy

type PathIdGenerationStrategy struct {
	IdGenerationStrategy
}

the path id generation strategy

func (*PathIdGenerationStrategy) GenerateId

func (strategy *PathIdGenerationStrategy) GenerateId(path string) string

the id simply represents the path of the underlying repository

type SinglebranchTransaction

type SinglebranchTransaction struct {
	Transaction
	// contains filtered or unexported fields
}

The singlebranch transaction abstracts a git-transaction inside one branch and represents the most simple version of a git transaction.

func (*SinglebranchTransaction) Commit

func (sbt *SinglebranchTransaction) Commit(ctx *Context) error

Commit will write commit the transaction by pushing to the defined repository.

func (*SinglebranchTransaction) Rollback

func (sbt *SinglebranchTransaction) Rollback(ctx *Context) error

Rollback will reset to the state where the branch transaction started. Rollback is called if an error happens during writing or commiting a transaction

func (*SinglebranchTransaction) Write

func (sbt *SinglebranchTransaction) Write(ctx *Context) error

Write will write all current changes to the transaction by creating a commit.

type Token

type Token struct {
	Username string
	Token    string
	Email    string
}

A token represents the properties of an acccess token which are needed to allow its usage for

type Transaction

type Transaction interface {
	Write(*Context) error
	Commit(*Context) error
	Rollback(*Context) error
}

The Transaction interface defines the abstraction of a transaction

func FindTransaction

func FindTransaction(ctx *Context) Transaction

returns a transaction if matching id is found, otherwise nil

type UUIDIdGenerationStrategy

type UUIDIdGenerationStrategy struct {
	IdGenerationStrategy
}

the UUID as id generation strategy

func (*UUIDIdGenerationStrategy) GenerateId

func (strategy *UUIDIdGenerationStrategy) GenerateId(seed string) string

generates an UUID as transaction id. This id will be written in each write allowing to trace what was done inside one transaction