docker

Documentation

Overview

Copyright 2020 The Matrix.org Foundation C.I.C.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Copyright 2020 The Matrix.org Foundation C.I.C.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Index

• Constants
• Variables
• type Builder
  • func NewBuilder(cfg *config.Complement) (*Builder, error)
  • func (d *Builder) Cleanup()
  • func (d *Builder) ConstructBlueprint(bprint b.Blueprint) error
  • func (d *Builder) ConstructBlueprintIfNotExist(bprint b.Blueprint) error
• type Deployer
  • func NewDeployer(deployNamespace string, cfg *config.Complement) (*Deployer, error)
  • func (d *Deployer) CreateDirtyDeployment() (*Deployment, error)
  • func (d *Deployer) CreateDirtyServer(hsName string) (*HomeserverDeployment, error)
  • func (d *Deployer) Deploy(ctx context.Context, blueprintName string) (*Deployment, error)
  • func (d *Deployer) Destroy(dep *Deployment, printServerLogs bool, testName string, failed bool)
  • func (d *Deployer) PauseServer(hsDep *HomeserverDeployment) error
  • func (d *Deployer) PrintLogs(dep *Deployment)
  • func (d *Deployer) Restart(hsDep *HomeserverDeployment) error
  • func (d *Deployer) StartServer(hsDep *HomeserverDeployment) error
  • func (d *Deployer) StopServer(hsDep *HomeserverDeployment) error
  • func (d *Deployer) UnpauseServer(hsDep *HomeserverDeployment) error
• type Deployment
  • func (d *Deployment) AppServiceUser(t ct.TestLike, hsName, appServiceUserID string) *client.CSAPI
  • func (d *Deployment) ContainerID(t ct.TestLike, hsName string) string
  • func (d *Deployment) Destroy(t ct.TestLike)
  • func (d *Deployment) DestroyAtCleanup()
  • func (d *Deployment) GetConfig() *config.Complement
  • func (d *Deployment) Login(t ct.TestLike, hsName string, existing *client.CSAPI, opts helpers.LoginOpts) *client.CSAPI
  • func (d *Deployment) Network() string
  • func (d *Deployment) PauseServer(t ct.TestLike, hsName string)
  • func (d *Deployment) Register(t ct.TestLike, hsName string, opts helpers.RegistrationOpts) *client.CSAPI
  • func (d *Deployment) Restart(t ct.TestLike) error
  • func (d *Deployment) RoundTripper() http.RoundTripper
  • func (d *Deployment) StartServer(t ct.TestLike, hsName string)
  • func (d *Deployment) StopServer(t ct.TestLike, hsName string)
  • func (d *Deployment) UnauthenticatedClient(t ct.TestLike, hsName string) *client.CSAPI
  • func (d *Deployment) UnpauseServer(t ct.TestLike, hsName string)
• type HomeserverDeployment
  • func (hsDep *HomeserverDeployment) SetEndpoints(baseURL string, fedBaseURL string)
• type RoundTripper
  • func (t *RoundTripper) RoundTrip(req *http.Request) (*http.Response, error)

Constants

const (
	MountCACertPath     = "/complement/ca/ca.crt"
	MountCAKeyPath      = "/complement/ca/ca.key"
	MountAppServicePath = "/complement/appservice/" // All registration files sit here
)

Variables

var (
	// HostnameRunningDocker is the hostname of the docker daemon from the perspective of Complement.
	HostnameRunningDocker = "localhost"
	// HostnameRunningComplement is the hostname of Complement from the perspective of a Homeserver.
	HostnameRunningComplement = "host.docker.internal"
)

Types

type Builder

type Builder struct {
	Config *config.Complement
	Docker *client.Client
}

func NewBuilder

func NewBuilder(cfg *config.Complement) (*Builder, error)

func (*Builder) Cleanup

func (d *Builder) Cleanup()

func (*Builder) ConstructBlueprint

func (d *Builder) ConstructBlueprint(bprint b.Blueprint) error

func (*Builder) ConstructBlueprintIfNotExist

func (d *Builder) ConstructBlueprintIfNotExist(bprint b.Blueprint) error

type Deployer

type Deployer struct {
	DeployNamespace string
	Docker          *client.Client
	Counter         int
	// contains filtered or unexported fields
}

func NewDeployer

func NewDeployer(deployNamespace string, cfg *config.Complement) (*Deployer, error)

func (*Deployer) CreateDirtyDeployment

func (d *Deployer) CreateDirtyDeployment() (*Deployment, error)

CreateDirtyDeployment creates a clean HS without any blueprints. More HSes can be added later via CreateDirtyServer()

func (*Deployer) CreateDirtyServer

func (d *Deployer) CreateDirtyServer(hsName string) (*HomeserverDeployment, error)

CreateDirtyServer creates a new dirty server on the dirty network, creating one if needed. This homeserver should be added to the dirty deployment. The hsName should start as 'hs1', then 'hs2' ... 'hsN'.

func (*Deployer) Deploy

func (d *Deployer) Deploy(ctx context.Context, blueprintName string) (*Deployment, error)

