Document package architecture (#972)

to make it easier for devs to find the right place for code

close #655

Co-authored-by: Anbraten <anton@ju60.de>
Co-authored-by: qwerty287 <80460567+qwerty287@users.noreply.github.com>

docs/docs/92-development/05-architecture.md

@@ -6,4 +6,44 @@
 
 ## System architecture
 
+### main package hirarchie
+
+| package    | meaning                                                      | imports
+|------------|--------------------------------------------------------------|----------
+| `cmd/**`   | parse commanline args & environment to stat server/cli/agent | all other
+| `agent/**` | code only agent (remote worker) will need                    | `pipeline`, `shared`
+| `cli/**`   | code only cli tool does need                                 | `pipeline`, `shared`, `woodpecker-go`
+| `server/**`| code only server will need                                   | `pipeline`, `shared`
+| `shared/**`| code shared for all three main tools (go help utils)         | only std and external libs
+| `woodpecker-go/**` | go client for server rest api                        | std
+
+### Server
+
+| package             | meaning                                         | imports
+|---------------------|-------------------------------------------------|----------
+| `server/api/**`     | handle web requests from `server/router`        | `pipeline`, `../badges`, `../ccmenue`, `../logging`, `../model`, `../pubsub`, `../queue`, `../remote`, `../shared`, `../store`, `shared`, (TODO: mv `server/router/middleware/session`)
+| `server/badges/**`  | generate svg badges for pipelines               | `../model`
+| `server/ccmenu/**`  | generate xml ccmenu for pipelines               | `../model`
+| `server/grpc/**`    | gRPC server agents can connect to               | `pipeline/rpc/**`, `../logging`, `../model`, `../pubsub`, `../queue`, `../remote`, `../pipeline`, `../store`
+| `server/logging/**` | logging lib for gPRC server to stream logs while running | std
+| `server/model/**`   | structs for store (db) and api (json)           | std
+| `server/plugins/**` | plugins for server                              | `../model`, `../remote`
+| `server/pipeline/**`| orchistrate pipelines                          | `pipeline`, `../model`, `../pubsub`, `../queue`, `../remote`, `../store`, `../plugins`
+| `server/pubsub/**`  | pubsub lib for server to push changes to the WebUI | std
+| `server/queue/**`   | queue lib for server where agents pull new pipelines from via gRPC | `server/model`
+| `server/remote/**`  | remote lib for server to connect and handle forge specific stuff | `shared`, `server/model`
+| `server/router/**`  | handle requests to REST API (and all middleware) and serve UI and WebUI config | `shared`, `../api`, `../model`, `../remote`, `../store`, `../web`
+| `server/store/**`   | handle database                                 | `server/model`
+| `server/shared/**`  | TODO: move and split [#974](https://github.com/woodpecker-ci/woodpecker/issues/974) |
+| `server/web/**`     | server SPA                                      |
+
+* `../` = `server/`
+
+
+### Agent
+
+TODO
+
+### CLI
+
 TODO

server/model/build.go

@@ -57,3 +57,7 @@ type Build struct {
 func (Build) TableName() string {
 	return "builds"
 }
+
+type UpdateBuildStore interface {
+	UpdateBuild(*Build) error
+}

server/model/proc.go

@@ -48,6 +48,10 @@ type Proc struct {
 	Children []*Proc           `json:"children,omitempty"   xorm:"-"`
 }
 
+type UpdateProcStore interface {
+	ProcUpdate(*Proc) error
+}
+
 // TableName return database table name for xorm
 func (Proc) TableName() string {
 	return "procs"

server/shared/buildStatus.go

@@ -20,37 +20,35 @@ import (
 	"github.com/woodpecker-ci/woodpecker/server/model"
 )
 
-type UpdateBuildStore interface {
+// TODO(974) move to server/pipeline/*
-	UpdateBuild(*model.Build) error
-}
 
-func UpdateToStatusRunning(store UpdateBuildStore, build model.Build, started int64) (*model.Build, error) {
+func UpdateToStatusRunning(store model.UpdateBuildStore, build model.Build, started int64) (*model.Build, error) {
 	build.Status = model.StatusRunning
 	build.Started = started
 	return &build, store.UpdateBuild(&build)
 }
 
-func UpdateToStatusPending(store UpdateBuildStore, build model.Build, reviewer string) (*model.Build, error) {
+func UpdateToStatusPending(store model.UpdateBuildStore, build model.Build, reviewer string) (*model.Build, error) {
 	build.Reviewer = reviewer
 	build.Status = model.StatusPending
 	build.Reviewed = time.Now().Unix()
 	return &build, store.UpdateBuild(&build)
 }
 
-func UpdateToStatusDeclined(store UpdateBuildStore, build model.Build, reviewer string) (*model.Build, error) {
+func UpdateToStatusDeclined(store model.UpdateBuildStore, build model.Build, reviewer string) (*model.Build, error) {
 	build.Reviewer = reviewer
 	build.Status = model.StatusDeclined
 	build.Reviewed = time.Now().Unix()
 	return &build, store.UpdateBuild(&build)
 }
 
-func UpdateStatusToDone(store UpdateBuildStore, build model.Build, status model.StatusValue, stopped int64) (*model.Build, error) {
+func UpdateStatusToDone(store model.UpdateBuildStore, build model.Build, status model.StatusValue, stopped int64) (*model.Build, error) {
 	build.Status = status
 	build.Finished = stopped
 	return &build, store.UpdateBuild(&build)
 }
 
-func UpdateToStatusError(store UpdateBuildStore, build model.Build, err error) (*model.Build, error) {
+func UpdateToStatusError(store model.UpdateBuildStore, build model.Build, err error) (*model.Build, error) {
 	build.Error = err.Error()
 	build.Status = model.StatusError
 	build.Started = time.Now().Unix()
@@ -58,7 +56,7 @@ func UpdateToStatusError(store UpdateBuildStore, build model.Build, err error) (
 	return &build, store.UpdateBuild(&build)
 }
 
-func UpdateToStatusKilled(store UpdateBuildStore, build model.Build) (*model.Build, error) {
+func UpdateToStatusKilled(store model.UpdateBuildStore, build model.Build) (*model.Build, error) {
 	build.Status = model.StatusKilled
 	build.Finished = time.Now().Unix()
 	return &build, store.UpdateBuild(&build)

server/shared/buildStatus_test.go

@@ -22,6 +22,8 @@ import (
 	"github.com/woodpecker-ci/woodpecker/server/model"
 )
 
+// TODO(974) move to server/pipeline/*
+
 type mockUpdateBuildStore struct{}
 
 func (m *mockUpdateBuildStore) UpdateBuild(build *model.Build) error {

server/shared/configFetcher.go

@@ -18,6 +18,8 @@ type ConfigFetcher interface {
 	Fetch(ctx context.Context) (files []*remote.FileMeta, err error)
 }
 
+// TODO(974) move to new package
+
 type configFetcher struct {
 	remote          remote.Remote
 	user            *model.User

server/shared/configFetcher_test.go

@@ -23,6 +23,8 @@ import (
 	"github.com/woodpecker-ci/woodpecker/server/shared"
 )
 
+// TODO(974) move to new package
+
 func TestFetch(t *testing.T) {
 	t.Parallel()
 

server/shared/procBuilder.go

@@ -35,6 +35,8 @@ import (
 	"github.com/woodpecker-ci/woodpecker/server/remote"
 )
 
+// TODO(974) move to pipeline/*
+
 // ProcBuilder Takes the hook data and the yaml and returns in internal data model
 type ProcBuilder struct {
 	Repo  *model.Repo

server/shared/procBuilder_test.go

@@ -22,6 +22,8 @@ import (
 	"github.com/woodpecker-ci/woodpecker/server/remote"
 )
 
+// TODO(974) move to pipeline/*
+
 func TestMultilineEnvsubst(t *testing.T) {
 	t.Parallel()
 

server/shared/procStatus.go

@@ -21,11 +21,9 @@ import (
 	"github.com/woodpecker-ci/woodpecker/server/model"
 )
 
-type UpdateProcStore interface {
+// TODO(974) move to server/pipeline/*
-	ProcUpdate(*model.Proc) error
-}
 
-func UpdateProcStatus(store UpdateProcStore, proc model.Proc, state rpc.State, started int64) (*model.Proc, error) {
+func UpdateProcStatus(store model.UpdateProcStore, proc model.Proc, state rpc.State, started int64) (*model.Proc, error) {
 	if state.Exited {
 		proc.Stopped = state.Finished
 		proc.ExitCode = state.ExitCode
@@ -48,13 +46,13 @@ func UpdateProcStatus(store UpdateProcStore, proc model.Proc, state rpc.State, s
 	return &proc, store.ProcUpdate(&proc)
 }
 
-func UpdateProcToStatusStarted(store UpdateProcStore, proc model.Proc, state rpc.State) (*model.Proc, error) {
+func UpdateProcToStatusStarted(store model.UpdateProcStore, proc model.Proc, state rpc.State) (*model.Proc, error) {
 	proc.Started = state.Started
 	proc.State = model.StatusRunning
 	return &proc, store.ProcUpdate(&proc)
 }
 
-func UpdateProcToStatusSkipped(store UpdateProcStore, proc model.Proc, stopped int64) (*model.Proc, error) {
+func UpdateProcToStatusSkipped(store model.UpdateProcStore, proc model.Proc, stopped int64) (*model.Proc, error) {
 	proc.State = model.StatusSkipped
 	if proc.Started != 0 {
 		proc.State = model.StatusSuccess // for daemons that are killed
@@ -63,7 +61,7 @@ func UpdateProcToStatusSkipped(store UpdateProcStore, proc model.Proc, stopped i
 	return &proc, store.ProcUpdate(&proc)
 }
 
-func UpdateProcStatusToDone(store UpdateProcStore, proc model.Proc, state rpc.State) (*model.Proc, error) {
+func UpdateProcStatusToDone(store model.UpdateProcStore, proc model.Proc, state rpc.State) (*model.Proc, error) {
 	proc.Stopped = state.Finished
 	proc.Error = state.Error
 	proc.ExitCode = state.ExitCode
@@ -78,7 +76,7 @@ func UpdateProcStatusToDone(store UpdateProcStore, proc model.Proc, state rpc.St
 	return &proc, store.ProcUpdate(&proc)
 }
 
-func UpdateProcToStatusKilled(store UpdateProcStore, proc model.Proc) (*model.Proc, error) {
+func UpdateProcToStatusKilled(store model.UpdateProcStore, proc model.Proc) (*model.Proc, error) {
 	proc.State = model.StatusKilled
 	proc.Stopped = time.Now().Unix()
 	if proc.Started == 0 {

server/shared/procStatus_test.go

@@ -22,6 +22,8 @@ import (
 	"github.com/woodpecker-ci/woodpecker/server/model"
 )
 
+// TODO(974) move to server/pipeline/*
+
 type mockUpdateProcStore struct{}
 
 func (m *mockUpdateProcStore) ProcUpdate(build *model.Proc) error {

server/shared/userSyncer.go

@@ -24,6 +24,8 @@ import (
 	"github.com/woodpecker-ci/woodpecker/server/store"
 )
 
+// TODO(974) move to new package
+
 // UserSyncer syncs the user repository and permissions.
 type UserSyncer interface {
 	Sync(ctx context.Context, user *model.User) error