func (*Deployer) Destroy

func (d *Deployer) Destroy(dep *Deployment, printServerLogs bool, testName string, failed bool)

Destroy a deployment. This will kill all running containers.

func (*Deployer) PauseServer

func (d *Deployer) PauseServer(hsDep *HomeserverDeployment) error

func (*Deployer) PrintLogs

func (d *Deployer) PrintLogs(dep *Deployment)

func (*Deployer) Restart

func (d *Deployer) Restart(hsDep *HomeserverDeployment) error

Restart a homeserver deployment.

func (*Deployer) StartServer

func (d *Deployer) StartServer(hsDep *HomeserverDeployment) error

func (*Deployer) StopServer

func (d *Deployer) StopServer(hsDep *HomeserverDeployment) error

func (*Deployer) UnpauseServer

func (d *Deployer) UnpauseServer(hsDep *HomeserverDeployment) error

type Deployment

type Deployment struct {
	// The Deployer which was responsible for this deployment
	Deployer *Deployer
	// The name of the deployed blueprint
	BlueprintName string
	// Set to true if this deployment is a dirty deployment and so should not be destroyed.
	Dirty bool
	// A map of HS name to a HomeserverDeployment
	HS     map[string]*HomeserverDeployment
	Config *config.Complement
	// contains filtered or unexported fields
}

Deployment is the complete instantiation of a Blueprint, with running containers for each homeserver in the Blueprint.

func (*Deployment) AppServiceUser

func (d *Deployment) AppServiceUser(t ct.TestLike, hsName, appServiceUserID string) *client.CSAPI

AppServiceUser returns a client for the given app service user ID. The HS in question must have an appservice hooked up to it already. TODO: REMOVE

func (*Deployment) ContainerID

func (d *Deployment) ContainerID(t ct.TestLike, hsName string) string

func (*Deployment) Destroy

func (d *Deployment) Destroy(t ct.TestLike)

Destroy the entire deployment. Destroys all running containers. If `printServerLogs` is true, will print container logs before killing the container.

func (*Deployment) DestroyAtCleanup

func (d *Deployment) DestroyAtCleanup()

DestroyAtCleanup destroys the entire deployment. It should be called at cleanup time for dirty deployments only. Handles configuration options for things which should run at container destroy time, like post-run scripts and printing logs.

func (*Deployment) GetConfig

func (d *Deployment) GetConfig() *config.Complement

func (*Deployment) Login

func (d *Deployment) Login(t ct.TestLike, hsName string, existing *client.CSAPI, opts helpers.LoginOpts) *client.CSAPI

func (*Deployment) Network

func (d *Deployment) Network() string

func (*Deployment) PauseServer

func (d *Deployment) PauseServer(t ct.TestLike, hsName string)

func (*Deployment) Register

func (d *Deployment) Register(t ct.TestLike, hsName string, opts helpers.RegistrationOpts) *client.CSAPI

func (*Deployment) Restart

func (d *Deployment) Restart(t ct.TestLike) error

Restart a deployment.

func (*Deployment) RoundTripper

func (d *Deployment) RoundTripper() http.RoundTripper

func (*Deployment) StartServer

func (d *Deployment) StartServer(t ct.TestLike, hsName string)

func (*Deployment) StopServer

func (d *Deployment) StopServer(t ct.TestLike, hsName string)

func (*Deployment) UnauthenticatedClient

func (d *Deployment) UnauthenticatedClient(t ct.TestLike, hsName string) *client.CSAPI

func (*Deployment) UnpauseServer

func (d *Deployment) UnpauseServer(t ct.TestLike, hsName string)

type HomeserverDeployment

type HomeserverDeployment struct {
	BaseURL      string            // e.g http://localhost:38646
	FedBaseURL   string            // e.g https://localhost:48373
	ContainerID  string            // e.g 10de45efba
	AccessTokens map[string]string // e.g { "@alice:hs1": "myAcc3ssT0ken" }

	ApplicationServices map[string]string // e.g { "my-as-id": "id: xxx\nas_token: xxx ..."} }
	DeviceIDs           map[string]string // e.g { "@alice:hs1": "myDeviceID" }

	// track all clients so if Restart() is called we can repoint to the new high-numbered port
	CSAPIClients      []*client.CSAPI
	CSAPIClientsMutex sync.Mutex
	// The docker network this HS is connected to.
	// Useful if you want to connect other containers to the same network.
	Network string
	// contains filtered or unexported fields
}

HomeserverDeployment represents a running homeserver in a container.

func (*HomeserverDeployment) SetEndpoints

func (hsDep *HomeserverDeployment) SetEndpoints(baseURL string, fedBaseURL string)

Updates the client and federation base URLs of the homeserver deployment.

type RoundTripper

type RoundTripper struct {
	Deployment *Deployment
}

RoundTripper is a round tripper that maps https://hs1 to the federation port of the container e.g https://localhost:35352

func (*RoundTripper) RoundTrip

func (t *RoundTripper) RoundTrip(req *http.Request) (*http.Response, error)